docs: say that `vi.stubEnv` changes only `import.meta.env` in Browser Mode

Open Beginner friendly
#11,971 0 comments 0 reactions 0 assignees View on GitHub

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
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

documentation p1-chore

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.stubEnv changes only import.meta.env. Vitest does not define process in the browser, and vi.stubEnv does not change a process.env object 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

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from vitest-dev/vitest

All issues in vitest-dev/vitest

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.