@lwc/vitest-plugin 0.0.0-stage → 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

@@ -1,3 +1,8 @@
-# Temporary Holding Version
+# @lwc/vitest-plugin
 
-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.
+Vite/Vitest plugin that mocks `@salesforce/*` scoped imports for LWC unit tests.
+
+It is the Vitest counterpart to the `@salesforce/*` mocking that `@lwc/jest-transformer`
+performed under Jest. LWC compilation itself is handled separately by `@lwc/rollup-plugin`.
+
+> **Status:** skeleton. The scoped-import mock logic lands in a later story.

package/package.json

@@ -1,6 +1,32 @@
 {
-  "name": "@lwc/vitest-plugin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@lwc/vitest-plugin",
+    "version": "19.7.0-alpha.1",
+    "description": "Vite/Vitest plugin that mocks @salesforce/* scoped imports for LWC unit tests",
+    "homepage": "https://lwc.dev/",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/salesforce/lwc-test.git",
+        "directory": "packages/@lwc/vitest-plugin"
+    },
+    "bugs": {
+        "url": "https://github.com/salesforce/lwc-test/issues"
+    },
+    "license": "MIT",
+    "type": "module",
+    "main": "src/index.js",
+    "keywords": [
+        "vitest",
+        "vite",
+        "lwc"
+    ],
+    "files": [
+        "/src/**/*.js"
+    ],
+    "exports": {
+        ".": "./src/index.js"
+    },
+    "engines": {
+        "node": ">=20"
+    },
+    "gitHead": "599fb9694a3daffe1fb1f723bd34be130a37d16c"
+}

package/src/index.js

