@lwc/vitest-preset 19.7.0-alpha.0 → 19.7.0-alpha.1

package/LICENSE

@@ -0,0 +1,10 @@
+MIT LICENSE
+
+Copyright (c) 2018, Salesforce.com, Inc.
+All rights reserved.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -46,7 +46,7 @@ Namespace imports (`import Child from 'x/child'`, or `<x-child>` in a template)
 }
 ```
 
-This replaces the `moduleNameMapper` entry used with `@lwc/jest-preset`.
+This replaces the namespace entries, such as `'^c/(.+)$'`, of the `moduleNameMapper` used with `@lwc/jest-preset`. For other entries, use the [`moduleNameMapper`](#modulenamemapper) option.
 
 #### nativeShadow
 
@@ -75,6 +75,36 @@ export default defineConfig({
 });
 ```
 
+#### moduleNameMapper
+
+Maps imports the way Jest's [`moduleNameMapper`](https://jestjs.io/docs/configuration#modulenamemapper-objectstring-string--arraystring) does, so stubs set up for Jest keep working:
+
+```js
+export default defineConfig(
+    lwcVitestConfig(import.meta.url, {
+        moduleNameMapper: {
+            '^lightning/(.+)$': '<rootDir>/stubs/lightning/$1/$1',
+        },
+    })
+);
+```
+
+The rules are Jest's:
+
+-   Keys are regular expressions. They match anywhere in the import specifier unless anchored with `^` and `$`.
+-   The first key that matches, in the order written, wins. If none of its targets exist, the import fails; later keys aren't tried.
+-   The target replaces the whole specifier, with `$1`, `$2` and so on filled in from the key's capture groups.
+-   `<rootDir>` is the directory of the Vitest config.
+-   An array target uses the first path that exists.
+
+Mapped imports are resolved before the `@salesforce/*` mocks, so a mapped `@salesforce/*` import loads your module, not the mock.
+
+Vite's `resolve.alias` can't express these rules: a regular-expression alias replaces only the part of the specifier that matched. For example, `'^@salesforce/label/'` aliased to a file leaves the label name stuck to the end of the file's path.
+
+Imports made from inside a dependency that Vitest externalizes (runs in Node without transforming it) aren't mapped. To map them, add the package to `test.server.deps.inline`.
+
+The plugin behind this option is exported as `lwcModuleNameMapper({ moduleNameMapper, rootDir })`, for configs that build their own plugin list. Put it before `salesforceScopedImports()` from `@lwc/vitest-plugin`, or the mocks claim mapped `@salesforce/*` imports first.
+
 ### 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).
