docs: say that `vi.stubEnv` changes only `import.meta.env` in Browser Mode
Maintainers usually reply within 1 day
Nobody has claimed this yet.
- #12005 by @2648782102 — closed without merging
Assessment
- Difficulty
- 1/5
- Estimated time
- 1-3 hours
- Newbie friendliness
- 82/100
- Issue type
- Documentation
- Clarity
- Clearly specified
- Activity status
- Active
- Tech stack
- javascript, typescript
- Domain
- documentation
Research direction
Read the vi.stubEnv and vi.unstubAllEnvs documentation at the linked API section, then check packages/vitest/src/integrations/vi.ts and the Browser Mode tester code cited in the issue. Add the Browser Mode behavior note to both API entries; optionally link it from the Browser Mode guide. Done when the docs clearly explain that only import.meta.env is changed and restored, including when setup defines process.env.
Written by the indexing model from the issue text.
Description
Explain in Detail
The vi.stubEnv docs say: "Changes the value of environmental variable on process.env and import.meta.env." The example then asserts process.env.NODE_ENV === 'production'.
In Browser Mode (5.1.0), vi.stubEnv writes only to import.meta.env. It does not touch process.env, also when the project gives the page a process.env object (for example a setup file, because a library under test reads process.env). vi.unstubAllEnvs restores only import.meta.env too.
The code agrees: stubEnv writes to state().metaEnv (packages/vitest/src/integrations/vi.ts), and in Browser Mode metaEnv is import.meta.env (state.metaEnv = __vitest_browser_import_meta_env_init__ in the tester).
Users who move tests from Node or jsdom to Browser Mode follow the docs and get a silent no-op on process.env.
Your Suggestion for Changes
Add a note to vi.stubEnv (and vi.unstubAllEnvs), for example:
In Browser Mode,
vi.stubEnvchanges onlyimport.meta.env. Vitest does not defineprocessin the browser, andvi.stubEnvdoes not change aprocess.envobject that your setup defines.
Optionally, link this note from the Browser Mode guide.
Reproduction
Complete reproduction, all files inline. Run pnpm install, then pnpm exec vitest run.
package.json
{
"name": "repro-stubenv",
"private": true,
"type": "module",
"devDependencies": {
"@vitest/browser-playwright": "5.1.0",
"playwright": "^1.56.0",
"vitest": "5.1.0"
}
}
setup.js
// The code under test reads process.env. Give the page a process.env object.
globalThis.process ??= {}
globalThis.process.env ??= {}
test/stub-env.test.js
import { expect, test, vi } from 'vitest'
test('vi.stubEnv changes import.meta.env', () => {
vi.stubEnv('FOO', 'bar')
expect(import.meta.env.FOO).toBe('bar')
})
test('vi.stubEnv changes process.env', () => {
vi.stubEnv('FOO', 'bar')
expect(process.env.FOO).toBe('bar')
})
vitest.config.js
import { playwright } from '@vitest/browser-playwright'
import { defineConfig } from 'vitest/config'
export default defineConfig({
test: {
unstubEnvs: true,
projects: [
{ test: { name: 'node', include: ['test/**/*.test.js'] } },
{
test: {
name: 'browser',
include: ['test/**/*.test.js'],
setupFiles: ['./setup.js'],
browser: {
enabled: true,
headless: true,
provider: playwright(),
instances: [{ browser: 'chromium' }],
},
},
},
],
},
})
Result: 3 of 4 tests pass. Only the browser process.env test fails:
FAIL |browser (chromium)| test/stub-env.test.js > vi.stubEnv changes process.env
AssertionError: expected undefined to be 'bar' // Object.is equality
Tests 1 failed | 3 passed (4)
Without setup.js, globalThis.process is undefined in Browser Mode, so process.env.FOO throws instead.
Written by an agent (Claude Code, claude-opus-5-5) and checked against the reproduction above.
- Dominant language
- TypeScript
- Stars
- 17.4k
- Forks
- 2.2k
- Avg merge
- 1d 12h
- Merged PRs (30d)
- 148
Getting set up
- No Dockerfile or Docker Compose file
- Has a pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from vitest-dev/vitest
-
approved documentation
Difficulty 1/5 Under an hour Newbie friendliness 89/100
vitest-dev/vitest#12015 · 4 comments ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
vitest-dev/vitest#11941 · 2 comments ·
Maintainers usually reply within 1 day
-
A fixture named `task` breaks `expect` from the test contextMay be free again @hrishikeshpathak1009 claimed this 7 days ago, and no pull request is open. Openp2-edge-case
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
vitest-dev/vitest#11929 · 1 comment ·
Maintainers usually reply within 1 day
-
`%%` in a `test.each` / `describe.each` / `test.for` title consumes a parameterMay be free again A pull request for this issue was closed without being merged. Open
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
vitest-dev/vitest#11913 · 1 comment ·
Maintainers usually reply within 1 day
-
Docs: importOriginal return type is missing PromisePossibly taken @ragib-mrb claimed this 6 days ago. Opendocumentation
Difficulty 1/5 Under an hour Newbie friendliness 94/100
vitest-dev/vitest#11894 · 1 comment ·
Maintainers usually reply within 1 day
All issues in vitest-dev/vitest
Similar issues
-
approved check:passed streams:remove
Difficulty 1/5 Under an hour Newbie friendliness 62/100
Maintainers usually reply within 1 day
-
Monthly Not a priority
Difficulty 2/5 1-3 hours Newbie friendliness 66/100
Expensify/App#107229 · 1 comment ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
GitTools/actions#2297 · 1 reaction ·
Maintainers usually reply within 1 day
-
bug
Difficulty 1/5 Under an hour Newbie friendliness 88/100
hiero-ledger/hiero-sdk-js#4793 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 62/100
microsoft/vscode-cosmosdb#3594 · 1 comment ·
Maintainers usually reply within 1 day