@@ -0,0 +1,230 @@
+/*
+ * 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
+ */
+
+// Vite plugin: mocks `@salesforce/*` + `@label/` scoped imports for LWC unit tests.
+const SCOPED_IMPORT_PREFIXES = [
+    '@salesforce/accessCheck/',
+    '@salesforce/apex', // also claims @salesforce/apexContinuation by prefix
+    '@salesforce/client/',
+    '@salesforce/contentAssetUrl/',
+    '@salesforce/customPermission/',
+    '@salesforce/i18n/',
+    '@salesforce/label/',
+    '@label/',
+    '@salesforce/messageChannel/',
+    '@salesforce/resourceUrl/',
+    '@salesforce/schema',
+    '@salesforce/user/Id',
+    '@salesforce/user/isGuest',
+    '@salesforce/userPermission/',
+];
+
+// Rollup treats ids beginning with '\0' as virtual, so no other plugin loads them from disk.
+const VIRTUAL_PREFIX = '\0salesforce:';
+
+function isMockedSpecifier(source) {
+    return SCOPED_IMPORT_PREFIXES.some((prefix) => source.startsWith(prefix));
+}
+
+// Apex default-method imports (plain + continuation). Both are a callable returning a promise, so
+// they share one fake — Jest mocks them identically. Trailing slash excludes bare `@salesforce/apex`
+// named imports (their own story).
+const APEX_METHOD_PREFIXES = ['@salesforce/apex/', '@salesforce/apexContinuation/'];
+
+// Callable spy returning a promise, so both @wire and imperative calls work. Vite caches the
+// virtual module per specifier, so all importers share one spy.
+const APEX_METHOD_SOURCE = `import { vi } from 'vitest';\nexport default vi.fn(() => Promise.resolve());`;
+
+// Bare `@salesforce/apex` (exact, no slash): real named exports for the module's API -- refreshApex
+// returns a promise, getSObjectValue is a vi.fn() spy. Must be real `export` statements: Vitest's
+// module runner builds the namespace from export statements only (syntheticNamedExports is Rollup-only).
+const APEX_IMPORT_SPECIFIER = '@salesforce/apex';
+const APEX_NAMED_IMPORTS_SOURCE = `import { vi } from 'vitest';\nexport const refreshApex = () => Promise.resolve();\nexport const getSObjectValue = vi.fn();`;
+
+// Mock value is the specifier minus its matched prefix (e.g. `@salesforce/label/c.foo` -> `"c.foo"`).
+const STRING_VALUE_PREFIXES = [
+    '@salesforce/label/',
+    '@label/', // legacy alias for @salesforce/label/
+    '@salesforce/resourceUrl/',
+    '@salesforce/contentAssetUrl/',
+    '@salesforce/messageChannel/',
+    '@salesforce/userPermission/',
+    '@salesforce/customPermission/',
+    '@salesforce/accessCheck/',
+];
+
+function getStringValue(specifier) {
+    const prefix = STRING_VALUE_PREFIXES.find((p) => specifier.startsWith(p));
+    return prefix === undefined ? undefined : specifier.slice(prefix.length);
+}
+
+// user/* and client/* mock to fixed constants, not values derived from the specifier.
+const USER_DEFAULTS = [
+    { prefix: '@salesforce/user/Id', value: '005000000000000000' },
+    { prefix: '@salesforce/user/isGuest', value: false },
+];
+const CLIENT_PREFIX = '@salesforce/client/';
+const CLIENT_MOCK_VALUES = {
+    formFactor: 'Large',
+};
+
+// Boxed in { value } so a legitimate `false` (isGuest) isn't mistaken for "no match".
+function getFixedValue(specifier) {
+    const userDefault = USER_DEFAULTS.find((d) => specifier.startsWith(d.prefix));
+    if (userDefault !== undefined) {
+        return { value: userDefault.value };
+    }
+    if (specifier.startsWith(CLIENT_PREFIX)) {
+        const resource = specifier.slice(CLIENT_PREFIX.length);
+        return { value: resource in CLIENT_MOCK_VALUES ? CLIENT_MOCK_VALUES[resource] : '' };
+    }
+    return null;
+}
+
+const I18N_IMPORT_PREFIX = '@salesforce/i18n/';
+
+// Ported from the Jest i18n transform's getMockValue -- keep in sync.
+function mappedI18nValue(key) {
+    const parts = key.split('.');
+    switch (parts[0]) {
+        case 'lang':
+            return 'en';
+        case 'dir':
+            return 'ltr';
+        case 'locale':
+            return 'en-US';
+        case 'timeZone':
+            return 'America/Los_Angeles';
+        case 'currency':
+            return 'USD';
+        case 'firstDayOfWeek':
+            return 0;
+        case 'dateTime':
+            switch (parts[1]) {
+                case 'shortDateFormat':
+                    return 'M/d/yyyy';
+                case 'mediumDateFormat':
+                    return 'MMM d, yyyy';
+                case 'longDateFormat':
+                    return 'MMMM d, yyyy';
+                case 'shortDateTimeFormat':
+                    return 'M/d/yyyy h:mm a';
+                case 'mediumDateTimeFormat':
+                    return 'MMM d, yyyy h:mm:ss a';
+                case 'shortTimeFormat':
+                    return 'h:mm a';
+                case 'mediumTimeFormat':
+                    return 'h:mm:ss a';
+                default:
+                    return undefined;
+            }
+        case 'number':
+            switch (parts[1]) {
+                case 'numberFormat':
+                    return '#,##0.###';
+                case 'percentFormat':
+                    return '#,##0%';
+                case 'currencyFormat':
+                    return '¤#,##0.00;(¤#,##0.00)';
+                case 'currencySymbol':
+                    return '$';
+                default:
+                    return undefined;
+            }
+        default:
+            return undefined;
+    }
+}
+
+// Mapped key -> its value; any other key -> ''
+function getI18nValue(specifier) {
+    const key = specifier.slice(I18N_IMPORT_PREFIX.length);
+    const mapped = mappedI18nValue(key);
+    return mapped === undefined ? '' : mapped;
+}
+
+const SCHEMA_IMPORT_PREFIX = '@salesforce/schema';
+
+function getSchemaValue(specifier) {
+    const resourcePath = specifier.slice(SCHEMA_IMPORT_PREFIX.length + 1);
+    const idx = resourcePath.indexOf('.');
+    if (idx === -1) {
+        return { objectApiName: resourcePath };
+    }
+    return {
+        objectApiName: resourcePath.slice(0, idx),
+        fieldApiName: resourcePath.slice(idx + 1),
+    };
+}
+
+// Narrow claim: only known keys are mocked; unknown @salesforce/site/* pass through to real resolution.
+const SITE_PREFIX = '@salesforce/site/';
+const SITE_VALUES = {
+    Id: '005000000000000000',
+    activeLanguages: [{ code: 'en-US', label: 'English (US)' }],
+    defaultLanguages: { code: 'en-US', label: 'English (US)' },
+};
+
+function getSiteValue(specifier) {
+    if (!specifier.startsWith(SITE_PREFIX)) {
+        return undefined;
+    }
+    const key = specifier.slice(SITE_PREFIX.length);
+    return Object.hasOwn(SITE_VALUES, key) ? SITE_VALUES[key] : undefined;
+}
+
+export function salesforceScopedImports() {
+    return {
+        name: '@lwc/vitest-plugin:salesforce-scoped-imports',
+        // Run before Vite's core `vite:resolve` so the mock wins even when the specifier also resolves to a real file on disk.
+        enforce: 'pre',
+        resolveId(source) {
+            const claimed = getSiteValue(source) !== undefined || isMockedSpecifier(source);
+            return claimed ? VIRTUAL_PREFIX + source : null;
+        },
+        load(id) {
+            if (!id.startsWith(VIRTUAL_PREFIX)) {
+                return null;
+            }
+            const specifier = id.slice(VIRTUAL_PREFIX.length);
+            if (APEX_METHOD_PREFIXES.some((prefix) => specifier.startsWith(prefix))) {
+                return APEX_METHOD_SOURCE;
+            }
+            if (specifier === APEX_IMPORT_SPECIFIER) {
+                return APEX_NAMED_IMPORTS_SOURCE;
+            }
+
+            const stringValue = getStringValue(specifier);
+            if (stringValue !== undefined) {
+                return `export default ${JSON.stringify(stringValue)};`;
+            }
+
+            const fixedValue = getFixedValue(specifier);
+            if (fixedValue !== null) {
+                return `export default ${JSON.stringify(fixedValue.value)};`;
+            }
+
+            if (specifier.startsWith(I18N_IMPORT_PREFIX)) {
+                return `export default ${JSON.stringify(getI18nValue(specifier))};`;
+            }
+
+            if (specifier.startsWith(SCHEMA_IMPORT_PREFIX)) {
+                return `export default ${JSON.stringify(getSchemaValue(specifier))};`;
+            }
+
+            const siteValue = getSiteValue(specifier);
+            if (siteValue !== undefined) {
+                return `export default ${JSON.stringify(siteValue)};`;
+            }
+
+            // Fallback for shapes without a dedicated value generator yet: echo the specifier.
+            return `export default ${JSON.stringify(specifier)};`;
+        },
+    };
+}
+
+export default salesforceScopedImports;