@@ -85,6 +115,7 @@ export default defineConfig({
 -   **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).
+-   **A broken mapping fails the import.** If no target of a matching `moduleNameMapper` key exists, the import fails. Under Jest, `@lwc/jest-transformer` wraps the `@salesforce/*` imports it mocks in a try/catch, so a broken mapping for one of them quietly falls back to the default mock.
 
 ### `import.meta`
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@lwc/vitest-preset",
-    "version": "19.7.0-alpha.0",
+    "version": "19.7.0-alpha.1",
     "description": "Vitest preset configuration and setup to help test LWC",
     "homepage": "https://lwc.dev/",
     "repository": {
@@ -37,8 +37,8 @@
         "@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"
+        "@lwc/jest-shared": "19.7.0-alpha.1",
+        "@lwc/vitest-plugin": "19.7.0-alpha.1"
     },
     "peerDependencies": {
         "@lwc/engine-dom": "^9.1.1",
@@ -51,5 +51,5 @@
     "engines": {
         "node": ">=20"
     },
-    "gitHead": "ded506234f9aac0e8195342811aae7bd22b48742"
+    "gitHead": "599fb9694a3daffe1fb1f723bd34be130a37d16c"
 }

package/src/index.js

@@ -7,6 +7,7 @@
 import { fileURLToPath } from 'node:url';
 import lwc from '@lwc/rollup-plugin';
 import { salesforceScopedImports } from '@lwc/vitest-plugin';
+import { lwcModuleNameMapper } from './module-name-mapper.js';
 import { lwcKnownScopeTokens } from './scope-tokens.js';
 import { lwcTypeScript } from './typescript.js';
 
@@ -87,7 +88,11 @@ function lwcCoverageExclude() {
 
 // 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 } = {}) {
+// `moduleNameMapper` takes Jest's moduleNameMapper rules; `<rootDir>` is the config's directory.
+export function lwcVitestConfig(
+    importMetaUrl,
+    { nativeShadow = false, moduleNameMapper = {} } = {}
+) {
     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).
@@ -115,6 +120,8 @@ export function lwcVitestConfig(importMetaUrl, { nativeShadow = false } = {}) {
         plugins: [
             lwcCoverageExclude(),
             lwcStylesheetIds(),
+            // Before the @salesforce/* mocks, which would otherwise claim a mapped specifier first.
+            lwcModuleNameMapper({ moduleNameMapper, rootDir }),
             salesforceScopedImports(),
             lwcTypeScript(),
             // Compile .js/.html/.css LWC bundles (replaces @lwc/jest-transformer's compile job).
@@ -162,4 +169,6 @@ export function lwcVitestConfig(importMetaUrl, { nativeShadow = false } = {}) {
     };
 }
 
+// For configs that build their own plugin list; put it before salesforceScopedImports().
+export { lwcModuleNameMapper };
 export default lwcVitestConfig;

package/src/module-name-mapper.js

@@ -0,0 +1,80 @@
+/*
+ * 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 fs from 'node:fs';
+import path from 'node:path';
+
+// Marks the resolve of a mapped target: Jest resolves targets without the mapper.
+const MAPPED = 'lwc-module-name-mapper';
+
+// existsSync first: statSync throws on Vite's \0 virtual ids.
+const isFile = (file) => fs.existsSync(file) && fs.statSync(file).isFile();
+
+// Jest's replaceRootDirInPath: only a leading <rootDir> is replaced.
+function replaceRootDir(target, rootDir) {
+    if (!target.startsWith('<rootDir>')) {
+        return target;
+    }
+    return path.resolve(rootDir, path.normalize(`./${target.slice('<rootDir>'.length)}`));
+}
+
+// Jest's moduleNameMapper as a Vite plugin. Vite's regex `resolve.alias` replaces only the part of
+// a specifier that matched; Jest replaces the whole specifier with the target, filling in $1, $2...
+// from the key's capture groups. Keys are unanchored regexes, the first key that matches (in
+// insertion order) wins, and an array target uses the first path that exists.
+export function lwcModuleNameMapper({ moduleNameMapper = {}, rootDir }) {
+    const rules = Object.entries(moduleNameMapper).map(([key, target]) => ({
+        key,
+        regex: new RegExp(key),
+        targets: [target].flat().map((t) => replaceRootDir(t, rootDir)),
+    }));
+    let entryImporter;
+    return {
+        name: 'lwc-module-name-mapper',
+        enforce: 'pre',
+        configResolved({ root }) {
+            // The importer Vite passes when there is none, as for Vitest's test and setup files.
+            entryImporter = path.join(root, 'index.html');
+        },
+        async resolveId(source, importer, options) {
+            // Jest maps only imports: never test or setup files, and never a mapped target.
+            if (importer === entryImporter || options?.custom?.[MAPPED]) {
+                return null;
+            }
+            const rule = rules.find(({ regex }) => regex.test(source));
+            if (!rule) {
+                return null;
+            }
+            const match = source.match(rule.regex);
+            const candidates = rule.targets.map((target) =>
+                target.replaceAll(/\$(\d+)/g, (_, index) => match[Number(index)] || '')
+            );
+            for (const candidate of candidates) {
+                const resolved = await this.resolve(candidate, importer, {
+                    ...options,
+                    skipSelf: true,
+                    custom: { ...options?.custom, [MAPPED]: true },
+                });
+                // @lwc/rollup-plugin resolves any relative or absolute path, even a missing one, so
+                // check the disk. Untag stylesheet ids first: lwcStylesheetIds renames .css to
+                // .css.lwc.js. The importer is undefined when Vite resolves without one.
+                if (
+                    resolved &&
+                    (isFile(resolved.id.split('?')[0].replace(/\.css\.lwc\.js$/, '.css')) ||
+                        (importer && isFile(path.resolve(path.dirname(importer), candidate))))
+                ) {
+                    return resolved;
+                }
+            }
+            // Like Jest, the first matching key is final: later keys (and the @salesforce/* mocks)
+            // never get the specifier.
+            throw new Error(
+                `Could not locate module ${source} mapped as:\n${candidates.join('\n')}\n\n` +
+                    `Please check the moduleNameMapper entry ${JSON.stringify(rule.key)}.`
+            );
+        },
+    };
+}

package/types/index.d.ts

@@ -1,10 +1,15 @@
 /* eslint-disable */
 import 'vitest';
-import type { ViteUserConfig } from 'vitest/config';
+import type { Plugin, ViteUserConfig } from 'vitest/config';
+
+/** Jest `moduleNameMapper` rules: regex keys, targets that can use `$1`, `$2`... and `<rootDir>`. */
+export type ModuleNameMapper = Record<string, string | string[]>;
 
 export interface LwcVitestOptions {
     /** Skip synthetic-shadow and run components in native shadow DOM. */
     nativeShadow?: boolean;
+    /** Map imports as Jest's `moduleNameMapper` does; `<rootDir>` is the config's directory. */
+    moduleNameMapper?: ModuleNameMapper;
 }
 
 /** Vitest config for LWC; call as `lwcVitestConfig(import.meta.url)` from a vitest config. */
@@ -14,6 +19,16 @@ export declare function lwcVitestConfig(
 ): ViteUserConfig;
 export default lwcVitestConfig;
 
+/**
+ * The Vite plugin behind the `moduleNameMapper` option, for configs that build their own plugin
+ * list. Put it before `salesforceScopedImports()`, or the `@salesforce/*` mocks win.
+ */
+export declare function lwcModuleNameMapper(options: {
+    moduleNameMapper?: ModuleNameMapper;
+    /** What `<rootDir>` in a target stands for. */
+    rootDir: string;
+}): Plugin;
+
 interface Constructable {
     new (...args: any[]): any;
 }