vitest-auto-spy 4.3.0 → 4.4.0

package/AGENTS.md

@@ -1183,6 +1183,17 @@ the realm, not owned by `globalThis`), and with `isolate: false` the next file d
 own `useFakeTimers` with `Cannot read properties of undefined (reading 'now')`. If you see that,
 the file in the stack is not the cause.
 
+`restoreWebStorage` is the other repair that is on by default. Vitest copies a DOM environment's
+globals onto `globalThis` behind `if (k in global) return KEYS.includes(k)`, and neither
+`localStorage` nor `sessionStorage` is in `KEYS` — both used to arrive only because Node put neither
+on `globalThis`, so the first half of that condition was false. Node's own Web Storage made the key
+exist, and the environment's storage stopped arriving: `setItem is not a function` on Node 25,
+`undefined` on Node 26, under jsdom and happy-dom alike, because the filter runs before either. The
+suite stays green until a spec touches storage, so this lands as "CI moved to a new Node and eleven
+unrelated specs died". The repair writes a key, reads it back and removes it — a storage that
+survives that is left alone, whoever implemented it — and it installs nothing in a `node`
+environment, which is supposed to have no Web Storage at all.
+
 `hookTimeoutHint` is on by default too, and it is the one that pays off on the day a suite lands in
 CI. Jest resolves **one** budget — `hook.timeout || getState().testTimeout` for a hook,
 `test.timeout || getState().testTimeout` for a body — while Vitest resolves `hookTimeout` on its
@@ -2484,6 +2495,7 @@ packages, which a subpath export can never be.
 | a spy is never called, no warning                                                                        | the method is an instance field, not on the prototype                                                                                                | `instanceMethodsToSpyOn`, or `createAutoMock<T>()`                                                                                      |
 | `Cannot access '__vi_import_N__' before initialization`                                                  | `vi.mock()` on `@angular/core` or a relative path                                                                                                    | you cannot mock it — the specs are bundled. Assert the result instead                                                                   |
 | `AggregateError at Object.dispatchError`, for a request nothing asserts on                               | jsdom really served an `XMLHttpRequest` — `blockNetwork` used to cover only `fetch`                                                                  | `setupAutoSpy({ blockNetwork: true })`, or `{ xhr: 'empty' }` for tracker pings (§10)                                                   |
+| `localStorage.setItem is not a function`, or `localStorage` undefined                                    | Node's own Web Storage made Vitest's global filter skip the environment's — Node 25 and up, jsdom and happy-dom alike                               | on by default in `setupAutoSpy()`; `restoreWebStorage()` on its own (§10)                                                               |
 | `Schedulers cannot synchronously execute watches while scheduling`                                       | a timer from a **previous** file, under `isolate: false`                                                                                             | track and cancel pending timers/frames in the setup file (§10)                                                                          |
 | `signal read during notification phase`                                                                  | same — a stray `requestAnimationFrame` callback                                                                                                      | same                                                                                                                                    |
 | an assertion error printed to stderr, every test green and the run exiting 0                             | zone.js swallowed a rejection nobody handled                                                                                                         | `setupAutoSpy({ strayRejections: true })` fails the test it surfaced in (§10)                                                           |

package/README.md

@@ -2492,6 +2492,7 @@ single-purpose utility you can pick up independently — they all ride on the sa
 | `installPerTest(install)`                                                                | `/setup`                      | Re-install a stub before every test of the block — a `describe`-level stub is restored away after the first                                                                                           |
 | `setupAngularTestEnv(opts)`                                                              | `/angular`                    | Zone and zoneless spec files in one worker, switching platforms per file                                                                                                                              |
 | `restoreTimerGlobals()`                                                                  | `/setup`                      | Put back timer globals that uninstalling the fakes deleted rather than restored                                                                                                                       |
+| `restoreWebStorage(options?)`                                                             | `/setup`                      | Give `globalThis` a `localStorage` / `sessionStorage` that work when the runner's copy never arrived ([details](#test-run-hygiene))                                                                    |
 | `trackMockRegistry()` / `keepMockRegistered(mock)` / `restoreLongLivedImplementations()` | `/setup`                      | Keep @vitest/spy's mock registry to the mocks that outlive a file; mark one the split would miss; put back an implementation a cross-file `vi.resetAllMocks()` dropped ([details](#test-run-hygiene)) |
 | `trackNodeMocks()` / `pruneNodeMocks()` / `countNodeMocks()`                             | `/node`                       | Give this library its own `node:test` `MockTracker` so a dropped spy is freed — 21× less retained heap; sweep by hand, and read the count back                                                        |
 | `setSpyEngine(engine)` / `getSpyEngine()`                                                | `/setup`                      | Build method spies from this library's own mock (`'auto-spy'`, the default) or from `vi.fn()` (`'runner'`) ([details](#the-spy-engine))                                                               |
@@ -2733,6 +2734,16 @@ expensive to diagnose when it is missing. The first three are on by default:
     which is a fact rather than a guess, and names the `setImmediate` case that reaches this with no
     timer in sight: a request matching no Express route is ended by `finalhandler` on `setImmediate`,
     so the 404 is never written and a routing mistake is reported as a slow test.
