Commit 707f8ad

{

text: 'browser.importMapMocks',

link: '/config/browser/importmapmocks',

},

title: browser.importMapMocks | Config

outline: deep

- **Type:** `boolean`

- **Default:** enabled when the browser supports it

- **CLI:** `--browser.importMapMocks`, `--browser.importMapMocks=false`

Serve module mocks through an [import map](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/script/type/importmap) in the tester document instead of intercepting network requests.

By default, Vitest checks once per browser whether it accepts an import map after a module has loaded. If it does not, Vitest intercepts requests instead.

An import map rule cannot be removed from the document. When [`isolate`](/config/isolate) is `false`, all test files run in the same document, so Vitest also intercepts requests by default.

Set the option to `true` to always use import maps, or to `false` to always intercept requests.

When a test file calls `vi.mock`, Vitest adds an import map rule that points the module URL to its mocked version: the automocked module, the file in the `__mocks__` folder, or a module that exports every name of the original and reads the values from the factory. The browser loads the mocked module itself, so the provider does not intercept requests (for example, with Playwright's `page.route`) and the mock stays local to the document of the test file.

Request interception adds a cost to every request in the page, which grows with the number of modules a test file imports. An import map has no per-request cost.

::: warning

The browser must support multiple import maps per document: Chromium 133+, Safari 18.4+, and Firefox 150+ with the `dom.multiple_import_maps.enabled` preference. The `playwright` provider sets this preference. Other providers cannot, so Firefox falls back to request interception there.

An import map rule cannot change a module that the document already imported. If a module was imported before `vi.mock` registered it, for example by a setup file that does not mock it, Vitest reports an error instead of silently using the original module.

An import map rule cannot be removed either. When a test file calls `vi.unmock` with a static path, the setup files do not add a rule for that module, so both the setup files and the test file load the original module. `vi.doUnmock` cannot restore the original module.

A factory can only provide the exports that the original module declares. Vitest reads the export names from the original module, so a key that the factory adds cannot be imported, and an export that the factory omits is `undefined`.

:::

- **CLI:** `--browser.importMapMocks`

- **Config:** [browser.importMapMocks](/config/browser/importmapmocks)

Serve module mocks through an import map instead of request interception. By default, enabled when the browser supports it

Vitest uses native ESM in the Browser Mode. This means that we cannot replace the module so easily. Instead, Vitest intercepts the fetch request (via playwright's `page.route` or a Vite plugin API if using `preview` or `webdriverio`) and serves transformed code, if the module was mocked. With the experimental [`browser.importMapMocks`](/config/browser/importmapmocks) option, mocked modules are served through an import map in the tester document instead, so no request is intercepted.

if (browserName === 'firefox') {

// multiple import maps per document are behind a pref in Firefox 150+

launchOptions.firefoxUserPrefs = {

'dom.multiple_import_maps.enabled': true,

...launchOptions.firefoxUserPrefs,

}

}

import { getBrowserState, getConfig, supportsLateImportMaps } from './utils'

.then(() => client.rpc.onOrchestratorReady({ lateImportMaps: supportsLateImportMaps() }))

viteModule.promise = __vitest_mocker__.prepare().then(() => moduleCallback())

import type { MockImportMap } from '../../types'

async register(module, importer) {

const { sessionId } = getBrowserState()

const importMap = await rpc().registerMock(sessionId, module.toJSON(), {

importer,

testFile: getWorkerState().filepath,

})

if (importMap) {

appendImportMap(importMap)

}

function appendImportMap(importMap: MockImportMap) {

const script = document.createElement('script')

script.type = 'importmap'

script.textContent = JSON.stringify(importMap)

document.head.append(script)

for (const [specifier, url] of Object.entries(importMap.imports)) {

const expected = new URL(url, location.href).href

if (import.meta.resolve(specifier) !== expected) {

throw new Error(

`Cannot mock "${specifier}" with an import map because the browser kept its original URL. ` +

`The module was already imported before vi.mock was registered, ` +

`for example by a setup file or by an earlier test file when "isolate" is false.`,

)

}

}

export function supportsLateImportMaps(): boolean {

const specifier = '__vitest_import_map_probe__'

const script = document.createElement('script')

script.type = 'importmap'

script.textContent = JSON.stringify({ imports: { [specifier]: `/${specifier}` } })

document.head.append(script)

try {

import.meta.resolve(specifier)

return true

} catch {

return false

}