fix!: don't emit localStorage warnings on Node 26, fail gracefully when worker fails to start (#10293)

sheremet-va · web-flow · commit 334edef920b3 · 2026-07-01T10:37:39.000+02:00
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -99,7 +99,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest]
-        node_version: [22, 24]
+        node_version: [22, 24, 26]
         include:
           - os: macos-latest
             node_version: 24
diff --git a/docs/guide/environment.md b/docs/guide/environment.md
@@ -96,9 +96,9 @@ interface PopulateOptions {
 interface PopulateResult {
   // a list of all keys that were copied, even if value doesn't exist on original object
   keys: Set<string>
-  // a map of original object that might have been overridden with keys
-  // you can return these values inside `teardown` function
-  originals: Map<string | symbol, any>
+  // a map of property descriptors for keys that might have been overridden
+  // you can restore them with `Object.defineProperty` inside `teardown`
+  originals: Map<string | symbol, PropertyDescriptor>
 }
 
 export function populateGlobal(global: any, original: any, options: PopulateOptions): PopulateResult
diff --git a/docs/guide/migration.md b/docs/guide/migration.md
@@ -328,6 +328,17 @@ $ cd subdir && vitest --config ../vitest.config.ts # [!code ++]
 
 Assignments to properties on `globalThis` or `window` in `jsdom` and `happy-dom` environments are now propagated to the underlying DOM implementation. Mutable properties such as `innerWidth` can affect APIs implemented by the DOM environment, for example `happy-dom`'s `matchMedia`.
 
+### `populateGlobal` Returns Descriptors in `originals`
+
+The `originals` map returned by [`populateGlobal`](/guide/environment#custom-environment) now holds [property descriptors](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/getOwnPropertyDescriptor) instead of plain values. This avoids invoking native lazy getters (such as Node's `localStorage`) while capturing the original, and restores them faithfully on teardown.
+
+If you restore them manually in a custom environment, use `Object.defineProperty` instead of an assignment:
+
+```ts
+originals.forEach((value, key) => (global[key] = value)) // [!code --]
+originals.forEach((descriptor, key) => Object.defineProperty(global, key, descriptor)) // [!code ++]
+```
+
 ### Browser Orchestrator URL Requires a Session
 
 Vitest no longer serves the browser orchestrator UI from a bare `/__vitest_test__/` URL. Browser runner URLs are now session-bound and must include the `sessionId` generated by Vitest, for example `/__vitest_test__/?sessionId=...`.
diff --git a/packages/vitest/src/integrations/env/edge-runtime.ts b/packages/vitest/src/integrations/env/edge-runtime.ts
@@ -43,7 +43,7 @@ export default <Environment>{
     return {
       teardown(global) {
         keys.forEach(key => delete global[key])
-        originals.forEach((v, k) => (global[k] = v))
+        originals.forEach((d, k) => Object.defineProperty(global, k, d))
       },
     }
   },
diff --git a/packages/vitest/src/integrations/env/happy-dom.ts b/packages/vitest/src/integrations/env/happy-dom.ts
@@ -82,7 +82,7 @@ export default <Environment>{
       async teardown(global) {
         await teardownWindow(win)
         keys.forEach(key => delete global[key])
-        originals.forEach((v, k) => (global[k] = v))
+        originals.forEach((d, k) => Object.defineProperty(global, k, d))
       },
     }
   },
diff --git a/packages/vitest/src/integrations/env/jsdom-keys.ts b/packages/vitest/src/integrations/env/jsdom-keys.ts
@@ -209,6 +209,7 @@ const OTHER_KEYS = [
   'innerHeight',
   'innerWidth',
   'length',
+  'localStorage',
   'location',
   'matchMedia',
   'moveBy',
@@ -241,6 +242,7 @@ const OTHER_KEYS = [
   'scrollX',
   'scrollY',
   'self',
+  'sessionStorage',
   /* 'setInterval', */
   /* 'setTimeout', */
   'stop',
diff --git a/packages/vitest/src/integrations/env/jsdom.ts b/packages/vitest/src/integrations/env/jsdom.ts
@@ -225,7 +225,7 @@ export default <Environment>{
         dom.window.close()
         delete global.jsdom
         keys.forEach(key => delete global[key])
-        originals.forEach((v, k) => (global[k] = v))
+        originals.forEach((d, k) => Object.defineProperty(global, k, d))
       },
     }
   },
diff --git a/packages/vitest/src/integrations/env/utils.ts b/packages/vitest/src/integrations/env/utils.ts
@@ -45,12 +45,12 @@ export function populateGlobal(
 ): {
   keys: Set<string>
   skipKeys: string[]
-  originals: Map<string | symbol, any>
+  originals: Map<string | symbol, PropertyDescriptor>
 } {
   const { bindFunctions = false } = options
   const keys = getWindowKeys(global, win, options.additionalKeys)
 
-  const originals = new Map<string | symbol, any>()
+  const originals = new Map<string | symbol, PropertyDescriptor>()
 
   const overriddenKeys = new Set([...KEYS, ...options.additionalKeys || []])
 
@@ -63,7 +63,12 @@ export function populateGlobal(
         && win[key].bind(win)
 
     if (overriddenKeys.has(key) && key in global) {
-      originals.set(key, global[key])
+      // capture the descriptor instead of the value to avoid invoking native
+      // lazy getters such as Node's `localStorage`, which warns when accessed
+      // without `--localstorage-file`
+      const descriptor = Object.getOwnPropertyDescriptor(global, key)
+        ?? { value: global[key], configurable: true, writable: true, enumerable: true }
+      originals.set(key, descriptor)
     }
 
     Object.defineProperty(global, key, {
diff --git a/packages/vitest/src/node/pools/poolRunner.ts b/packages/vitest/src/node/pools/poolRunner.ts
@@ -384,9 +384,14 @@ export class PoolRunner {
 
   private waitForStart() {
     return new Promise<void>((resolve, reject) => {
-      const onStart = (message: WorkerResponse) => {
+      const cleanup = () => {
+        this.off('message', onStart)
+        this.off('error', onError)
+      }
+
+      function onStart(message: WorkerResponse) {
         if (message.type === 'started') {
-          this.off('message', onStart)
+          cleanup()
           if (message.error) {
             reject(message.error)
           }
@@ -396,7 +401,16 @@ export class PoolRunner {
         }
       }
 
+      // The worker can die before it ever reports back (e.g. an invalid
+      // `execArgv` makes Node exit immediately). Reject as soon as that
+      // happens instead of waiting for the start timeout to elapse.
+      function onError(error: Error) {
+        cleanup()
+        reject(error)
+      }
+
       this.on('message', onStart)
+      this.on('error', onError)
     })
   }
 
diff --git a/test/e2e/test/no-module-runner.test.ts b/test/e2e/test/no-module-runner.test.ts
@@ -712,7 +712,7 @@ test('2+2=4', () => {
       `)
     })
 
-    test('with --experimental-transform-types is supported', async () => {
+    test.runIf(process.allowedNodeEnvironmentFlags.has('--experimental-transform-types'))('with --experimental-transform-types is supported', async () => {
       const { errorTree } = await runNoViteModuleRunnerTests(
         {
           'add.cts': /* ts */`
diff --git a/test/e2e/test/pool-worker-exit.test.ts b/test/e2e/test/pool-worker-exit.test.ts
@@ -1,5 +1,5 @@
 import { sep } from 'node:path'
-import { runVitest, StableTestFileOrderSorter } from '#test-utils'
+import { runInlineTests, runVitest, StableTestFileOrderSorter } from '#test-utils'
 import { resolve } from 'pathe'
 import { expect, test } from 'vitest'
 import { readCoverageMap } from '../../coverage-test/utils'
@@ -144,3 +144,33 @@ test('worker process exit and kill raises exit code and signal to stderr along w
     }
   `)
 })
+
+test('worker that fails to start surfaces the error instead of hanging', async () => {
+  // An invalid `execArgv` makes the worker process exit immediately, before it
+  // ever reports back. The run must fail fast with the worker error rather than
+  // wait out the worker-start timeout (which previously made the run hang).
+  const { stderr, thrown } = await runInlineTests({
+    'basic.test.ts': `import { test } from 'vitest'\ntest('ok', () => {})`,
+  }, {
+    pool: 'forks',
+    execArgv: ['--vitest-invalid-flag-regression-test'],
+  })
+
+  expect(thrown).toBe(false)
+
+  const errors = stderr
+    .split('\n')
+    .filter(line => !line.startsWith(' ❯') && !line.includes('bad option') && line.trim().length > 0)
+    .join('\n')
+
+  expect(stderr).toContain('bad option: --vitest-invalid-flag-regression-test')
+  expect(errors).toMatchInlineSnapshot(`
+    "⎯⎯⎯⎯⎯⎯ Unhandled Errors ⎯⎯⎯⎯⎯⎯
+    Vitest caught 1 unhandled error during the test run.
+    This might cause false positive tests. Resolve unhandled errors to make sure your tests are not affected.
+    ⎯⎯⎯⎯⎯⎯ Unhandled Error ⎯⎯⎯⎯⎯⎯⎯
+    Error: [vitest-pool]: Worker forks emitted error.
+    Caused by: Error: Worker exited unexpectedly with exit code 9 during starting state
+    ⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯⎯"
+  `)
+})
diff --git a/test/unit/test/env-runtime.test.ts b/test/unit/test/env-runtime.test.ts
@@ -9,7 +9,7 @@ test('returns valid globals', () => {
   }
   const win = { Event: winEvent }
   const { originals } = populateGlobal(global, win)
-  expect(originals.get('Event')).toBe(globalEvent)
+  expect(originals.get('Event')?.value).toBe(globalEvent)
   expect(win.Event).toBe(winEvent)
   expect(global.Event).toBe(winEvent)
 })

Original file line number	Diff line number	Diff line change
`@@ -43,7 +43,7 @@ export default <Environment>{`
`43`	`43`	`return {`
`44`	`44`	`teardown(global) {`
`45`	`45`	`keys.forEach(key => delete global[key])`
`46`		`- originals.forEach((v, k) => (global[k] = v))`
	`46`	`+ originals.forEach((d, k) => Object.defineProperty(global, k, d))`
`47`	`47`	`},`
`48`	`48`	`}`
`49`	`49`	`},`
Original file line number	Diff line number	Diff line change
`@@ -82,7 +82,7 @@ export default <Environment>{`
`82`	`82`	`async teardown(global) {`
`83`	`83`	`await teardownWindow(win)`
`84`	`84`	`keys.forEach(key => delete global[key])`
`85`		`- originals.forEach((v, k) => (global[k] = v))`
	`85`	`+ originals.forEach((d, k) => Object.defineProperty(global, k, d))`
`86`	`86`	`},`
`87`	`87`	`}`
`88`	`88`	`},`
Original file line number	Diff line number	Diff line change
`@@ -225,7 +225,7 @@ export default <Environment>{`
`225`	`225`	`dom.window.close()`
`226`	`226`	`delete global.jsdom`
`227`	`227`	`keys.forEach(key => delete global[key])`
`228`		`- originals.forEach((v, k) => (global[k] = v))`
	`228`	`+ originals.forEach((d, k) => Object.defineProperty(global, k, d))`
`229`	`229`	`},`
`230`	`230`	`}`
`231`	`231`	`},`
Original file line number	Diff line number	Diff line change
`@@ -712,7 +712,7 @@ test('2+2=4', () => {`
`712`	`712`	`)
`713`	`713`	`})`
`714`	`714`
`715`		`- test('with --experimental-transform-types is supported', async () => {`
	`715`	`+ test.runIf(process.allowedNodeEnvironmentFlags.has('--experimental-transform-types'))('with --experimental-transform-types is supported', async () => {`
`716`	`716`	`const { errorTree } = await runNoViteModuleRunnerTests(`
`717`	`717`	`{`
`718`	`718`	'add.cts': /* ts */`