+11. **Web Storage the runner never handed over.** On by default, because it only ever repairs.
+    Vitest copies a DOM environment's globals onto `globalThis` behind `if (k in global) return
+    KEYS.includes(k)`, and neither `localStorage` nor `sessionStorage` is in `KEYS` — they used to
+    arrive only because Node put neither on `globalThis`, so the first half was false. Node's own
+    Web Storage made the key exist, and now the environment's storage never arrives: `setItem is
+    not a function` on Node 25, `undefined` on Node 26, under jsdom and happy-dom alike, since the
+    filter runs before either. A suite stays green with this broken — only the specs that touch
+    storage fail — so it arrives as "CI moved to a new Node and eleven unrelated specs died". The
+    repair decides by using the storage rather than looking at it, replaces only one that cannot
+    keep a value, and installs nothing at all in a `node` environment.
 
 | Option                | Default   | Notes                                                                                 |
 | --------------------- | --------- | ------------------------------------------------------------------------------------- |
@@ -2746,6 +2757,7 @@ expensive to diagnose when it is missing. The first three are on by default:
 | `guardGlobals`        | `'off'`   | Report a test that redefines a global property as non-configurable                    |
 | `globalFakeTimers`    | `false`   | Fake timers for every test **and between them** — Jest's `enableGlobally`             |
 | `restoreTimerGlobals` | `true`    | Put back timer globals that uninstalling the fakes deleted                            |
+| `restoreWebStorage`   | `true`    | Give the run a `localStorage` / `sessionStorage` that work                             |
 | `pruneMockRegistry`   | `false`   | Keep @vitest/spy's ever-growing mock registry to the mocks that outlive a file        |
 | `hookTimeoutHint`     | `true`    | Explain a hook that ran out of `hookTimeout` while `testTimeout` is larger            |
 | `frozenClockHint`     | `true`    | Explain a timeout that happened because nothing advanced the fake clock               |

package/dist/cli.js

@@ -2356,7 +2356,7 @@ function checkForeignPragma(graph) {
 }
 
 // src/cli/checks/export-map.generated.ts
-var EXPORT_MAP_VERSION = "4.2.0";
+var EXPORT_MAP_VERSION = "4.3.0";
 var ENTRY_SPECIFIERS = "vitest-auto-spy vitest-auto-spy/bun vitest-auto-spy/bun-angular vitest-auto-spy/node vitest-auto-spy/rxjs vitest-auto-spy/console vitest-auto-spy/dom-stubs vitest-auto-spy/diagnostics vitest-auto-spy/jasmine vitest-auto-spy/jasmine-compat vitest-auto-spy/observer-spy vitest-auto-spy/angular vitest-auto-spy/angular-http vitest-auto-spy/nestjs vitest-auto-spy/react vitest-auto-spy/vue vitest-auto-spy/svelte vitest-auto-spy/setup vitest-auto-spy/zone vitest-auto-spy/eslint-plugin";
 var EXPORTED_BY = {
   AccessorImplementations: "0 1 2 3 11 14 15 16",
@@ -2604,6 +2604,8 @@ var EXPORTED_BY = {
   RestoreProp: "0 1 2 3 11 14 15 16",
   restoreSpiedInstance: "0 1 2 3 14 15 16",
   restoreTimerGlobals: "17",
+  restoreWebStorage: "17",
+  RestoreWebStorageOptions: "17",
   RuleSeverity: "19",
   runEffect: "2 11",
   SchedulerHost: "17",

package/dist/setup.d.ts

@@ -356,6 +356,18 @@ interface SetupAutoSpyOptions {
      * installed on purpose. See {@link restoreTimerGlobals}.
      */
     restoreTimerGlobals?: boolean;
+    /**
+     * Give the run a `localStorage` and a `sessionStorage` that work. Default `true`, for the same
+     * reason as {@link restoreTimerGlobals}: a storage that survives a write and a read back is left
+     * untouched, and a `node` environment — which is supposed to have neither — gets nothing.
+     *
+     * Vitest's `populateGlobal` copies a DOM environment's globals behind `if (k in global) return
+     * KEYS.includes(k)`, and neither storage is in `KEYS`. Node's own Web Storage put the key on
+     * `globalThis`, so the filter now answers "no" and the environment's storage never arrives:
+     * `setItem is not a function` on Node 25, `localStorage` undefined on Node 26, under jsdom and
+     * happy-dom alike. See {@link restoreWebStorage}.
+     */
+    restoreWebStorage?: boolean;
     /**
      * Keep `@vitest/spy`'s registry of every mock ever created down to the mocks that outlive a file.
      * Default `false`, because it reaches into a set the runner does not expose.
@@ -458,16 +470,6 @@ interface SetupAutoSpyOptions {
      */
     onUnstubbedCall?: UnstubbedCallHandler;
 }
-/**
- * Install the library's test-run hygiene.
- *
- * ```ts
- * // vitest.setup.ts
- * import { setupAutoSpy } from 'vitest-auto-spy/setup';
- *
- * setupAutoSpy();
- * ```
- */
 declare function setupAutoSpy(options?: SetupAutoSpyOptions): void;
 
 /**
@@ -817,4 +819,60 @@ declare function restoreTimerGlobals(): void;
 /** The names this module watches — exported for the diagnostics that report what went missing. */
 declare function getWatchedTimerGlobals(): string[];
 
-export { BLOCKED_FETCH_MESSAGE, BLOCKED_XHR_MESSAGE, type BlockNetworkOptions, type CountingClock, type CountingClockOptions, type DuplicateCopiesReaction, type FakeTimersConfig, type GlobalPatchReaction, type PerTestHandle, type RejectionHost, type SchedulerHost, type SetupAutoSpyOptions, type SpyEngine, type StopTrackingRejections, type StopTrackingTimers, type StrayRejection, type SystemTime, type XhrBlockMode, advanceTimers, blockNetwork, cancelStrayTimers, captureMockRegistry, countStrayRejections, countStrayTimers, flushStrayRejections, getMockRegistrySize, getSpyEngine, getWatchedTimerGlobals, guardGlobalPatches, installPerTest, keepMockRegistered, keepRegisteredMocks, mockNow, mockSystemTime, pruneMockRegistry, registerFocusMatchers, resetMockRegistryTracking, restoreLongLivedImplementations, restoreTimerGlobals, setSpyEngine, setupAutoSpy, setupFakeTimers, trackMockRegistry, trackStrayRejections, trackStrayTimers, useCountingClock, withSystemTime };
+/**
+ * Putting `localStorage` / `sessionStorage` back after the runner drops them.
+ *
+ * Vitest copies a DOM environment's globals onto `globalThis` behind one filter — `if (k in global)
+ * return KEYS.includes(k)` — and neither storage is in `KEYS`. While Node put neither on
+ * `globalThis` the first half was false and both were copied; Node's own Web Storage made the key
+ * exist, so the filter now answers "no" and the environment's storage never arrives. Measured with
+ * one spec, under jsdom and happy-dom alike, because the filter runs before either:
+ *
+ * ```text
+ * Node 24.19  localStorage works
+ * Node 25.9   localStorage.setItem is not a function
+ * Node 26.7   localStorage is undefined
+ * ```
+ *
+ * A suite stays green with this broken — only the specs that touch storage fail — so it usually
+ * arrives as "CI moved to a new Node and eleven unrelated specs died".
+ */
+/** The two globals this module repairs. */
+declare const STORAGE_KEYS: readonly ["localStorage", "sessionStorage"];
+/** One of the two. */
+type StorageKey = (typeof STORAGE_KEYS)[number];
+/** How {@link restoreWebStorage} finds the window whose storage it trusts. */
+interface RestoreWebStorageOptions {
+    /**
+     * The window to take a working storage from, and to repair alongside `globalThis`.
+     *
+     * Defaults to `document.defaultView`, and to nothing where there is no document. Pass `null` to
+     * say there is no window: the repair then does nothing, which is what a DOM-less runtime wants.
+     */
+    view?: object | null;
+}
+/**
+ * Give `globalThis` a `localStorage` and a `sessionStorage` that work.
+ *
+ * Safe to call at any point and as often as you like, and a no-op in the ordinary case: a storage
+ * that survives a write and a read back is left exactly as it is, so a spec's own stub survives
+ * this. It is also a no-op where there is no window — a `node` environment is *supposed* to have no
+ * Web Storage, and inventing one would hand the code under test an API the real runtime lacks.
+ *
+ * The window's own storage is preferred over the stand-in: the environment implements the real
+ * thing, and under a runner whose window is a separate object (a Bun preload, say) only the copy to
+ * `globalThis` failed. The `Map`-backed one is for when nothing else works — which, under Vitest,
+ * is every time, because there `document.defaultView` *is* `globalThis`.
+ *
+ * ```ts
+ * // vitest.setup.ts — or leave it to setupAutoSpy(), which calls this by default
+ * import { restoreWebStorage } from 'vitest-auto-spy/setup';
+ *
+ * restoreWebStorage();
+ * ```
+ *
+ * @returns The keys it had to repair — `[]` when the environment was already sound.
+ */
+declare function restoreWebStorage(options?: RestoreWebStorageOptions): StorageKey[];
+
+export { BLOCKED_FETCH_MESSAGE, BLOCKED_XHR_MESSAGE, type BlockNetworkOptions, type CountingClock, type CountingClockOptions, type DuplicateCopiesReaction, type FakeTimersConfig, type GlobalPatchReaction, type PerTestHandle, type RejectionHost, type RestoreWebStorageOptions, type SchedulerHost, type SetupAutoSpyOptions, type SpyEngine, type StopTrackingRejections, type StopTrackingTimers, type StrayRejection, type SystemTime, type XhrBlockMode, advanceTimers, blockNetwork, cancelStrayTimers, captureMockRegistry, countStrayRejections, countStrayTimers, flushStrayRejections, getMockRegistrySize, getSpyEngine, getWatchedTimerGlobals, guardGlobalPatches, installPerTest, keepMockRegistered, keepRegisteredMocks, mockNow, mockSystemTime, pruneMockRegistry, registerFocusMatchers, resetMockRegistryTracking, restoreLongLivedImplementations, restoreTimerGlobals, restoreWebStorage, setSpyEngine, setupAutoSpy, setupFakeTimers, trackMockRegistry, trackStrayRejections, trackStrayTimers, useCountingClock, withSystemTime };

package/dist/setup.js

@@ -140,7 +140,7 @@ function getWatchedTimerGlobals() {
 
 // src/lib/fake-timers.ts
 function setupFakeTimers(config, { betweenTests = false } = {}) {
-  const install = () => {
+  const install2 = () => {
     if (!vi.isFakeTimers()) {
       vi.useFakeTimers(config);
     }
@@ -152,13 +152,13 @@ function setupFakeTimers(config, { betweenTests = false } = {}) {
     restoreTimerGlobals();
   };
   if (betweenTests) {
-    beforeAll(install);
+    beforeAll(install2);
   }
-  beforeEach(install);
+  beforeEach(install2);
   afterEach(() => {
     uninstall();
     if (betweenTests) {
-      install();
+      install2();
     }
   });
   if (betweenTests) {
@@ -681,6 +681,78 @@ function detectsAsyncLeaks(host = globalThis) {
   return Reflect.get(Object(Reflect.get(Object(Reflect.get(host, "__vitest_worker__")), "config")), "detectAsyncLeaks") === true;
 }
 
+// src/lib/web-storage.ts
+var STORAGE_KEYS = ["localStorage", "sessionStorage"];
+var PROBE_KEY = "__vitest_auto_spy_probe__";
+var PROBE_METHODS = ["setItem", "getItem", "removeItem"];
+var MapBackedStorage = class {
+  #items = /* @__PURE__ */ new Map();
+  get length() {
+    return this.#items.size;
+  }
+  clear() {
+    this.#items.clear();
+  }
+  getItem(key) {
+    return this.#items.get(key) ?? null;
+  }
+  key(index) {
+    return [...this.#items.keys()][index] ?? null;
+  }
+  removeItem(key) {
+    this.#items.delete(key);
+  }
+  setItem(key, value) {
+    this.#items.set(key, String(value));
+  }
+};
+function restoreWebStorage(options = {}) {
+  const view = options.view === void 0 ? currentView() : options.view;
+  if (!view) {
+    return [];
+  }
+  const repaired = [];
+  for (const key of STORAGE_KEYS) {
+    if (works(read(globalThis, key))) {
+      continue;
+    }
+    const fromView = read(view, key);
+    install(view, key, works(fromView) ? fromView : new MapBackedStorage());
+    repaired.push(key);
+  }
+  return repaired;
+}
+function currentView() {
+  return typeof document === "undefined" ? null : document.defaultView;
+}
+function read(host, key) {
+  return Reflect.get(host, key);
+}
+function isStorageShaped(candidate) {
+  const host = Object(candidate);
+  return PROBE_METHODS.every((method) => typeof Reflect.get(host, method) === "function");
+}
+function works(candidate) {
+  if (!isStorageShaped(candidate)) {
+    return false;
+  }
+  try {
+    candidate.setItem(PROBE_KEY, PROBE_KEY);
+    const stored = candidate.getItem(PROBE_KEY);
+    candidate.removeItem(PROBE_KEY);
+    return stored === PROBE_KEY;
+  } catch {
+    return false;
+  }
+}
+function install(view, key, storage) {
+  const descriptor = { value: storage, writable: true, configurable: true };
+  Object.defineProperty(globalThis, key, descriptor);
+  if (view !== globalThis) {
+    Object.defineProperty(view, key, descriptor);
+  }
+}
+
 // src/lib/setup-auto-spy.ts
 function warnAboutSuppressedLeaks(cancelled, write = writeWarning) {
   write(
@@ -811,11 +883,17 @@ function watchStrayRejections(enabled) {
   afterAll(trackStrayRejections());
   return [reportStrayRejections];
 }
-function setupAutoSpy(options = {}) {
-  reportDuplicateCopies(options.duplicateCopies ?? "throw");
+function prepareEnvironment(options) {
   if (options.angularBuildHint ?? true) {
     noticeAngularBuildSplitting();
   }
+  if (options.restoreWebStorage ?? true) {
+    restoreWebStorage();
+  }
+}
+function setupAutoSpy(options = {}) {
+  reportDuplicateCopies(options.duplicateCopies ?? "throw");
+  prepareEnvironment(options);
   if (options.strayTimers ?? false) {
     trackStrayTimers();
     afterAll(() => {
@@ -886,10 +964,10 @@ function describeSkippedTeardown(leaked) {
     DOCS_LINKS.setup
   );
 }
-function installPerTest(install) {
+function installPerTest(install2) {
   let current;
   beforeEach(() => {
-    current = { value: install() };
+    current = { value: install2() };
   });
   afterEach(() => {
     current = void 0;
@@ -1000,4 +1078,4 @@ function registerFocusMatchers() {
 }
 useVitestAdapter();
 
-export { BLOCKED_FETCH_MESSAGE, BLOCKED_XHR_MESSAGE, advanceTimers, blockNetwork, cancelStrayTimers, captureMockRegistry, countStrayRejections, countStrayTimers, flushStrayRejections, getMockRegistrySize, getWatchedTimerGlobals, guardGlobalPatches, installPerTest, keepMockRegistered, keepRegisteredMocks, mockNow, mockSystemTime, pruneMockRegistry, registerFocusMatchers, resetMockRegistryTracking, restoreLongLivedImplementations, restoreTimerGlobals, setupAutoSpy, setupFakeTimers, trackMockRegistry, trackStrayRejections, trackStrayTimers, useCountingClock, withSystemTime };
+export { BLOCKED_FETCH_MESSAGE, BLOCKED_XHR_MESSAGE, advanceTimers, blockNetwork, cancelStrayTimers, captureMockRegistry, countStrayRejections, countStrayTimers, flushStrayRejections, getMockRegistrySize, getWatchedTimerGlobals, guardGlobalPatches, installPerTest, keepMockRegistered, keepRegisteredMocks, mockNow, mockSystemTime, pruneMockRegistry, registerFocusMatchers, resetMockRegistryTracking, restoreLongLivedImplementations, restoreTimerGlobals, restoreWebStorage, setupAutoSpy, setupFakeTimers, trackMockRegistry, trackStrayRejections, trackStrayTimers, useCountingClock, withSystemTime };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vitest-auto-spy",
-  "version": "4.3.0",
+  "version": "4.4.0",
   "description": "Auto-generate fully-typed test spies from a class — across Vitest, Bun and node:test, with Angular/NestJS/React/Vue/Svelte recipes. Drop-in replacement for jest-auto-spies and jasmine-auto-spies.",
   "keywords": [
     "auto-mock",

package/skills/vitest-auto-spy/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: vitest-auto-spy
-description: Write or fix tests that use vitest-auto-spy — typed spies from a class or a type on Vitest, bun:test and node:test. Use when a spec imports `vitest-auto-spy` or any of its subpaths (`/angular`, `/angular-http`, `/bun-angular`, `/bun`, `/node`, `/rxjs`, `/nestjs`, `/jasmine`, `/jasmine-compat`, `/observer-spy`, `/setup`, `/zone`, `/diagnostics`, `/eslint-plugin`), when the user mentions createSpyFromClass, createAutoMock, createMock, mockDeep, createFunctionSpy, createSpyObj, enableJasmineCompat, subscribeSpyTo, provideAutoSpy, provideHttpTesting, expectRequest, injectSpy, createNestUnit, extendWithAutoSpies, renderShallow, createWithAutoSpies, createDirectiveHost, overrideComponentProvider, enableAngularDiagnostics, trackInjections, runEffect, settleResource, httpResource, mockResourceProp, mockSignalProp, mockReadonlyProp, captureArg, createSpyFromInstance, explainSpy, expectEmission, expectError, setupAutoSpy, setSpyEngine, assertMocked, Spy<T>, calledWith, mustBeCalledWith, onlyMethodsToSpyOn, strict, onUnstubbedCall, resolveWith or nextWith, when migrating a suite off jest-auto-spies, jasmine-auto-spies or @ngneat/spectator (createSpyObject, mockProvider, SpectatorService), or when a test fails with "No mock adapter registered", "Observable spies require rxjs", "not found on the class prototype", "strict mode is on", "the override did not apply", "is not a constructor", "Expected to be running in 'ProxyZone'", "jasmine is not defined", "no HttpTestingController" or "Spy<T> is not assignable".
+description: Write or fix tests that use vitest-auto-spy — typed spies from a class or a type on Vitest, bun:test and node:test. Use when a spec imports `vitest-auto-spy` or a subpath (`/angular`, `/angular-http`, `/bun-angular`, `/bun`, `/node`, `/rxjs`, `/nestjs`, `/jasmine`, `/observer-spy`, `/setup`, `/zone`, `/diagnostics`, `/eslint-plugin`), the user mentions createSpyFromClass, createAutoMock, createMock, mockDeep, createFunctionSpy, createSpyObj, enableJasmineCompat, subscribeSpyTo, provideAutoSpy, provideHttpTesting, expectRequest, injectSpy, createNestUnit, extendWithAutoSpies, renderShallow, createWithAutoSpies, createDirectiveHost, overrideComponentProvider, enableAngularDiagnostics, trackInjections, runEffect, settleResource, httpResource, mockResourceProp, mockSignalProp, mockReadonlyProp, captureArg, createSpyFromInstance, explainSpy, expectEmission, expectError, setupAutoSpy, setSpyEngine, restoreWebStorage, assertMocked, Spy<T>, calledWith, mustBeCalledWith, onlyMethodsToSpyOn, strict, onUnstubbedCall, resolveWith or nextWith, migrating off jest-auto-spies, jasmine-auto-spies or @ngneat/spectator (createSpyObject, mockProvider, SpectatorService), or a test fails with "No mock adapter registered", "Observable spies require rxjs", "not found on the class prototype", "strict mode is on", "the override did not apply", "is not a constructor", "Expected to be running in 'ProxyZone'", "jasmine is not defined", "no HttpTestingController", "localStorage.setItem is not a function" or "Spy<T> is not assignable".
 ---
 
 # vitest-auto-spy
@@ -126,69 +126,70 @@ it('loads', async () => {
 
 ## Reach for these before hand-rolling
 
-| Situation                                                                | Helper                                                                                               |
-| ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
-| a `signal()` / `computed()` field on the class under test                | `mockSignalProp(obj, prop, initial)` — returns the writable                                          |
-| a resource field, when the HTTP round trip is not the point              | `mockResourceProp(obj, prop, initial)` — `set` / `fail` / `loading`                                  |
-| the HTTP round trip _is_ the point                                       | `expectRequest(url).flush(body)` — `/angular-http`, settling included                                |
-| a node:test suite whose heap grows all run                               | `trackNodeMocks()` — `/node`, a private MockTracker                                                  |
-| a Nest provider whose constructor keeps changing                         | `createNestUnit(Target, { expose })` — built from its DI metadata                                    |
-| asserting a resource's value _and_ status together                       | `registerResourceMatchers()` → `toHaveResourceValue` / `toBeLoading`                                 |
-| a callback or config object the code under test built                    | `captureArg<T>()` in the assertion, then read `.value`                                               |
-| an object the test already holds — a real service, a client, `TestBed.inject(X)` | `createSpyFromInstance(obj, config?)` — patches it in place, `restoreSpiedInstance` undoes it       |
-| a `calledWith` that is not matching and you cannot see why               | `explainSpy(spy, 'method')` from `/diagnostics` — configs, calls, which hit which                       |
-| a method that has to throw — for all calls, or for some arguments        | `spy.m.failWith(err)` / `spy.m.calledWith(x).failWith(err)` — **not** `throwWith`                    |
-| a `TestBed` spec on Vitest 4.1+, to drop `let` + `beforeEach`            | `extendWithAutoSpies(test, { cart: CartService })` (`/angular`)                                      |
-| an `effect()` whose trigger is now a static signal                       | `runEffect(effectRef)`                                                                               |
-| the component constructs its own `IntersectionObserver`                  | `stubIntersectionObserver()` (+ `Resize` / `Mutation`)                                               |
-| a green run exiting 1 with `AbortError` under happy-dom                  | `setupAutoSpy({ blockNetwork: true })`                                                               |
-| a real request going out of a unit run (`fetch`, XHR, `sendBeacon`)      | `setupAutoSpy({ blockNetwork: true })` — `{ xhr: 'empty' }` for pings                                |
-| timers or frames from a previous file failing this one                   | `setupAutoSpy({ strayTimers: true })` — mutes `--detect-async-leaks`, see below                      |
-| an assertion error in stderr, every test green and the run at 0          | `setupAutoSpy({ strayRejections: true })` — zone.js swallowed it                                     |
-| a run getting slower the longer it goes, on `isolate: false`             | `setupAutoSpy({ pruneMockRegistry: true })` — the mock registry                                      |
-| `JavaScript heap out of memory` on a suite of wide generated clients     | `createSpyFromClass(X, { lazySpies: 'proxy' })` — one trap object, not a placeholder per method      |
-| `Cannot read properties of undefined (reading 'now')`                    | `restoreTimerGlobals` — on by default                                                                |
-| a spy handed to an API typed against the real class                      | `asInstance()` / `asSpy()`                                                                           |
-| the code under test does `new X()` (a global, a vendor SDK)              | `mockConstructor(factory)` / `stubConstructor(obj, key, factory)`                                    |
-| `X is not a constructor`, with a stack in production code                | same — a `vi.fn(() => …)` cannot serve `new`                                                         |
-| waiting for a dynamic `import()` under fake timers                       | `settleDynamicImport(() => import('…'))` / `flushEventLoop()`                                        |
-| `addEventListener(…, { signal })` throwing about `EventTarget`           | `stubAbortController()`                                                                              |
-| a suite ported from Jest's `fakeTimers.enableGlobally`                   | `setupAutoSpy({ globalFakeTimers: true })`                                                           |
-| `toHaveBeenCalledBefore` across an auto-spy and a hand-written `vi.fn()` | `setSpyEngine('runner')` / `getSpyEngine()` — `/setup`, Vitest only                                  |
-| a nested `describe`'s `beforeAll` landing on real timers                 | `setupFakeTimers(cfg, { betweenTests: true })`                                                       |
-| setup hooks applying to the first spec file of a worker only             | the setup module is cached — run coverage with `--isolate`                                           |
-| `fakeAsync` inside `test.concurrent`                                     | `installProxyZonePatch({ scope: 'callback' })`                                                       |
-| an assertion containing a date                                           | `mockSystemTime(iso)` — never `vi.spyOn(globalThis, 'Date')`                                         |
-| a spec asserting on tick _order_ under a frozen clock                    | `useCountingClock()`                                                                                 |
-| a dependency declared in the component's own `providers`                 | `overrideComponentProvider(Cmp, Token)` — it verifies on the first fixture that the override applied |
-| a double answering `undefined` for a method nobody configured            | `{ strict: true }`, or `setupAutoSpy({ strict: true })` suite-wide                                   |
-| an `afterEach` that exists only to reset one spy                         | `using spy = createSpyFromClass(X)` — `[Symbol.dispose]` resets it                                   |
-| a dead NgModule import, dead `schemas`, an unflushed HTTP request        | `enableAngularDiagnostics()` in the setup file, after `initTestEnvironment`                          |
-| "which collaborators did this actually inject?"                          | `trackInjections([A, TOKEN])` — providers plus the record, not `vi.mock`                             |
-| `NG0303` / `NG0301` / `NG0304` from an imported NgModule                 | `assertNgModuleScopes(Module)` — an AOT bundle stripped its scope                                    |
-| `Cannot read properties of undefined (reading 'provide')` in `di_setup`  | `assertComponentDefIntact(Cmp)` — a barrel chunk left a hole in `ɵcmp`                               |
-| a focus assertion failing as `expected false to deeply equal true`       | `registerFocusMatchers()` + `expect(el).toHaveFocus()`                                               |
-| a collaborator passed as an argument, then asserted on                   | `autoMocked<T>()` — typed `T & Spy<T>`                                                               |
-| a `<video>` / `<audio>`: `play()` throws, `duration` is `NaN`            | `stubMediaElement({ duration })`, then `media.set(el, …)`                                            |
-| a `vi.mock()` that silently did nothing under a bundler                  | `assertMocked(ns, { specifier, exports })`                                                           |
-| `No "default" export is defined on the mock`                             | `vi.mock('x', () => moduleNamespace({ … }))`                                                         |
-| waiting for a `resource()` / an SDK to become ready                      | `flushEventLoopUntil(() => …, { label })` — budgeted, not tuned                                      |
-| `expected [ { at: 1, …(5) }, …(8) ] to deeply equal …`                   | `expect(diffByField(actual, expected)).toBeUndefined()`                                              |
-| a stub that works only in the first test of the file                     | `installPerTest(() => stub…())` — or install it in `beforeEach`                                      |
-| a library failing every other run after a `defineProperty` on DOM        | `setupAutoSpy({ guardGlobals: 'throw' })` names the file                                             |
-| `Cannot set base providers because it has already been called`           | `setupAngularTestEnv({ zoneless, initZone, initZoneless })`                                          |
-| a dependency behind an `InjectionToken`, with no class to spy            | `provideAutoSpyForToken(TOKEN)` + `injectSpy(TOKEN)`                                                 |
-| `Expected to be running in 'ProxyZone', but it was not found`            | `import 'vitest-auto-spy/zone'` (needs `globals: true`)                                              |
-| `Property 'mockReturnValue' does not exist on type 'never'`              | upgrade — the spy no longer collapses on an unreadable return type                                   |
-| a signal-valued getter that `gettersToSpyOn` will not accept             | it accepts any key now; for a signal prefer `mockSignalProp`                                         |
-| five `asInstance(…)` in one call, found one per `tsc` run                | `...asInstances(a, b, c, d, e)`                                                                      |
-| `nextWith` demanding `HttpEvent<T>` on a generated client                | `asSpy<Client, { overload: 'first' }>(…)` / `Overload<M, 0>`                                         |
-| a fixture that needs a nested object built by its own call               | `createMock<T>({ a: { b: 1 } })` — deep partial, still exact                                         |
-| the same 100-line model literal copied into eight specs (`TS1117`)       | one `createFixtureFactory<T>(defaults)`; specs call it with what they change                         |
-| `'params' in link` ladders, or a cast, to pick a union branch            | `narrow.byKey(link, 'params')` / `narrow.observable(x)`                                              |
-| `{ ...modelInstance, flag: true }` losing every getter                   | `withOverrides(modelInstance, { flag: true })`                                                       |
-| `NG0303` / `NG0304` / silence from a directive spec                      | `createDirectiveHost({ template, scope: [Module] })`                                                 |
-| "did the migration lose a test?" with matching counters                  | `compareTestRuns(before, after)`                                                                     |
+| Situation                                                                        | Helper                                                                                               |
+| -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| a `signal()` / `computed()` field on the class under test                        | `mockSignalProp(obj, prop, initial)` — returns the writable                                          |
+| a resource field, when the HTTP round trip is not the point                      | `mockResourceProp(obj, prop, initial)` — `set` / `fail` / `loading`                                  |
+| the HTTP round trip _is_ the point                                               | `expectRequest(url).flush(body)` — `/angular-http`, settling included                                |
+| a node:test suite whose heap grows all run                                       | `trackNodeMocks()` — `/node`, a private MockTracker                                                  |
+| a Nest provider whose constructor keeps changing                                 | `createNestUnit(Target, { expose })` — built from its DI metadata                                    |
+| asserting a resource's value _and_ status together                               | `registerResourceMatchers()` → `toHaveResourceValue` / `toBeLoading`                                 |
+| a callback or config object the code under test built                            | `captureArg<T>()` in the assertion, then read `.value`                                               |
+| an object the test already holds — a real service, a client, `TestBed.inject(X)` | `createSpyFromInstance(obj, config?)` — patches it in place, `restoreSpiedInstance` undoes it        |
+| a `calledWith` that is not matching and you cannot see why                       | `explainSpy(spy, 'method')` from `/diagnostics` — configs, calls, which hit which                    |
+| a method that has to throw — for all calls, or for some arguments                | `spy.m.failWith(err)` / `spy.m.calledWith(x).failWith(err)` — **not** `throwWith`                    |
+| a `TestBed` spec on Vitest 4.1+, to drop `let` + `beforeEach`                    | `extendWithAutoSpies(test, { cart: CartService })` (`/angular`)                                      |
+| an `effect()` whose trigger is now a static signal                               | `runEffect(effectRef)`                                                                               |
+| the component constructs its own `IntersectionObserver`                          | `stubIntersectionObserver()` (+ `Resize` / `Mutation`)                                               |
+| a green run exiting 1 with `AbortError` under happy-dom                          | `setupAutoSpy({ blockNetwork: true })`                                                               |
+| a real request going out of a unit run (`fetch`, XHR, `sendBeacon`)              | `setupAutoSpy({ blockNetwork: true })` — `{ xhr: 'empty' }` for pings                                |
+| timers or frames from a previous file failing this one                           | `setupAutoSpy({ strayTimers: true })` — mutes `--detect-async-leaks`, see below                      |
+| an assertion error in stderr, every test green and the run at 0                  | `setupAutoSpy({ strayRejections: true })` — zone.js swallowed it                                     |
+| a run getting slower the longer it goes, on `isolate: false`                     | `setupAutoSpy({ pruneMockRegistry: true })` — the mock registry                                      |
+| `JavaScript heap out of memory` on a suite of wide generated clients             | `createSpyFromClass(X, { lazySpies: 'proxy' })` — one trap object, not a placeholder per method      |
+| `Cannot read properties of undefined (reading 'now')`                            | `restoreTimerGlobals` — on by default                                                                |
+| `localStorage.setItem is not a function`, or it is `undefined`                   | `restoreWebStorage` — on by default; Vitest's global filter, Node 25+                                |
+| a spy handed to an API typed against the real class                              | `asInstance()` / `asSpy()`                                                                           |
+| the code under test does `new X()` (a global, a vendor SDK)                      | `mockConstructor(factory)` / `stubConstructor(obj, key, factory)`                                    |
+| `X is not a constructor`, with a stack in production code                        | same — a `vi.fn(() => …)` cannot serve `new`                                                         |
+| waiting for a dynamic `import()` under fake timers                               | `settleDynamicImport(() => import('…'))` / `flushEventLoop()`                                        |
+| `addEventListener(…, { signal })` throwing about `EventTarget`                   | `stubAbortController()`                                                                              |
+| a suite ported from Jest's `fakeTimers.enableGlobally`                           | `setupAutoSpy({ globalFakeTimers: true })`                                                           |
+| `toHaveBeenCalledBefore` across an auto-spy and a hand-written `vi.fn()`         | `setSpyEngine('runner')` / `getSpyEngine()` — `/setup`, Vitest only                                  |
+| a nested `describe`'s `beforeAll` landing on real timers                         | `setupFakeTimers(cfg, { betweenTests: true })`                                                       |
+| setup hooks applying to the first spec file of a worker only                     | the setup module is cached — run coverage with `--isolate`                                           |
+| `fakeAsync` inside `test.concurrent`                                             | `installProxyZonePatch({ scope: 'callback' })`                                                       |
+| an assertion containing a date                                                   | `mockSystemTime(iso)` — never `vi.spyOn(globalThis, 'Date')`                                         |
+| a spec asserting on tick _order_ under a frozen clock                            | `useCountingClock()`                                                                                 |
+| a dependency declared in the component's own `providers`                         | `overrideComponentProvider(Cmp, Token)` — it verifies on the first fixture that the override applied |
+| a double answering `undefined` for a method nobody configured                    | `{ strict: true }`, or `setupAutoSpy({ strict: true })` suite-wide                                   |
+| an `afterEach` that exists only to reset one spy                                 | `using spy = createSpyFromClass(X)` — `[Symbol.dispose]` resets it                                   |
+| a dead NgModule import, dead `schemas`, an unflushed HTTP request                | `enableAngularDiagnostics()` in the setup file, after `initTestEnvironment`                          |
+| "which collaborators did this actually inject?"                                  | `trackInjections([A, TOKEN])` — providers plus the record, not `vi.mock`                             |
+| `NG0303` / `NG0301` / `NG0304` from an imported NgModule                         | `assertNgModuleScopes(Module)` — an AOT bundle stripped its scope                                    |
+| `Cannot read properties of undefined (reading 'provide')` in `di_setup`          | `assertComponentDefIntact(Cmp)` — a barrel chunk left a hole in `ɵcmp`                               |
+| a focus assertion failing as `expected false to deeply equal true`               | `registerFocusMatchers()` + `expect(el).toHaveFocus()`                                               |
+| a collaborator passed as an argument, then asserted on                           | `autoMocked<T>()` — typed `T & Spy<T>`                                                               |
+| a `<video>` / `<audio>`: `play()` throws, `duration` is `NaN`                    | `stubMediaElement({ duration })`, then `media.set(el, …)`                                            |
+| a `vi.mock()` that silently did nothing under a bundler                          | `assertMocked(ns, { specifier, exports })`                                                           |
+| `No "default" export is defined on the mock`                                     | `vi.mock('x', () => moduleNamespace({ … }))`                                                         |
+| waiting for a `resource()` / an SDK to become ready                              | `flushEventLoopUntil(() => …, { label })` — budgeted, not tuned                                      |
+| `expected [ { at: 1, …(5) }, …(8) ] to deeply equal …`                           | `expect(diffByField(actual, expected)).toBeUndefined()`                                              |
+| a stub that works only in the first test of the file                             | `installPerTest(() => stub…())` — or install it in `beforeEach`                                      |
+| a library failing every other run after a `defineProperty` on DOM                | `setupAutoSpy({ guardGlobals: 'throw' })` names the file                                             |
+| `Cannot set base providers because it has already been called`                   | `setupAngularTestEnv({ zoneless, initZone, initZoneless })`                                          |
+| a dependency behind an `InjectionToken`, with no class to spy                    | `provideAutoSpyForToken(TOKEN)` + `injectSpy(TOKEN)`                                                 |
+| `Expected to be running in 'ProxyZone', but it was not found`                    | `import 'vitest-auto-spy/zone'` (needs `globals: true`)                                              |
+| `Property 'mockReturnValue' does not exist on type 'never'`                      | upgrade — the spy no longer collapses on an unreadable return type                                   |
+| a signal-valued getter that `gettersToSpyOn` will not accept                     | it accepts any key now; for a signal prefer `mockSignalProp`                                         |
+| five `asInstance(…)` in one call, found one per `tsc` run                        | `...asInstances(a, b, c, d, e)`                                                                      |
+| `nextWith` demanding `HttpEvent<T>` on a generated client                        | `asSpy<Client, { overload: 'first' }>(…)` / `Overload<M, 0>`                                         |
+| a fixture that needs a nested object built by its own call                       | `createMock<T>({ a: { b: 1 } })` — deep partial, still exact                                         |
+| the same 100-line model literal copied into eight specs (`TS1117`)               | one `createFixtureFactory<T>(defaults)`; specs call it with what they change                         |
+| `'params' in link` ladders, or a cast, to pick a union branch                    | `narrow.byKey(link, 'params')` / `narrow.observable(x)`                                              |
+| `{ ...modelInstance, flag: true }` losing every getter                           | `withOverrides(modelInstance, { flag: true })`                                                       |
+| `NG0303` / `NG0304` / silence from a directive spec                              | `createDirectiveHost({ template, scope: [Module] })`                                                 |
+| "did the migration lose a test?" with matching counters                          | `compareTestRuns(before, after)`                                                                     |
 
 ## Rules that prevent most of the mistakes