{"record":{"id":"d82dbb6e298aa262","repo":"vitest-dev/vitest","slug":"vitest-browser-can-be-imported-only-inside-the-bro-d82dbb","errorCode":null,"errorMessage":"vitest/browser can be imported only inside the Browser Mode. Instead, it was imported outside of Vitest.","messagePattern":"vitest/browser can be imported only inside the Browser Mode\\. Instead, it was imported outside of Vitest\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/browser/context.js","lineNumber":14,"sourceCode":"// Vitest resolves \"vitest/browser\" as a virtual module instead\n\n// fake exports for static analysis\nexport const page = null\nexport const server = null\nexport const userEvent = null\nexport const cdp = null\nexport const commands = null\nexport const locators = null\nexport const utils = null\n\nconst pool = globalThis.__vitest_worker__?.ctx?.pool\n\nthrow new Error(\n  // eslint-disable-next-line prefer-template\n  'vitest/browser can be imported only inside the Browser Mode. '\n  + (pool\n    ? `Your test is running in ${pool} pool. Make sure your regular tests are excluded from the \"test.include\" glob pattern.`\n    : 'Instead, it was imported outside of Vitest.'),\n)\n","sourceCodeStart":1,"sourceCodeEnd":21,"githubUrl":"https://github.com/vitest-dev/vitest/blob/1fa9837ec26533512fdcad8baebf249771bd340a/packages/browser/context.js#L1-L21","documentation":"Same virtual-module guard as the pool variant, but here `globalThis.__vitest_worker__` is undefined or has no ctx.pool — meaning the module is being imported outside any vitest worker at all (no test runner present). The fallback throws telling you the import happened outside vitest entirely.","triggerScenarios":"Running the file with plain node/tsx/vite outside vitest; importing a browser test module from a script, a Storybook story, an ESLint rule, a build step, or a non-vitest test runner (jest).","commonSituations":"Tooling that statically evaluates or imports test files (eslint import/no-unresolved, storybook, typecheck scripts, unit tests in another framework); a dev script that loads test utilities; SSR/build accidentally bundling the browser module.","solutions":["Run the file under vitest with the browser pool instead of node/tsx/vite directly.","Mark `vitest/browser` as external in build/eslint configs that should not evaluate it.","Move shared helpers out of files that import `vitest/browser` so non-vitest tooling does not pull it in.","Use a dynamic import gated on a vitest-only environment check for code shared with non-vitest contexts."],"exampleFix":"// before\n// utils.shared.ts imported by both vitest browser tests and a node script\nimport { page } from 'vitest/browser' // throws when node script runs\n\n// after\n// keep the vitest/browser import inside test-only files; shared utils take page as a parameter\nexport function fillForm(p: Page) { /* ... */ }\n// test file (vitest only):\nimport { page } from 'vitest/browser'\nfillForm(page)","handlingStrategy":"type-guard","validationCode":"// before importing vitest/browser in shared code, ensure a vitest worker exists\nconst inVitest = typeof globalThis.__vitest_worker__ !== 'undefined'\nconst inBrowserPool = globalThis.__vitest_worker__?.ctx?.pool === 'browser'\n\n// only dynamic-import when both are true\n","typeGuard":"function isVitestBrowserWorker(): boolean {\n  return globalThis.__vitest_worker__?.ctx?.pool === 'browser'\n}","tryCatchPattern":null,"preventionTips":["Keep vitest/browser imports out of files loaded by non-vitest tooling.","Mark vitest/browser as external in eslint/build configs that should not resolve it.","Inject browser-only dependencies via dynamic import gated on a worker check."],"tags":["browser","import","environment","tooling","config"],"backgroundTag":null,"analyzedSha":"1fa9837ec26533512fdcad8baebf249771bd340a","analyzedAt":"2026-08-11T16:11:39.638Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}