feat(snaps-vitest): scaffold package

README.md

@@ -20,6 +20,7 @@ This repository contains the following packages [^fn1]:
 - [`@metamask/snaps-sdk`](packages/snaps-sdk)
 - [`@metamask/snaps-simulation`](packages/snaps-simulation)
 - [`@metamask/snaps-utils`](packages/snaps-utils)
+- [`@metamask/snaps-vitest`](packages/snaps-vitest)
 - [`@metamask/snaps-webpack-plugin`](packages/snaps-webpack-plugin)
 
 <!-- end package list -->
@@ -43,6 +44,7 @@ linkStyle default opacity:0.5
   snaps_sdk(["@metamask/snaps-sdk"]);
   snaps_simulation(["@metamask/snaps-simulation"]);
   snaps_utils(["@metamask/snaps-utils"]);
+  snaps_vitest(["@metamask/snaps-vitest"]);
   snaps_webpack_plugin(["@metamask/snaps-webpack-plugin"]);
   create_snap --> snaps_utils;
   snaps_cli --> snaps_rpc_methods;

eslint.config.mjs

@@ -307,6 +307,7 @@ const config = createConfig([
       'packages/snaps-rollup-plugin/src/**/*',
       'packages/snaps-simulation/src/**/*',
       'packages/snaps-utils/src/**/*',
+      'packages/snaps-vitest/src/**/*',
       'packages/snaps-webpack-plugin/src/**/*',
       'packages/test-snaps/src/**/*',
       '**/scripts/**/*.ts',

packages/snaps-vitest/.depcheckrc.json

@@ -0,0 +1,17 @@
+{
+  "ignore-patterns": ["dist", "coverage"],
+  "ignores": [
+    "@lavamoat/allow-scripts",
+    "@lavamoat/preinstall-always-fail",
+    "@metamask/auto-changelog",
+    "@metamask/eslint-*",
+    "@types/*",
+    "@typescript-eslint/*",
+    "eslint-config-*",
+    "eslint-plugin-*",
+    "prettier-plugin-packagejson",
+    "ts-node",
+    "typedoc",
+    "typescript"
+  ]
+}

packages/snaps-vitest/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+[Unreleased]: https://github.com/MetaMask/snaps/

packages/snaps-vitest/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 MetaMask
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

packages/snaps-vitest/README.md

@@ -0,0 +1,49 @@
+# @metamask/snaps-vitest
+
+A Vitest environment and matchers for end-to-end testing MetaMask Snaps.
+
+This package is a Vitest port of [`@metamask/snaps-jest`](../snaps-jest), and
+provides the same end-to-end testing API:
+
+- A Vitest environment that starts the built-in Snap server and exposes
+  `installSnap()`.
+- The Snaps matchers (`toRespondWith`, `toRespondWithError`,
+  `toSendNotification`, `toRender`, `toTrackError`, `toTrackEvent`, and
+  `toTrace`).
+- The `installSnap`, `getMockAccount`, `getStateFromAccount`, and
+  `getStateFromAsset` helpers.
+- The Snap test types re-exported from `@metamask/snaps-simulation`.
+
+## Setup
+
+Add the preset to your `vitest.config.ts`:
+
+```ts
+import { defineConfig } from 'vitest/config';
+import { getSnapsVitestConfig } from '@metamask/snaps-vitest';
+
+export default defineConfig(
+  getSnapsVitestConfig({
+    globals: true,
+  }),
+);
+```
+
+Write tests as you would with `@metamask/snaps-jest`:
+
+```ts
+import { installSnap } from '@metamask/snaps-vitest';
+
+describe('My Snap', () => {
+  it('responds with bar', async () => {
+    const { request } = await installSnap();
+
+    const response = await request({
+      method: 'foo',
+      params: ['bar'],
+    });
+
+    expect(response).toRespondWith('bar');
+  });
+});
+```

packages/snaps-vitest/package.json

@@ -0,0 +1,102 @@
+{
+  "name": "@metamask/snaps-vitest",
+  "version": "0.0.0",
+  "description": "A Vitest environment and matchers for end-to-end testing MetaMask Snaps",
+  "keywords": [
+    "MetaMask",
+    "Snaps",
+    "Ethereum",
+    "Vitest"
+  ],
+  "homepage": "https://github.com/MetaMask/snaps/tree/main/packages/snaps-vitest#readme",
+  "bugs": {
+    "url": "https://github.com/MetaMask/snaps/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MetaMask/snaps.git"
+  },
+  "license": "ISC",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./environment": {
+      "import": {
+        "types": "./dist/environment.d.mts",
+        "default": "./dist/environment.mjs"
+      },
+      "require": {
+        "types": "./dist/environment.d.cts",
+        "default": "./dist/environment.cjs"
+      }
+    },
+    "./setup": {
+      "import": {
+        "types": "./dist/setup.d.mts",
+        "default": "./dist/setup.mjs"
+      },
+      "require": {
+        "types": "./dist/setup.d.cts",
+        "default": "./dist/setup.cjs"
+      }
+    },
+    "./config": {
+      "import": {
+        "types": "./dist/config.d.mts",
+        "default": "./dist/config.mjs"
+      },
+      "require": {
+        "types": "./dist/config.d.cts",
+        "default": "./dist/config.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "ts-bridge --project tsconfig.build.json --verbose --clean --no-references",
+    "changelog:update": "../../scripts/update-changelog.sh @metamask/snaps-vitest",
+    "changelog:validate": "../../scripts/validate-changelog.sh @metamask/snaps-vitest",
+    "lint": "yarn lint:eslint && yarn lint:misc --check && yarn changelog:validate && yarn lint:dependencies",
+    "lint:ci": "yarn lint",
+    "lint:dependencies": "depcheck",
+    "lint:eslint": "eslint . --cache",
+    "lint:fix": "yarn lint:eslint --fix && yarn lint:misc --write",
+    "lint:misc": "prettier --no-error-on-unmatched-pattern --log-level warn \"**/*.json\" \"**/*.md\" \"**/*.html\" \"!CHANGELOG.md\" --ignore-path ../../.gitignore",
+    "publish:preview": "yarn npm publish --tag preview",
+    "since-latest-release": "../../scripts/since-latest-release.sh",
+    "test": "vitest run",
+    "test:verbose": "vitest run --reporter=verbose",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "@metamask/auto-changelog": "^7.0.1",
+    "@ts-bridge/cli": "^0.6.1",
+    "depcheck": "^1.4.7",
+    "eslint": "^9.11.0",
+    "prettier": "^3.3.3",
+    "typescript": "~5.8.3",
+    "vitest": "^3.1.1"
+  },
+  "engines": {
+    "node": "^20 || >=22"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

packages/snaps-vitest/src/config.test.ts

@@ -0,0 +1,9 @@
+import { describe, expect, it } from 'vitest';
+
+import { snapsVitestPreset } from './config';
+
+describe('snapsVitestPreset', () => {
+  it('sets a test timeout', () => {
+    expect(snapsVitestPreset.testTimeout).toBe(30_000);
+  });
+});

packages/snaps-vitest/src/config.ts

@@ -0,0 +1,69 @@
+import { createRequire } from 'node:module';
+
+const nodeRequire = createRequire(__filename);
+
+/**
+ * The Vitest configuration for testing MetaMask Snaps. Spread this into the
+ * `test` section of your Vitest configuration:
+ *
+ * @example
+ * import { defineConfig } from 'vitest/config';
+ * import { snapsVitestPreset } from '@metamask/snaps-vitest';
+ *
+ * export default defineConfig({
+ *   test: {
+ *     ...snapsVitestPreset,
+ *   },
+ * });
+ */
+export const snapsVitestPreset = {
+  // These are resolved lazily, so that importing the package entrypoint does
+  // not require the built environment and setup files to exist.
+  get environment() {
+    return nodeRequire.resolve('./environment.mjs');
+  },
+  get setupFiles() {
+    return [nodeRequire.resolve('./setup.mjs')];
+  },
+
+  // End-to-end tests can take longer than usual to run, so we set the test
+  // timeout to 30 seconds by default.
+  testTimeout: 30_000,
+};
+
+export type SnapsVitestPreset = typeof snapsVitestPreset;
+
+/**
+ * Get a complete Vitest configuration for testing MetaMask Snaps, including
+ * the JSX runtime configuration required for Snap UI components in tests.
+ *
+ * @example
+ * import { defineConfig } from 'vitest/config';
+ * import { getSnapsVitestConfig } from '@metamask/snaps-vitest';
+ *
+ * export default defineConfig(
+ *   getSnapsVitestConfig({
+ *     globals: true,
+ *     environmentOptions: {
+ *       server: { root: process.cwd() },
+ *     },
+ *   }),
+ * );
+ * @param test - Additional or overridden Vitest test options.
+ * @returns The Vitest configuration.
+ */
+export function getSnapsVitestConfig(
+  test: Record<string, unknown> = {},
+): Record<string, unknown> {
+  return {
+    esbuild: {
+      jsx: 'automatic',
+      jsxImportSource: '@metamask/snaps-sdk',
+      jsxDev: false,
+    },
+    test: {
+      ...snapsVitestPreset,
+      ...test,
+    },
+  };
+}

packages/snaps-vitest/src/index.ts

@@ -0,0 +1 @@
+export * from './config';

packages/snaps-vitest/tsconfig.build.json

@@ -0,0 +1,30 @@
+{
+  "extends": "../../tsconfig.packages.build.json",
+  "compilerOptions": {
+    "baseUrl": "./",
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["./src"],
+  "exclude": [
+    "**/*.test.ts",
+    "**/*.test.tsx",
+    "./src/**/test-utils",
+    "./src/**/__mocks__",
+    "./src/**/__snapshots__"
+  ],
+  "references": [
+    {
+      "path": "../snaps-controllers/tsconfig.build.json"
+    },
+    {
+      "path": "../snaps-sdk/tsconfig.build.json"
+    },
+    {
+      "path": "../snaps-simulation/tsconfig.build.json"
+    },
+    {
+      "path": "../snaps-utils/tsconfig.build.json"
+    }
+  ]
+}

packages/snaps-vitest/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "extends": "../../tsconfig.packages.json",
+  "compilerOptions": {
+    "baseUrl": "./"
+  },
+  "include": ["./src", "package.json", "vitest.config.mts"],
+  "references": [
+    {
+      "path": "../snaps-controllers"
+    },
+    {
+      "path": "../snaps-sdk"
+    },
+    {
+      "path": "../snaps-simulation"
+    },
+    {
+      "path": "../snaps-utils"
+    }
+  ]
+}

packages/snaps-vitest/vitest.config.mts

@@ -0,0 +1,7 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    include: ['src/**/*.test.{ts,tsx}'],
+  },
+});

tsconfig.build.json

@@ -11,6 +11,7 @@
     { "path": "./packages/snaps-sdk/tsconfig.build.json" },
     { "path": "./packages/snaps-simulation/tsconfig.build.json" },
     { "path": "./packages/snaps-utils/tsconfig.build.json" },
+    { "path": "./packages/snaps-vitest/tsconfig.build.json" },
     { "path": "./packages/snaps-webpack-plugin/tsconfig.build.json" }
   ]
 }

tsconfig.json

@@ -10,6 +10,7 @@
     { "path": "./packages/snaps-sdk" },
     { "path": "./packages/snaps-simulation" },
     { "path": "./packages/snaps-utils" },
+    { "path": "./packages/snaps-vitest" },
     { "path": "./packages/snaps-webpack-plugin" }
   ],
   "compilerOptions": {

yarn.config.cjs

@@ -171,7 +171,8 @@ module.exports = defineConfig({
 
         if (
           workspace.cwd !== 'packages/examples' &&
-          workspace.cwd !== 'packages/snaps-sandbox'
+          workspace.cwd !== 'packages/snaps-sandbox' &&
+          workspace.cwd !== 'packages/snaps-vitest'
         ) {
           // All non-root packages must have the same "test" script.
           if (workspace.manifest.scripts['test:browser']) {