@lwc/vitest-preset 0.0.0-stage → 19.7.0-alpha.0

package/README.md

@@ -1,3 +1,105 @@
-# Temporary Holding Version
+# @lwc/vitest-preset
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Vitest configuration and setup for testing Lightning Web Components (LWC). It is the Vitest counterpart to [`@lwc/jest-preset`](https://github.com/salesforce/lwc-test/blob/master/packages/%40lwc/jest-preset/README.md).
+
+`lwcVitestConfig()` returns a Vitest config that:
+
+-   compiles component `.js`, `.ts`, `.html` and `.css` files with `@lwc/rollup-plugin`, using the same compiler options as `@lwc/jest-transformer`
+-   mocks `@salesforce/*` scoped imports with `@lwc/vitest-plugin`
+-   runs tests in jsdom at `http://localhost/`, as Jest does
+-   loads synthetic shadow DOM, the LWC engine and the custom matchers before each test file
+
+## Usage
+
+### Installation
+
+```shell
+yarn add --dev @lwc/vitest-preset vitest jsdom @lwc/engine-dom @lwc/synthetic-shadow @lwc/rollup-plugin @lwc/wire-service
+```
+
+-   Install `@lwc/rollup-plugin` at the same version as `@lwc/engine-dom`. Otherwise the engine warns that components were compiled by a different compiler version.
+-   `@lwc/rollup-plugin` looks up `@lwc/wire-service` whenever it resolves a namespace import such as `x/child`, so install it even if you don't use it.
+-   Requires Node 20+, Vitest 4.1+ and LWC 9.1.1+.
+
+### Configuration
+
+Create a `vitest.config.mjs`:
+
+```js
+import { defineConfig } from 'vitest/config';
+import { lwcVitestConfig } from '@lwc/vitest-preset';
+
+export default defineConfig(lwcVitestConfig(import.meta.url));
+```
+
+`import.meta.url` makes the config's directory the project root. Tests are picked up from `**/__tests__/**/*.vitest.test.{js,ts}`.
+
+Each test file runs in its own forked process with a fresh module registry (`pool: 'forks'`, `isolate: true`), as in Jest.
+
+Setting `isolate: false` (or a pool other than `forks`) in your config overrides this and is **not supported**: module state such as synthetic shadow and the `@wire` registry would leak between files.
+
+Namespace imports (`import Child from 'x/child'`, or `<x-child>` in a template) are resolved with the standard LWC module config. Point it at your components in an `lwc.config.json` next to the Vitest config, or in an `lwc` key in `package.json`:
+
+```json
+{
+    "modules": [{ "dir": "src/modules" }]
+}
+```
+
+This replaces the `moduleNameMapper` entry used with `@lwc/jest-preset`.
+
+#### nativeShadow
+
+Tests run with synthetic shadow DOM by default. To use native shadow DOM instead:
+
+```js
+export default defineConfig(lwcVitestConfig(import.meta.url, { nativeShadow: true }));
+```
+
+Tests can read the mode with `inject('lwcNativeShadow')` from `vitest`. There is no `global['lwc-jest']` under Vitest.
+
+To run the same tests in both modes, add one project per mode. Each project needs a unique name:
+
+```js
+import { defineConfig } from 'vitest/config';
+import { lwcVitestConfig } from '@lwc/vitest-preset';
+
+function project(nativeShadow) {
+    const config = lwcVitestConfig(import.meta.url, { nativeShadow });
+    config.test.name = nativeShadow ? 'native shadow' : 'synthetic shadow';
+    return config;
+}
+
+export default defineConfig({
+    test: { projects: [project(false), project(true)] },
+});
+```
+
+### Custom matchers
+
+`expect().toThrowInConnectedCallback()` and its alias `toThrowErrorInConnectedCallback()` are registered automatically and typed for TypeScript. They behave as they do in [`@lwc/jest-preset`](https://github.com/salesforce/lwc-test/blob/master/packages/%40lwc/jest-preset/README.md#custom-matchers).
+
+## Differences from `@lwc/jest-preset`
+
+-   **No snapshot serializer yet.** Snapshots don't go through `@lwc/jest-serializer`.
+-   **Component names come from the file path.** `@lwc/jest-transformer` compiles every component as `x-test`. Here a component keeps its real name (for example `smoke-mixin`), so tag names and CSS scope tokens differ.
+-   **No SSR preset.** There is no counterpart to `@lwc/jest-preset/ssr`.
+-   **`import.meta` is not rewritten.** `@lwc/jest-transformer` turns every `import.meta.env.X` into a boolean. Vitest keeps the real `import.meta`. See [`import.meta`](#importmeta).
+
+### `import.meta`
+
+Under Jest, `import.meta.env.X` is `true` only when `process.env.X` matches `/true/i`, and `import.meta.url` is `undefined`. Under Vitest, `DEV` is `true`, `PROD` is `false`, `SSR` is `false` (`true` in a `node` environment), `MODE` is `'test'`, any other key is the raw `process.env` string, and `import.meta.url` is the module's `file://` URL. So string comparisons such as `import.meta.env.X === 'false'` behave differently.
+
+Both runners read `process.env` when the code runs, but they convert `SSR` differently:
+
+| `process.env.SSR`                 | Jest    | Vitest  |
+| --------------------------------- | ------- | ------- |
+| `'true'`                          | `true`  | `true`  |
+| `'1'`                             | `false` | `true`  |
+| `'false'`, `false` or `undefined` | `false` | `true`  |
+| `''` or deleted                   | `false` | `false` |
+
+-   To turn SSR on in a test, use `vi.stubEnv('SSR', true)` and undo it with `vi.unstubAllEnvs()`. Setting `process.env.SSR = 'true'` and then `delete process.env.SSR` also works, under both runners.
+-   Never turn SSR off with `'false'`, `false` or `undefined`. Vitest reads all three as `true`.
+-   Don't set `SSR` in `test.env`. Vitest resets it from the test environment when the worker starts. Set it in a setup file instead. Use a setup file too when a module reads `import.meta.env.SSR` at the top level, because the value is captured when the module is imported.
+-   Jest only rewrites dot access (`import.meta.env.X`). Computed access, optional chaining and destructuring only work under Vitest.

package/package.json

@@ -1,6 +1,55 @@
 {
-  "name": "@lwc/vitest-preset",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@lwc/vitest-preset",
+    "version": "19.7.0-alpha.0",
+    "description": "Vitest preset configuration and setup to help test LWC",
+    "homepage": "https://lwc.dev/",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/salesforce/lwc-test.git",
+        "directory": "packages/@lwc/vitest-preset"
+    },
+    "bugs": {
+        "url": "https://github.com/salesforce/lwc-test/issues"
+    },
+    "license": "MIT",
+    "type": "module",
+    "main": "src/index.js",
+    "types": "types/index.d.ts",
+    "keywords": [
+        "vitest",
+        "vite",
+        "lwc"
+    ],
+    "files": [
+        "/src/**/*.js",
+        "!/src/__tests__",
+        "/types"
+    ],
+    "exports": {
+        ".": {
+            "types": "./types/index.d.ts",
+            "default": "./src/index.js"
+        },
+        "./setup": "./src/setup.js"
+    },
+    "dependencies": {
+        "@babel/core": "7.25.2",
+        "@babel/plugin-syntax-class-properties": "7.12.13",
+        "@babel/plugin-syntax-decorators": "7.24.7",
+        "@babel/preset-typescript": "7.24.7",
+        "@lwc/jest-shared": "19.7.0-alpha.0",
+        "@lwc/vitest-plugin": "19.7.0-alpha.0"
+    },
+    "peerDependencies": {
+        "@lwc/engine-dom": "^9.1.1",
+        "@lwc/rollup-plugin": "^9.1.1",
+        "@lwc/synthetic-shadow": "^9.1.1",
+        "@lwc/wire-service": "^9.1.1",
+        "jsdom": ">=26.1.0",
+        "vitest": "^4.1.0"
+    },
+    "engines": {
+        "node": ">=20"
+    },
+    "gitHead": "ded506234f9aac0e8195342811aae7bd22b48742"
+}

package/src/aria-reflection-polyfill.js

@@ -0,0 +1,82 @@
+/*
+ * Copyright (c) 2026, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: MIT
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
+ */
+
+// Minimal polyfill for ARIA string reflection, e.g. aria-label -> ariaLabel.
+// As of this writing, ARIA string reflection is supported in Chrome and Safari, but not Firefox or JSDOM.
+
+// ARIA Element properties that reflect to strings (not Element or FrozenArray<Element>)
+// https://w3c.github.io/aria/#ARIAMixin
+const ARIA_STRING_PROPS = [
+    'role',
+    'ariaAtomic',
+    'ariaAutoComplete',
+    'ariaBusy',
+    'ariaChecked',
+    'ariaColCount',
+    'ariaColIndex',
+    'ariaColIndexText',
+    'ariaColSpan',
+    'ariaCurrent',
+    'ariaDescription',
+    'ariaDisabled',
+    'ariaExpanded',
+    'ariaHasPopup',
+    'ariaHidden',
+    'ariaInvalid',
+    'ariaKeyShortcuts',
+    'ariaLabel',
+    'ariaLevel',
+    'ariaLive',
+    'ariaModal',
+    'ariaMultiLine',
+    'ariaMultiSelectable',
+    'ariaOrientation',
+    'ariaPlaceholder',
+    'ariaPosInSet',
+    'ariaPressed',
+    'ariaReadOnly',
+    'ariaRequired',
+    'ariaRoleDescription',
+    'ariaRowCount',
+    'ariaRowIndex',
+    'ariaRowIndexText',
+    'ariaRowSpan',
+    'ariaSelected',
+    'ariaSetSize',
+    'ariaSort',
+    'ariaValueMax',
+    'ariaValueMin',
+    'ariaValueNow',
+    'ariaValueText',
+];
+
+for (const prop of ARIA_STRING_PROPS) {
+    if (!(prop in Element.prototype)) {
+        // sniff for support
+        // e.g. `ariaPosInSet` -> `aria-posinset`
+        const attribute = prop.replace(/[A-Z]/, (letter) => `-${letter}`).toLowerCase();
+        Object.defineProperty(Element.prototype, prop, {
+            get() {
+                return this.getAttribute(attribute);
+            },
+            set(value) {
+                // Per the spec, only null is treated as removing the attribute. However, Chromium/WebKit currently
+                // differ from the spec and allow undefined as well. Here, we follow the standard.
+                // See: https://github.com/w3c/aria/issues/1858
+                if (value === null) {
+                    this.removeAttribute(attribute);
+                } else {
+                    this.setAttribute(attribute, value);
+                }
+            },
+            // These props in both WebKit and Chromium are configurable/enumerable. This allows overriding
+            // (Try `Object.getOwnPropertyDescriptor(Element.prototype, 'ariaLabel')` in either browser)
+            configurable: true,
+            enumerable: true,
+        });
+    }
+}

package/src/index.js

@@ -0,0 +1,165 @@
+/*
+ * Copyright (c) 2026, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: MIT
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
+ */
+import { fileURLToPath } from 'node:url';
+import lwc from '@lwc/rollup-plugin';
+import { salesforceScopedImports } from '@lwc/vitest-plugin';
+import { lwcKnownScopeTokens } from './scope-tokens.js';
+import { lwcTypeScript } from './typescript.js';
+
+// Print LWC compiler diagnostics in jest-transformer's `[LWC Warn](<file>): <message>` format;
+// the plugin's own string warnings still go through Vite's logger.
+function formatLwcWarnings(plugin) {
+    const { transform } = plugin;
+    return {
+        ...plugin,
+        transform(src, id) {
+            const ctx = Object.create(this);
+            ctx.warn = (log) => {
+                if (!log?.pluginCode) {
+                    return this.warn(log);
+                }
+                const message = log.message.replace(/^@lwc\/rollup-plugin: /, '');
+                console.warn(`\x1b[33m[LWC Warn]\x1b[0m(${id.split('?')[0]}): ${message}`);
+            };
+            return transform.call(ctx, src, id);
+        },
+    };
+}
+
+// Vitest blanks every `.css` module and Vite's CSS pipeline would replace LWC's stylesheet output,
+// so suffix resolved stylesheet ids to hide them from both; bypassViteCss strips it for LWC.
+const CSS_ID = /\.css(?=$|\?)/;
+const CSS_SUFFIX = '.lwc.js';
+const tagCss = (id) => id.replace(CSS_ID, `.css${CSS_SUFFIX}`);
+const untagCss = (id) => id.replace(`.css${CSS_SUFFIX}`, '.css');
+function lwcStylesheetIds() {
+    return {
+        name: 'lwc-stylesheet-ids',
+        enforce: 'pre',
+        async resolveId(source, importer, options) {
+            const resolved = await this.resolve(source, importer && untagCss(importer), {
+                ...options,
+                skipSelf: true,
+            });
+            return resolved && CSS_ID.test(resolved.id)
+                ? { ...resolved, id: tagCss(resolved.id) }
+                : resolved;
+        },
+        // The watcher reports the real .css path, but the module graph holds the tagged id.
+        configureVitest({ vitest }) {
+            const { watcher } = vitest.vite;
+            watcher.on(
+                'change',
+                (file) => CSS_ID.test(file) && watcher.emit('change', tagCss(file))
+            );
+        },
+    };
+}
+function bypassViteCss(plugin) {
+    const { load, transform } = plugin;
+    return {
+        ...plugin,
+        load(id) {
+            return load.call(this, untagCss(id));
+        },
+        transform(src, id) {
+            return transform.call(this, src, untagCss(id));
+        },
+    };
+}
+
+// Parity with jest-preset's coveragePathIgnorePatterns. Vitest reads coverage only from the root
+// config, so append to it from a hook; that also covers configs that nest this in `projects`.
+const coverageExclude = ['**/*.css', '**/*.html'];
+function lwcCoverageExclude() {
+    return {
+        name: 'lwc-coverage-exclude',
+        configureVitest({ vitest }) {
+            const { exclude } = vitest.config.coverage;
+            exclude.push(...coverageExclude.filter((glob) => !exclude.includes(glob)));
+        },
+    };
+}
+
+// Vitest config factory for LWC. Call as `lwcVitestConfig(import.meta.url)` from a vitest.config.
+// `nativeShadow: true` skips synthetic-shadow (Jest's `globals['lwc-jest'].nativeShadow`).
+export function lwcVitestConfig(importMetaUrl, { nativeShadow = false } = {}) {
+    const rootDir = fileURLToPath(new URL('.', importMetaUrl));
+    // Compiler options mirroring the jest-transformer config for parity.
+    // rootDir is mandatory: buildStart crashes without it under Vitest (no rollup input).
+    // Known gap: Jest hardcodes namespace 'x'/name 'test'; the plugin derives them from the path
+    // (no override), so `sel` and CSS scope tokens differ (x-test vs e.g. smoke-mixin).
+    const compilerOptions = {
+        rootDir,
+        sourcemap: true,
+        dynamicImports: { strictSpecifier: false },
+        enableDynamicComponents: true,
+        enableLwcOn: true,
+    };
+    // Compile test files too, as Jest does: they can define inline components with decorators.
+    // Like jest-preset's `transform`, compile only .js/.ts/.html/.css; Vite handles the rest (e.g. JSON).
+    const compileExclude = ['**/node_modules/**', /(?<!\.(?:js|ts|html|css))$/];
+    // enablePrivateMethods is per-namespace in Jest (lightning/interop only), but the plugin
+    // exposes only a global flag, so split compilation into two path-scoped instances.
+    const privateMethodsNamespaces = /[\\/](?:modules|jest-modules)[\\/](?:lightning|interop)[\\/]/;
+    return {
+        root: rootDir,
+        // Vite's built-in .ts transform lowers LWC decorators; lwcTypeScript() strips types instead.
+        // esbuild runs it on Vite 6/7, Oxc on Vite 8, so turn off both.
+        esbuild: false,
+        oxc: false,
+        plugins: [
+            lwcCoverageExclude(),
+            lwcStylesheetIds(),
+            salesforceScopedImports(),
+            lwcTypeScript(),
+            // Compile .js/.html/.css LWC bundles (replaces @lwc/jest-transformer's compile job).
+            bypassViteCss(
+                formatLwcWarnings(
+                    lwc({
+                        ...compilerOptions,
+                        include: [privateMethodsNamespaces],
+                        exclude: compileExclude,
+                        enablePrivateMethods: true,
+                    })
+                )
+            ),
+            bypassViteCss(
+                formatLwcWarnings(
+                    lwc({
+                        ...compilerOptions,
+                        exclude: [...compileExclude, privateMethodsNamespaces],
+                        enablePrivateMethods: false,
+                    })
+                )
+            ),
+            // After compilation; replaces jest-transformer's addKnownScopeToken append.
+            lwcKnownScopeTokens({ exclude: compileExclude }),
+        ],
+        // Resolve bare `lwc` to the engine (parity with @lwc/jest-resolver), via the @wire trap.
+        resolve: { alias: { lwc: fileURLToPath(new URL('./lwc.js', import.meta.url)) } },
+        test: {
+            environment: 'jsdom',
+            // Match Jest's jsdom URL (Vitest defaults to http://localhost:3000).
+            environmentOptions: { jsdom: { url: 'http://localhost/' } },
+            // Read by setup.js via inject().
+            provide: { lwcNativeShadow: nativeShadow },
+            globals: true,
+            include: ['**/__tests__/**/*.vitest.test.{js,ts}'],
+            setupFiles: ['@lwc/vitest-preset/setup'],
+            // Setup order is load-bearing (polyfill -> synthetic-shadow -> engine -> flag); run in order.
+            sequence: { setupFiles: 'list' },
+            // Jest runs each test file in its own worker with a fresh module registry, and LWC tests
+            // rely on it (synthetic-shadow patches globals once per load; the @wire registry is module state).
+            // These are Vitest 4's defaults; pin them so a package config or a future default can't change them.
+            pool: 'forks',
+            isolate: true,
+        },
+    };
+}
+
+export default lwcVitestConfig;

package/src/lwc.js

@@ -0,0 +1,140 @@
+/*
+ * Copyright (c) 2026, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: MIT
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
+ */
+
+// What `lwc` resolves to: engine-dom with a wrapped registerDecorators. Jest patches the CJS
+// engine in place; an ESM namespace can't be patched, so the local export shadows `export *`.
+import { registerDecorators as originalRegisterDecorators } from '@lwc/engine-dom';
+
+export * from '@lwc/engine-dom';
+
+// Provides temporary backward compatibility for wire-protocol reform: lwc > 1.5.0
+global.wireAdaptersRegistryHack = new Map();
+
+function isValidWireAdapter(adapter) {
+    let isValid = false;
+    if (typeof adapter === 'function') {
+        // lets check, if it is a valid adapter
+        try {
+            const adapterInstance = new adapter(() => {});
+            isValid =
+                typeof adapterInstance.connect === 'function' &&
+                typeof adapterInstance.update === 'function' &&
+                typeof adapterInstance.disconnect === 'function';
+        } catch (e) {
+            isValid = false;
+        }
+    }
+
+    return isValid;
+}
+
+/**
+ * Returns a wire adapter mock in the shape of:
+ *
+ * fn         : Used when adapter is invoked imperatively. It proxies to the original adapter function, if is callable.
+ * fn.adapter : A valid wire adapter class, consumable by @lwc/engine-dom.
+ *              If the @originalAdapter.adapter or @originalAdapter is a valid wire adapter class, fn.adapter will
+ *              act as a proxy on it until a spy is attached.
+ *
+ * @param originalAdapter
+ * @returns {function(...[*]): *}
+ */
+function createWireAdapterMockClass(originalAdapter) {
+    const noopAdapter = {
+        connect() {},
+        update() {},
+        disconnect() {},
+    };
+    let baseAdapter;
+    let baseAdapterFn = () => {};
+    const spies = [];
+
+    if (Object.prototype.hasOwnProperty.call(originalAdapter, 'adapter')) {
+        // Is more likely that the originalAdapter was registered with the wire service
+        // .adapter is the one that the engine will use, lets make it our base adapter
+        baseAdapter = originalAdapter.adapter;
+    } else if (isValidWireAdapter(originalAdapter)) {
+        // it may be the case that original adapter is a valid one, if is the case, lets use it as our base adapter
+        baseAdapter = originalAdapter;
+    }
+
+    if (typeof originalAdapter === 'function') {
+        // Mostly used in apex methods
+        baseAdapterFn = originalAdapter;
+    }
+
+    // Support for adapters to be called imperatively, mainly for apex.
+    const newAdapterMock = function (...args) {
+        return baseAdapterFn.call(this, ...args);
+    };
+
+    newAdapterMock.adapter = class WireAdapterMock {
+        constructor(dataCallback) {
+            // if a test is spying these adapter, it means is overriding the implementation
+            this._originalAdapter =
+                spies.length === 0 && baseAdapter ? new baseAdapter(dataCallback) : noopAdapter;
+            this._dataCallback = dataCallback;
+
+            spies.forEach((spy) => spy.createInstance(this));
+        }
+        connect() {
+            spies.forEach((spy) => spy.connect(this));
+            this._originalAdapter.connect();
+        }
+        update(config) {
+            spies.forEach((spy) => spy.update(this, config));
+            this._originalAdapter.update(config);
+        }
+        disconnect() {
+            spies.forEach((spy) => spy.disconnect(this));
+            this._originalAdapter.disconnect();
+        }
+        emit(value) {
+            this._dataCallback(value);
+        }
+        static spyAdapter(spy) {
+            // this function is meant to be used by wire-service-jest-util library.
+            // When this is used, register* was called, thus replacing the wire behaviour.
+            // As consequence, it will stop calling the originalAdapter on new instances.
+            spies.push(spy);
+        }
+    };
+
+    return newAdapterMock;
+}
+
+export function registerDecorators(Ctor, decoratorsMeta) {
+    const wire = decoratorsMeta.wire || {};
+
+    Object.keys(wire).forEach((adapterName) => {
+        const adapter = wire[adapterName].adapter;
+        let wireAdapterMock = global.wireAdaptersRegistryHack.get(adapter);
+
+        if (!wireAdapterMock) {
+            // Checking if the adapter is extensible, since with the wire reform,
+            // the adapterId must be:
+            // a) An extensible object (so backward compatibility is provided via register)
+            // b) A valid class.
+
+            if (!Object.isExtensible(adapter)) {
+                // if we are in case of a) lets throw now so the developer knows that they need to migrate their
+                // adapters.
+                throw new TypeError('Invalid adapterId, it must be extensible.');
+            }
+
+            // Lets create a whole replacement for this adapter.
+            wireAdapterMock = createWireAdapterMockClass(adapter);
+
+            global.wireAdaptersRegistryHack.set(adapter, wireAdapterMock);
+        }
+
+        // we are entirely replacing the wire adapter with one that can be spied on.
+        wire[adapterName].adapter = wireAdapterMock;
+    });
+
+    return originalRegisterDecorators(Ctor, decoratorsMeta);
+}

package/src/matchers/expect-throw-in-connected-callback.js

@@ -0,0 +1,100 @@
+/*
+ * Copyright (c) 2026, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: MIT
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
+ */
+import { expect } from 'vitest';
+
+// Based on Jest's toThrow() https://jestjs.io/docs/expect#tothrowerror
+// regular expression: error message matches the pattern
+// string: error message includes the substring
+// error object: error message is equal to the message property of the object
+// error class: error object is instance of class
+function matches(matcher, error) {
+    if (!matcher) {
+        return true; // any error will do
+    }
+    if (typeof matcher === 'string') {
+        return error.message.includes(matcher);
+    }
+    if (matcher instanceof RegExp) {
+        return matcher.test(error.message);
+    }
+    if (typeof matcher === 'function') {
+        // Error class
+        return error instanceof matcher;
+    }
+    if (matcher.message) {
+        // Error object
+        return error.message === matcher.message;
+    }
+}
+
+// Custom matcher to test for errors in a connectedCallback of a web component,
+// either LWC or third-party.
+// Due to native vs synthetic lifecycle (https://github.com/salesforce/lwc/pull/3662),
+// the connectedCallback function may either throw a synchronous error or an async error
+// on `window.onerror`. This function is agnostic to both and can be used as a drop-in replacement
+// for `toThrow()`/`toThrowError`.
+function createMatcher(matcherName) {
+    return {
+        [matcherName]: function toThrowErrorInConnectedCallback(func, matcher) {
+            if (typeof func !== 'function') {
+                throw new Error(`Expected a function, received: ${func}`);
+            }
+
+            // There are two cases here:
+            // 1) Error is thrown by LWC component with synthetic behavior (sync)
+            // 2) Error is thrown by third-party component or LWC with native behavior (async)
+            // We don't care which one we get; they are both treated the same.
+            let syncError;
+            let asyncError;
+
+            const listener = (errorEvent) => {
+                errorEvent.preventDefault(); // do not continue bubbling the error; we're handling it
+                asyncError = errorEvent.error;
+            };
+            window.addEventListener('error', listener);
+            try {
+                func();
+            } catch (err) {
+                syncError = err;
+            } finally {
+                window.removeEventListener('error', listener);
+            }
+
+            const { utils } = this;
+            const overallError = syncError || asyncError;
+            const pass = !!overallError && matches(matcher, overallError);
+
+            // Inspired by https://github.com/jest-community/jest-extended/blob/1f91c09/src/matchers/toThrowWithMessage.js#L25
+            // This shows a nicely-formatted error message to the user
+            const positiveHint = utils.matcherHint(`.${matcherName}`, 'function', 'expected');
+            const negativeHint = utils.matcherHint(`.not.${matcherName}`, 'function', 'expected');
+            const message =
+                `${pass ? positiveHint : negativeHint}` +
+                '\n\n' +
+                `Expected connectedCallback${pass ? ' not' : ''} to throw:\n` +
+                `  ${
+                    matcher ? utils.printExpected(matcher) : utils.EXPECTED_COLOR('Any error')
+                }\n` +
+                'Thrown:\n' +
+                `  ${
+                    overallError
+                        ? utils.printReceived(overallError)
+                        : utils.RECEIVED_COLOR('No error')
+                }\n`;
+
+            return {
+                pass,
+                message: () => message,
+            };
+        },
+    };
+}
+expect.extend({
+    // both names are accepted, ala Jest's `toThrow` and `toThrowError` being equivalent
+    ...createMatcher('toThrowInConnectedCallback'),
+    ...createMatcher('toThrowErrorInConnectedCallback'),
+});

package/src/scope-tokens.js

@@ -0,0 +1,58 @@
+/*
+ * Copyright (c) 2026, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: MIT
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
+ */
+import path from 'node:path';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const rollupPluginRequire = createRequire(require.resolve('@lwc/rollup-plugin'));
+// Filter ids with the same createFilter @lwc/rollup-plugin uses, so include/exclude match exactly.
+const { createFilter } = rollupPluginRequire('@rollup/pluginutils');
+// Hash tokens with the template-compiler @lwc/rollup-plugin compiles with, so they always match.
+const compilerRequire = createRequire(rollupPluginRequire.resolve('@lwc/compiler'));
+const { generateScopeTokens } = compilerRequire('@lwc/template-compiler/dist/index.cjs');
+// Always load @lwc/jest-shared with require(), never import: Vite's import of this CJS package
+// loads a separate copy, and the snapshot serializer reads the require() one. So register into
+// that copy (as jest-transformer does) via its absolute path.
+const registerImport = [
+    `import { createRequire as __lwcCreateRequire } from 'node:module';`,
+    `const { addKnownScopeToken } = __lwcCreateRequire(import.meta.url)(${JSON.stringify(
+        require.resolve('@lwc/jest-shared')
+    )});`,
+];
+
+// Same namespace/name @lwc/rollup-plugin passes to the compiler: an alias `?specifier=ns/name`,
+// else the last two directories. Tokens follow whichever it is, so they stay right if module ids
+// gain a specifier (e.g. x/test).
+function componentNamespaceAndName(id) {
+    const [filename, query] = id.split('?', 2);
+    const specifier = new URLSearchParams(query).get('specifier');
+    const [namespace, name] =
+        specifier?.split('/') ?? path.dirname(filename).split(path.sep).slice(-2);
+    return { filename, namespace, name };
+}
+
+// Port of jest-transformer's addKnownScopeToken append: register each compiled template's scope
+// tokens with @lwc/jest-shared so the snapshot serializer can replace them. Pass the same
+// `exclude` the lwc() instances get, so this registers tokens for exactly the templates they compile.
+export function lwcKnownScopeTokens({ exclude } = {}) {
+    const filter = createFilter(undefined, exclude);
+    return {
+        name: 'lwc-known-scope-tokens',
+        transform(code, id) {
+            const { filename, namespace, name } = componentNamespaceAndName(id);
+            if (path.extname(filename) !== '.html' || !filter(filename)) {
+                return;
+            }
+            const { cssScopeTokens } = generateScopeTokens(filename, namespace, name);
+            const register = cssScopeTokens.map(
+                (token) => `addKnownScopeToken(${JSON.stringify(token)});`
+            );
+            // Appending moves no existing code, so `map: null` keeps the compiler's sourcemap.
+            return { code: [code, ...registerImport, ...register].join('\n'), map: null };
+        },
+    };
+}

package/src/setup.js

@@ -0,0 +1,39 @@
+/*
+ * Copyright (c) 2026, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: MIT
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
+ */
+
+// Vitest runtime bootstrap for LWC — port of `@lwc/jest-preset/src/setup.js`.
+// Load order is load-bearing: ARIA polyfill -> synthetic-shadow -> engine-dom.
+import { inject } from 'vitest';
+import './aria-reflection-polyfill.js';
+
+// On Node 20, Vitest doesn't copy these jsdom globals; synthetic-shadow and engine-dom read them at load.
+for (const key of ['HTMLDocument', 'ElementInternals']) {
+    global[key] ??= global.jsdom?.window[key];
+}
+
+if (!inject('lwcNativeShadow')) {
+    // synthetic-shadow patches the global ShadowRoot/EventTarget the engine captures at load;
+    // loading it twice corrupts those globals, so guard before the (dynamic) import.
+    if (
+        ShadowRoot.prototype.constructor.toString().includes('function SyntheticShadowRoot') ||
+        EventTarget.prototype.addEventListener
+            .toString()
+            .includes('function patchedAddEventListener')
+    ) {
+        throw new Error(
+            '@lwc/synthetic-shadow is being loaded twice. Please examine your vitest/jsdom configuration.'
+        );
+    }
+    await import('@lwc/synthetic-shadow');
+}
+
+// Same module the `lwc` alias points at, so the @wire trap and its registry exist before any test.
+const { setFeatureFlag } = await import('./lwc.js');
+setFeatureFlag('ENABLE_EXPERIMENTAL_SIGNALS', true);
+
+// Custom matchers
+await import('./matchers/expect-throw-in-connected-callback.js');

package/src/typescript.js

@@ -0,0 +1,39 @@
+/*
+ * Copyright (c) 2026, salesforce.com, inc.
+ * All rights reserved.
+ * SPDX-License-Identifier: MIT
+ * For full license text, see the LICENSE file in the repo root or https://opensource.org/licenses/MIT
+ */
+import { transformSync } from '@babel/core';
+import presetTypeScript from '@babel/preset-typescript';
+import syntaxDecorators from '@babel/plugin-syntax-decorators';
+import syntaxClassProperties from '@babel/plugin-syntax-class-properties';
+
+// Vite plugin that strips TypeScript types from .ts files while leaving LWC decorators
+// (@api/@track/@wire) intact for the LWC compiler. Vite's esbuild lowers those decorators
+// into runtime __decorate calls, which the compiler can't read, so esbuild must stay off
+// for .ts. Config mirrors @lwc/jest-transformer's BABEL_TS_CONFIG.
+export function lwcTypeScript() {
+    return {
+        name: 'lwc-vitest:typescript',
+        enforce: 'pre',
+        transform(code, id) {
+            const [filepath] = id.split('?');
+            if (!filepath.endsWith('.ts') || filepath.includes('/node_modules/')) {
+                return null;
+            }
+            const result = transformSync(code, {
+                filename: filepath,
+                sourceMaps: true,
+                babelrc: false,
+                configFile: false,
+                presets: [[presetTypeScript, { allowDeclareFields: true }]],
+                plugins: [
+                    syntaxClassProperties,
+                    [syntaxDecorators, { decoratorsBeforeExport: true }],
+                ],
+            });
+            return { code: result.code, map: result.map };
+        },
+    };
+}

package/types/index.d.ts

@@ -0,0 +1,57 @@
+/* eslint-disable */
+import 'vitest';
+import type { ViteUserConfig } from 'vitest/config';
+
+export interface LwcVitestOptions {
+    /** Skip synthetic-shadow and run components in native shadow DOM. */
+    nativeShadow?: boolean;
+}
+
+/** Vitest config for LWC; call as `lwcVitestConfig(import.meta.url)` from a vitest config. */
+export declare function lwcVitestConfig(
+    importMetaUrl: string,
+    options?: LwcVitestOptions
+): ViteUserConfig;
+export default lwcVitestConfig;
+
+interface Constructable {
+    new (...args: any[]): any;
+}
+
+interface LwcVitestMatchers<R = unknown> {
+    /**
+     * @description
+     * Assert that appending a custom element to the DOM causes an error to be thrown from that element's `connectedCallback`.
+     * @example
+     * expect(() => {
+     *     document.body.appendChild(element);
+     * }).toThrowInConnectedCallback('expected error message');
+     * @see
+     * [@lwc/jest-preset docs](https://github.com/salesforce/lwc-test/blob/master/packages/%40lwc/jest-preset/README.md#custom-matchers)
+     */
+    toThrowInConnectedCallback(expected?: string | Constructable | RegExp | Error): R;
+
+    /**
+     * @description
+     * Assert that appending a custom element to the DOM causes an error to be thrown from that element's `connectedCallback`.
+     *
+     * Equivalent to `toThrowInConnectedCallback`.
+     * @example
+     * expect(() => {
+     *     document.body.appendChild(element);
+     * }).toThrowErrorInConnectedCallback('expected error message');
+     * @see
+     * [@lwc/jest-preset docs](https://github.com/salesforce/lwc-test/blob/master/packages/%40lwc/jest-preset/README.md#custom-matchers)
+     */
+    toThrowErrorInConnectedCallback(expected?: string | Constructable | RegExp | Error): R;
+}
+
+// Vitest's `Assertion` and `ExpectStatic` both extend `Matchers`, so augmenting it
+// covers `expect(fn).toThrowInConnectedCallback(...)`.
+declare module 'vitest' {
+    interface Matchers<T = any> extends LwcVitestMatchers<T> {}
+    // Mirrors the `nativeShadow` option; read it with `inject('lwcNativeShadow')`.
+    interface ProvidedContext {
+        lwcNativeShadow: boolean;
+    }
+}