vitest-auto-spy 4.2.0 → 4.4.0

package/AGENTS.md

@@ -88,6 +88,8 @@ Do you have a real class at runtime?
                  ├── one spec, a couple of fields   → createMock<T>(partial?)        → T   (no spies)
                  └── many specs, one shared model   → createFixtureFactory<T>(defaults) → (overrides?) => T
 
+Object already built, other code already holds it?
+                                  → createSpyFromInstance(obj, config?)  → Spy<T>, patched IN PLACE
 One standalone function?          → createFunctionSpy<Fn>('name')
 Code under test does `new Foo()`? → a real class?  createSpyClass(Foo)
                                   → only a shape?  mockConstructor<T>(() => instance)
@@ -106,6 +108,37 @@ noise scales with the number of them.
 `createMock<T>()` is the one to reach for on data shapes — it returns a plain `T`, so it satisfies a
 `no-type-assertion` lint rule without an `eslint-disable` on every fixture.
 
+**`createSpyFromInstance(instance, config?)` is the one case where nothing is constructed.** Every
+factory above builds the double, which is no help once the object exists and other code already
+points at it — a service a factory built, a third-party client, a half-real `TestBed.inject(X)`. It
+patches that object in place and hands the same object back typed as `Spy<T>`, so a closure, a DI
+container or a live subscription that captured it first sees the spies:
+
+```ts
+const client = new PaymentsClient(config); // real, already wired into the code under test
+const spy = createSpyFromInstance(client);
+
+spy.charge.calledWith(100).resolveWith({ ok: true });
+await checkout.pay(100);
+
+restoreSpiedInstance(client); // client.charge is the real method again
+```
+
+Discovery is the object's own function-valued fields **plus** every prototype method up to but not
+including `Object.prototype` — so an arrow-function property needs no `instanceMethodsToSpyOn` here,
+and `hasOwnProperty` / `toString` are never replaced. The configuration is `createSpyFromClass`',
+minus the two options that describe a double being built rather than an object being patched:
+`lazySpies` (the members already exist) and `fillMissing` (an instance is not an erased `abstract`
+declaration). Every write is journaled through the same mechanism as the `mock*Prop` helpers, so
+three ways back compose — `restoreSpiedInstance(instance)` for one object mid-test,
+`restoreMockedProps()` (which `setupAutoSpy()` already runs) for the sweep, and
+`using spy = createSpyFromInstance(client)`, whose dispose **restores** rather than merely resets:
+the only sense disposal can have for an object the consumer owns. A frozen or sealed instance, and a
+member declared `configurable: false`, come back as this package's diagnostic rather than a bare
+`TypeError` (§17). Nothing else in the field does this — `vi.mockObject` is Vitest-only,
+`sinon.createStubInstance` builds a new object from a constructor instead of patching the one you
+hold, and `bun:test` and `node:test` have nothing.
+
 **`createFixture<T>(defaults, overrides?)` / `createFixtureFactory<T>(defaults)` are for the model
 that more than one spec builds.** The difference from `createMock` is the `defaults` argument: it is
 a **complete** `T`, checked in full, in one place — so a field the model dropped fails there instead
@@ -846,6 +879,12 @@ setupAutoSpy({ globalFakeTimers: true });
 setEmissionTimeout(100); // the clock is frozen; a real second buys nothing
 ```
 
+**The code frame these failures open is the spec line, not this package.** The helpers build their
+error inside a `subscribe` or timer callback, so the stack is captured at helper entry and pinned on
+when the failure is finally built; only errors these helpers make themselves are re-anchored, and
+the error `expectError` resolves with keeps the stack of the code under test. Do not wrap them in
+`vi.defineHelper` — its `__VITEST_HELPER__` frame lands last and Vitest then drops the stack whole.
+
 **`expectEmission` subscribes when you call it, not when you await it**, and that is load-bearing
 rather than an implementation detail. It is what converts the test whose source has to be poked
 _after_ somebody is listening — a router event, a `Subject` the spec pushes into, anything that
@@ -1144,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
@@ -2104,6 +2154,17 @@ thing to check by hand after the swap: Suites' double answers every property nam
 stubbed a since-renamed method was passing over nothing and will now fail. Full mapping:
 <https://asdalexey.github.io/vitest-auto-spy/migrating-suites>.
 
+**A spec importing `@testing-library/angular` usually keeps it.** `render`, `screen` and the query
+set are a different discipline and have no twin here. What overlaps is the secondary
+`@testing-library/angular/vitest-utils` entry alone — 52 lines, four exports:
+`createMock` → `createSpyFromClass`, `createMockWithValues` → `createSpyFromClass(X, { overrides })`,
+`provideMock` → `provideAutoSpy`, `provideMockWithValues` → `provideAutoSpy(X, { overrides })` —
+`overrides` and not `returns`, because those values replace the member rather than configure it. Its
+walk assigns a mock only where `typeof descriptor?.value === 'function'`, so accessors are dropped
+silently while its `Mock<T>` still types them callable, and it recurses past `Object.prototype`, so
+`hasOwnProperty` and `toString` end up as `vi.fn()`. Full mapping, verified against the 19.4.2
+tarball: <https://asdalexey.github.io/vitest-auto-spy/migrating-testing-library-angular>.
+
 - **`renderShallow` has no single speed number, and quoting one is a bug.** This repository commits
   no harness for the helper, so no surface publishes a ratio for it and none may be invented.
   Describe the shape instead: `renderShallow` is flat in the number of children because it never
@@ -2148,6 +2209,18 @@ and it never throws: the class is reached through the undocumented `mock.constru
 constructed tracker is probed first and any failure leaves spies on `node:test`'s own tracker.
 Spies created **before** the call stay there too. `mock.reset()` in `afterEach` is the fallback.
 
+**A `node:test` spy now prints under its method name.** `mock.fn()` takes no name and has no
+`mockName()`, so a spy inherited the library's internal dispatcher and read back as
+`[Function: dispatch]` everywhere. The adapter names the *implementation* at creation and lets
+`mock.fn()` carry that name onto the mock, which is where a `node:test` mock takes its `name` from;
+`displayName` is set on the mock alongside it. The name survives `mock.reset()`, `mock.restore()`,
+`resetCalls()` and a `mockImplementation()` swap, and it is what `node:assert` diffs, what
+`util.inspect()` prints and what this package's own messages read. Do not "simplify" this into
+`Object.defineProperty(mock, 'name', …)`: redefining `name` drops the function out of V8's fast map
+and costs +206 B per mock against +65 B for naming at creation, measured over 200 000 mocks. `getMockName()` still does not exist there: read `spy.method.name`. Nothing labels a
+mock in `node:test`'s reporter output on its own. Full account:
+<https://asdalexey.github.io/vitest-auto-spy/runtimes/node#spy-names>.
+
 ---
 
 ## 14. `fakeAsync` needs `vitest-auto-spy/zone`
@@ -2401,6 +2474,8 @@ packages, which a subpath export can never be.
 | `advanceTimers() requires fake timers`                                                                   | no fake timers installed                                                                                                                             | `setupFakeTimers()` or `vi.useFakeTimers()` first                                                                                       |
 | `Nothing configured X.method, and strict mode is on`                                                     | a strict double was asked for a method no line configured                                                                                            | configure it (`mockReturnValue` / `resolveWith` / `nextWith` / `calledWith`), or `{ strict: false }` on that double (§5)                |
 | `Cannot redefine property: …` from a library accessor spy                                                | the target is an ES module namespace a bundler inlined                                                                                               | no spy library can win this — give the code a real seam (inject it, pass it in) and spy on that                                         |
+| `Cannot spy on this instance in place: it is not extensible`                                             | `createSpyFromInstance` was handed a frozen or sealed object                                                                                         | spy it before it is frozen, or build a separate double with `createSpyFromClass` (§2)                                                   |
+| `Cannot mock the property 'X': it is not configurable`                                                   | the member was defined with `configurable: false`, so it cannot be redefined                                                                         | members replaced before it are still restorable — `restoreSpiedInstance(instance)` or `restoreMockedProps()`                            |
 | `overrideComponentProvider(…): the override did not apply`                                               | the component injects a different token, or a later `overrideProvider` won                                                                           | pass the token the component actually injects (a base class, an `InjectionToken`), and override after nothing else re-configures        |
 | `the test ended with N unflushed HttpTestingController request(s)`                                       | `enableAngularDiagnostics({ pendingRequests })` — nothing answered them                                                                              | flush each (`controller.expectOne(url).flush(body)`), or `controller.verify()` where absence is the assertion (§13)                     |
 | `NgModule(s) with an empty runtime scope: …`                                                             | `ngModuleScopes` (or `assertNgModuleScopes`) — an AOT test bundle stripped `ɵɵsetNgModuleScope`, so the import contributes nothing                   | declare what the spec needs in the TestBed module directly; pass only modules expected to bring declarations (§13)                      |
@@ -2420,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)                                                           |
@@ -2479,6 +2555,18 @@ nothing in the spec: `of(double)` never emitting; `accessorSpies.setters.X` stil
 `mockReturnValue` missing on a generic method; a `mock*Prop` patch surfacing in a `describe` that
 never patched anything.
 
+**When the double is the suspect and no message names it, print it.**
+`import { explainSpy } from 'vitest-auto-spy/diagnostics'` — it sits on that entry, not the root,
+because ESM re-export is eager and a reader calls it at a breakpoint, not from a spec.
+`console.log(explainSpy(spy))`
+reports every spied member with its configured argument lists numbered and every recorded call
+attributed to the config it hit — or to the default it fell through to, which is the shape of "the
+method answered `undefined` and nothing said why". `explainSpy(spy, 'load')` narrows to one member,
+`explainSpy(spy.load)` takes a bare function spy, `calledWith` and `mustBeCalledWith` share one
+numbering, and it never throws — a foreign mock is reported as one in the text. The wording is a
+diagnostic and is free to change: print it, never assert on it.
+<https://asdalexey.github.io/vitest-auto-spy/utilities/explain-spy>.
+
 ---
 
 ## 18. Do not write this
@@ -2574,8 +2662,19 @@ config describes — `coverage.all` on a Vitest that stopped reading the key, a
 `coverage.include` in a runner config over a bundle, and a scope so large that `picomatch`
 recompiling it per file costs more than collecting the coverage does. It is
 worth one run after any large edit to a test suite — especially after a codemod, which is where
-the eaten glob below came from. Full reference:
-<https://asdalexey.github.io/vitest-auto-spy/utilities/cli>.
+the eaten glob below came from.
+
+Two of its checks are about this package's own names. `helper-from-wrong-entry` catches a named
+import taken from an entry that does not export it — `provideAutoSpy` from the root rather than
+`/angular` or `/nestjs`, `expectRequest` from anywhere but `/angular-http`. `no-unawaited-helper`
+catches an `expectEmission` / `expectError` / `stable` / `flushEventLoop` called as a bare statement
+and dropped, so the promise settles after the test ended and its assertion reports into a later test
+or nowhere. Both resolve the name against a table **generated from this package's own `exports`
+map**, which is why they are `doctor` checks and not lint rules: a per-file linter has none. Both
+are conservative — the callee must have been imported from this package in that same file (a rename
+with `as` still counts), the call must both begin and end a statement, and the pair goes quiet when
+the installed major differs from the table's. Neither has a fixer; `doctor` still never writes.
+Full reference: <https://asdalexey.github.io/vitest-auto-spy/utilities/cli>.
 
 ### If you were asked why a suite is slow
 

package/README.md

@@ -23,7 +23,7 @@ faster at suite scale ([benchmarks](#benchmarks)) — and for
 [![downloads per month](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapi.npmjs.org%2Fdownloads%2Fpoint%2Flast-month%2Fvitest-auto-spy&query=%24.downloads&color=brightgreen&logo=npm&label=downloads%2Fmonth)](https://www.npmjs.com/package/vitest-auto-spy)
 [![downloads over 18 months](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapi.npmjs.org%2Fdownloads%2Fpoint%2F2026-06-21%3A2030-01-01%2Fvitest-auto-spy&query=%24.downloads&color=brightgreen&logo=npm&label=downloads%2F18mo)](https://www.npmjs.com/package/vitest-auto-spy)
 [![CI](https://github.com/ASDAlexey/vitest-auto-spy/actions/workflows/ci.yml/badge.svg)](https://github.com/ASDAlexey/vitest-auto-spy/actions/workflows/ci.yml)
-[![minzipped size](https://img.shields.io/badge/minzip-14.3%20kB-brightgreen)](#install)
+[![minzipped size](https://img.shields.io/badge/minzip-15.0%20kB-brightgreen)](#install)
 [![types](https://img.shields.io/npm/types/vitest-auto-spy?logo=typescript&logoColor=white)](https://www.npmjs.com/package/vitest-auto-spy)
 [![coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](https://github.com/ASDAlexey/vitest-auto-spy/actions/workflows/ci.yml)
 [![license](https://img.shields.io/npm/l/vitest-auto-spy?color=blue)](./LICENSE)
@@ -48,10 +48,11 @@ faster at suite scale ([benchmarks](#benchmarks)) — and for
 
 - 🧪 Reads a class and generates a typed spy for **every** method — no hand-written `vi.fn()` lists
 - 🧬 Or mock from a **type/interface** alone — `createAutoMock<T>()`, no class required
+- 🪛 Or patch the object you already hold, in place — `createSpyFromInstance(client)` spies a real instance without replacing it, so a closure or a DI container that captured it first sees the spies; `restoreSpiedInstance` puts it back
 - 🌐 One `MockAdapter` core — **Vitest**, **Bun** and **`node:test`**, identical API on each
 - 🧩 Framework recipes: **Angular**, **NestJS**, **React**, **Vue/Pinia** and **Svelte**
 - 🎯 Return-type-aware helpers — sync, `Promise`, and `Observable` all get the right API
-- 🔀 `calledWith` / `mustBeCalledWith` argument dispatch
+- 🔀 `calledWith` / `mustBeCalledWith` argument dispatch — and `explainSpy(spy)` prints every configured list next to every recorded call, before anything has failed
 - 📡 First-class RxJS `Observable` spying (`nextWith`, `nextWithValues`, `throwWith`, …)
 - ⚙️ Getter / setter spies via `accessorSpies` — **including on Bun**, where `bun:test`'s own `spyOn(obj, 'prop', 'get')` throws _"does not support accessor properties yet"_ (verified on Bun 1.4.0); no library that generates a double from a class or a type has accessor spies on any runner
 - 🧰 DI & mocking utilities — `provideAutoSpy` / `injectSpy` (Angular, NestJS, Vue), `createFunctionSpy`, `mockReadonlyProp` for signals
@@ -74,7 +75,7 @@ faster at suite scale ([benchmarks](#benchmarks)) — and for
 - 🌀 `fakeAsync` / `waitForAsync` on Vitest — one import of `vitest-auto-spy/zone`; zone.js stays out of every other entry
 - 🧩 Module mocks that prove they applied — `assertMocked`, `moduleNamespace`, for a `vi.mock()` a bundler quietly ignored
 - 🧾 Fixtures without casts — deep-partial `createMock`, `createFixture` / `createFixtureFactory`, `narrow()`, `withOverrides()`, `asInstances()`, `captureArg()`
-- 🚚 A migration you can verify — `vitest-auto-spy/diagnostics`: `compareTestRuns` on the two JSON reports, `summarizeTestRun` / `formatTestRunComparison` to read the answer, `diffByField` for the assertion the reporter collapses
+- 🚚 A migration you can verify — `vitest-auto-spy/diagnostics`: `compareTestRuns` on the two JSON reports, `summarizeTestRun` / `formatTestRunComparison` to read the answer, `diffByField` for the assertion the reporter collapses, `explainSpy` for a double that answered something you did not configure
 - 📏 Lint rules and one-line test-run hygiene — nineteen rules in `vitest-auto-spy/eslint-plugin` (three `--fix`, seven suggestions, four of them for a suite mid-migration off jasmine), `setupAutoSpy()`
 - 🩺 [Editor diagnostics](#editor-diagnostics--webstorm--vs-code) — the same anti-patterns underlined while you type: native ESLint inspections in **WebStorm** and the other JetBrains IDEs, the ESLint extension in **VS Code**, no extra plugin either way
 - 🔎 [`npx vitest-auto-spy doctor`](#the-cli--doctor-perf-codemod-and-init) — suite-level defects **that never fail a run**: a `tsconfig` `include` matching no file, a production module importing a spec, a `@jest-environment` pragma the runner never reads, config left behind for a runner that is gone. Read-only, no config, exits 1 in CI
@@ -125,6 +126,7 @@ includes — that one import is what keeps `returnSubject()` typed as rxjs's own
 - [How to mock](#how-to-mock)
   - [A service behind Angular DI](#how-to-mock-a-service-behind-angular-di)
   - [A service without DI](#how-to-mock-a-service-without-di)
+  - [An object the test already holds](#how-to-mock-an-object-the-test-already-holds)
   - [Reading a spy back from DI](#how-to-mock-reading-a-spy-back-from-di)
   - [A whole class's dependencies at once](#how-to-mock-a-whole-classs-dependencies-at-once)
   - [A readonly property or a signal](#how-to-mock-a-readonly-property-or-a-signal)
@@ -147,6 +149,7 @@ includes — that one import is what keeps `returnSubject()` typed as rxjs's own
 - [Migrating from jest-auto-spies](#migrating-from-jest-auto-spies)
 - [Migrating from jasmine-auto-spies](#migrating-from-jasmine-auto-spies)
 - [Migrating from @ngneat/spectator](https://asdalexey.github.io/vitest-auto-spy/migrating-spectator)
+- [Migrating from @testing-library/angular](https://asdalexey.github.io/vitest-auto-spy/migrating-testing-library-angular)
 - [Configuration](#configuration)
   - [Spying instance-assigned callables (`signal()`, arrow props, `signalStore()`)](#spying-instance-assigned-callables-signal-arrow-props-signalstore)
   - [Strict doubles — fail on a method nobody configured](#strict-doubles--fail-on-a-method-nobody-configured)
@@ -176,6 +179,7 @@ includes — that one import is what keeps `returnSubject()` typed as rxjs's own
   - [Which factory, and what it costs](#which-factory-and-what-it-costs)
 - [Utilities](#utilities)
   - [Console spies — `vitest-auto-spy/console`](#console-spies--vitest-auto-spyconsole)
+  - [Why a spy answered what it did — `explainSpy`](#why-a-spy-answered-what-it-did--explainspy)
 - [Observable assertions](#observable-assertions)
 - [Test-run hygiene](#test-run-hygiene)
 - [Fake timers](#fake-timers)
@@ -290,6 +294,8 @@ error  tsconfig-glob-matches-nothing libs/users/tsconfig.spec.json
 | `coverage-include-recompiles-globs` | A coverage scope large enough that `picomatch` recompiling it per file costs more than the coverage. Info        |
 | `jasmine-era-project`               | `jasmine-core`, `@types/jasmine`, `karma.conf.*` or `@hirez_io/observer-spy` still installed. Info, not an error |
 | `no-agent-instructions`             | No instruction file names the package. A note, not an error                                                      |
+| `helper-from-wrong-entry`           | A named import taken from an entry that does not export it — `provideAutoSpy` from the root                      |
+| `no-unawaited-helper`               | An `expectEmission` / `stable` / `flushEventLoop` call dropped as a bare statement, so nothing awaits it         |
 
 The check that motivated the tool: a spec showing `Cannot find name 'vi'` in the editor while
 `tsc --noEmit` reported zero errors. A migration codemod editing `include` had eaten a `/**`,
@@ -298,6 +304,16 @@ spec tsconfigs still covered their specs.
 
 `doctor` never writes. There is no `--fix`.
 
+The last two checks resolve a **name**, and both read the same table: the entry each helper is
+exported from, generated from this package's own `exports` map by compiling the barrels and reading
+the symbols back out of the compiler. That table is why they are `doctor` checks and not lint rules
+— a per-file linter has none. Both are conservative in the same way: the callee has to have been
+imported from this package in that same file (a rename with `as` still counts), `no-unawaited-helper`
+reports only a call that both begins and ends a statement, and the pair goes quiet when the installed
+major differs from the table's, because a helper moves between entries only in a major. Over this
+repository's own 755 source files they report nothing outside their own fixtures. Neither has a
+fixer.
+
 ### `perf` — where the CPU time actually goes
 
 Vitest prints one summary line per run with a phase breakdown; it is the only place those numbers
@@ -720,6 +736,48 @@ const gateway = createAutoMock<PaymentGateway>(); // from a type/interface alone
 The constructor is never called, so no side effects run. `createAutoMock<T>()` is for the case
 where there is no runtime class to read — an interface, a type alias, an imported `.d.ts`.
 
+### How to mock: an object the test already holds
+
+Every factory above _constructs_ the double, which is no help once the object exists and other code
+already points at it — a service a factory built, a third-party client, a half-real
+`TestBed.inject(X)`. `createSpyFromInstance` patches that object **in place**:
+
+```ts
+import { createSpyFromInstance, restoreSpiedInstance } from 'vitest-auto-spy';
+
+const client = new PaymentsClient(config); // real, and already wired into the code under test
+const spy = createSpyFromInstance(client); // same object, now typed as Spy<PaymentsClient>
+
+spy.charge.calledWith(100).resolveWith({ ok: true });
+await checkout.pay(100);
+
+expect(spy.charge).toHaveBeenCalledWith(100);
+restoreSpiedInstance(client); // client.charge is the real method again
+```
+
+Mutating rather than copying is the whole point: anything that captured the object before the spec
+ran — a closure, a DI container, a live subscription — sees the spies. Discovery is the object's own
+function-valued fields _plus_ every prototype method up to but not including `Object.prototype`, so
+an arrow-function property needs no `instanceMethodsToSpyOn` here and `hasOwnProperty` / `toString`
+are never replaced. The configuration is `createSpyFromClass`' — `methodsToSpyOn`,
+`onlyMethodsToSpyOn`, `instanceMethodsToSpyOn`, the array shorthand, `observablePropsToSpyOn`,
+`gettersToSpyOn`, `settersToSpyOn`, `autoSpyAccessors`, `returns`, `overrides`, `strict`,
+`onUnstubbedCall` — minus the two that describe a double being built rather than an object being
+patched: `lazySpies` (the members already exist) and `fillMissing` (an instance is not an erased
+`abstract` declaration).
+
+Every write is journaled through the same mechanism as the [`mock*Prop` helpers](#how-to-mock-a-readonly-property-or-a-signal),
+so there are three ways back and they compose: `restoreSpiedInstance(instance)` for one object mid-test,
+`restoreMockedProps()` for the sweep `setupAutoSpy()` already runs, and
+`using spy = createSpyFromInstance(client)`, whose dispose **restores** rather than merely resets —
+the only sense disposal can have for an object the consumer owns. A frozen or sealed instance, and a
+member defined with `configurable: false`, are reported with the object described and the repair
+named rather than as a bare `TypeError`.
+
+Nothing else in the field does this: `vi.mockObject` is Vitest-only, `sinon.createStubInstance`
+builds a new object from a constructor instead of patching the one you hold, and `bun:test` and
+`node:test` have nothing.
+
 ### How to mock: reading a spy back from DI
 
 ```ts
@@ -1037,11 +1095,19 @@ Node / Bun / React / Vue project pulls **neither rxjs nor Angular into its runti
 > file while every Angular consumer imports `/angular` alongside it. The root now reaches the loader
 > as **2 modules instead of 8** and `/angular` as **2 instead of 10** — measured at ~0.8 ms less per
 > spec file for the root and ~1.0 ms for an Angular consumer, at a cost of ~120 kB in a dev-only
-> dependency that never reaches a production bundle. The four modules that hold process-wide state
+> dependency that never reaches a production bundle. The five modules that hold process-wide state —
+> `mock-adapter`, `observable-support`, `jasmine-support`, `package-identity` and `emission-timeout` —
 > stay in one shared `dist/shared-state.js` that every ESM entry imports, so there is still exactly
 > one mock-adapter registry — two copies of it is what `No mock adapter registered` and
-> `Observable spies require rxjs` used to mean. Only these two entries: de-chunking them all
-> costs +429 kB and duplicates the registries.
+> `Observable spies require rxjs` used to mean. Only the **state** goes in, never the code that reads
+> it: `expect-emission` used to be the member, and it dragged its 10 kB of pure helper into every
+> entry that imports the shared file. Splitting it so that only its `defaultTimeoutMs` cell —
+> `emission-timeout` — is pinned, while the helper is code-split normally, took **−10.0 kB** off the
+> module graph of `/rxjs`, `/console`, `/nestjs`, `/setup`, `/jasmine`, `/jasmine-compat` and
+> `/dom-stubs`, none of which export an emission helper, and **−2.5 kB** off the eight entries that
+> do — module count unchanged on every entry, `/setup` min+gzip 12 092 → 12 072 B, measured
+> 2026-09-04. Only these two entries: de-chunking them all costs +429 kB and duplicates the
+> registries.
 
 ```ts
 import { createSpyFromClass } from 'vitest-auto-spy';
@@ -1481,6 +1547,14 @@ is `createNestUnit(S)` and `TestBed.sociable(S).expose(D).compile()` is
 refuses, is in
 [Migrating from @suites/unit](https://asdalexey.github.io/vitest-auto-spy/migrating-suites).
 
+On [`@testing-library/angular`](https://github.com/testing-library/angular-testing-library) there is
+one page here that tells you to **keep** the library you came from. `render`, `screen` and the query
+set have no twin in this package and should not move; what overlaps is the secondary
+`/vitest-utils` entry point alone — 52 lines, four exports, `createMock` → `createSpyFromClass` and
+`provideMock` → `provideAutoSpy`, with the eager walk and the two defects
+[above](#testing-libraryangular-vitest-utils) as the reason to make the swap:
+[Migrating from @testing-library/angular](https://asdalexey.github.io/vitest-auto-spy/migrating-testing-library-angular).
+
 ## Configuration
 
 ```ts
@@ -2390,6 +2464,7 @@ single-purpose utility you can pick up independently — they all ride on the sa
 | `moduleNamespace(exports, opts?)`                                                        | core                          | The `vi.mock` factory result an interop probe recognises — `default` + `__esModule` in place                                                                                                          |
 | `diffByField(actual, expected)`                                                          | core                          | Which field of an array of records moved, and in how many elements — the diff the reporter collapses                                                                                                  |
 | `captureArg<T>()`                                                                        | core                          | Take hold of a callback or config the code under test built, instead of describing its shape — assertions only, never `calledWith`                                                                    |
+| `explainSpy(spy, method?)`                                                               | `/diagnostics`                | Every configured argument list next to every recorded call, each attributed to the config it hit — before anything failed                                                                             |
 | `asInstances(...spies)`                                                                  | core                          | `asInstance` for a whole argument list — one edit against one compiler error, not five                                                                                                                |
 | `narrow(value, guard)` / `narrow.byKey` / `narrow.observable`                            | core                          | The branch of a union a test knows it got, failing with the shape the value actually had                                                                                                              |
 | `withOverrides(model, overrides?)`                                                       | core                          | A fixture from a model instance: its getters read once, as data — a spread drops them                                                                                                                 |
@@ -2417,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))                                                               |
@@ -2477,6 +2553,47 @@ service.doWork();
 expect(fakeConsole.info).toHaveBeenCalledWith('done');
 ```
 
+### Why a spy answered what it did — `explainSpy`
+
+`mustBeCalledWith` already prints wanted next to actual — but only on the call that breaks. While a
+test is red for some _other_ reason, the question is different: which of my configs did this call
+hit, and which one never fired at all. `explainSpy` answers it on demand.
+
+```ts
+import { explainSpy } from 'vitest-auto-spy/diagnostics';
+
+console.log(explainSpy(users)); // every spied member; explainSpy(users, 'load') for one, explainSpy(users.load) for a bare spy
+```
+
+```text
+[vitest-auto-spy] explainSpy
+
+load — 3 calls, 2 configured
+  configured:
+    #1 calledWith(1)
+    #2 calledWith(Any<String>)
+  calls:
+    #1 load(1) -> matched #1
+    #2 load(2) -> no configured arguments matched; the default value was used
+    #3 load('ada') -> matched #2
+
+save — 1 call, nothing configured
+  calls:
+    #1 save('ada')
+
+remove — never called, 1 configured
+  configured:
+    #1 mustBeCalledWith(9)
+```
+
+`calledWith` and `mustBeCalledWith` share one numbering, so a call names a single number whichever
+chain answered it. An accessor spy appears as `get name` / `set name`, read from the double's
+`accessorSpies` bag so that naming one never invokes the live accessor. It never throws — a foreign
+mock, or anything that is not one of this library's doubles, is reported as one in the text, because
+this is reached from a spec that is already failing. The wording is a diagnostic, not an API: print
+it, never assert on it. Full reference:
+[explainSpy](https://asdalexey.github.io/vitest-auto-spy/utilities/explain-spy).
+
 ## Observable assertions
 
 `expect(...)` inside a `subscribe()` callback is the most common way to write a test that passes
@@ -2517,6 +2634,16 @@ saved$ did not emit within 1000 ms (0 emission(s) received). Either the stream n
 the trigger and any provider spy feeding it — or it is slower than the timeout; …
 ```
 
+**The code frame opens your spec line, not this package.** These helpers build their failure inside
+a `subscribe` or timer callback, long after the call returned, so the stack the runner used to see
+started in `node_modules/vitest-auto-spy/…` and carried no spec frame at all. The stack is now
+captured at helper entry, before anything subscribes, and pinned onto the failure when it is finally
+built — so the frame the reporter shows is the `await expectEmission(…)` line. Only errors these
+helpers build themselves are re-anchored: the error `expectError` resolves with belongs to the code
+under test and keeps the stack it was created with. `vi.defineHelper`, which covers the helpers that
+throw while the caller's frame is still live, cannot serve these — its `__VITEST_HELPER__` frame
+lands last and Vitest then drops the stack whole, code frame included.
+
 | Option    | Default | Notes                                                        |
 | --------- | ------- | ------------------------------------------------------------ |
 | `timeout` | `1000`  | Milliseconds to wait. `0` waits indefinitely                 |
@@ -2607,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                                                                                 |
 | --------------------- | --------- | ------------------------------------------------------------------------------------- |
@@ -2620,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               |
@@ -3015,6 +3153,8 @@ another, and the next one is in that same file.
 | Export                                                                                                            | Description                                                                                                                                           |
 | ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `createSpyFromClass(Class, methodsOrConfig?)`                                                                     | Build a fully-typed `Spy<T>` from a class                                                                                                             |
+| `createSpyFromInstance(instance, methodsOrConfig?)`                                                               | Patch an object the test already holds **in place**, so everything that captured it sees the spies                                                    |
+| `restoreSpiedInstance(instance)`                                                                                  | Put one spied instance back — `restoreMockedProps()` and `using` do the same, and all three compose                                                   |
 | `createAutoMock<T>(overrides?, config?)`                                                                          | Build a `Spy<T>` from a **type/interface** alone (Proxy, no class); `{ returns, observablePropsToSpyOn }` configure it                                |
 | `createMock<T>(partial?)`                                                                                         | Build a plain, spy-free `T` from the fields a test seeds — for data shapes the code under test reads                                                  |
 | `createFixture<T>(defaults, overrides?)` / `createFixtureFactory<T>(defaults)`                                    | A model written out and checked once, stamped into a fresh copy per test — for the fixture eight specs would otherwise each keep a copy of            |
@@ -3063,6 +3203,7 @@ another, and the next one is in that same file.
 | `guardGlobalPatches(reaction)` / `installPerTest(install)` _(`/setup`)_                                           | Name the test that sealed a global property; re-install a stub before every test                                                                      |
 | `consoleDebugSpy` … `consoleWarnSpy` _(`/console`)_                                                               | Silent typed spies replacing the global `console` methods on import                                                                                   |
 | `installConsoleSpies()` / `resetConsoleSpies()` / `restoreConsole()`                                              | Install / clear / undo the console spies                                                                                                              |
+| `explainSpy(spy, method?)` _(`/diagnostics`)_                                                                     | Every configured argument list next to every recorded call, attributed to the config it hit                                                           |
 | `errorHandler`                                                                                                    | The `mustBeCalledWith` argument-mismatch error helper                                                                                                 |
 
 **Spied sync method:** `mockReturnValue`, `calledWith(...)`, `mustBeCalledWith(...)` — `calledWith`

package/dist/angular.d.ts

@@ -1,10 +1,10 @@
-export { l as AngularTokenProvider, A as AngularValueProvider, a as AutoSpiedInstance, C as ComponentInputs, b as CreateWithAutoSpiesOptions, R as RenderShallowOptions, c as ResourceStatusLike, S as SettleResourceOptions, d as ShallowRender, e as SpyRegistry, f as StableOptions, g as createWithAutoSpies, h as flushEffects, i as injectSpy, p as provideAutoSpy, m as provideAutoSpyForToken, r as renderShallow, j as runEffect, s as settleResource, k as stable } from './zoneless-DGwkbWKm.js';
+export { l as AngularTokenProvider, A as AngularValueProvider, a as AutoSpiedInstance, C as ComponentInputs, b as CreateWithAutoSpiesOptions, R as RenderShallowOptions, c as ResourceStatusLike, S as SettleResourceOptions, d as ShallowRender, e as SpyRegistry, f as StableOptions, g as createWithAutoSpies, h as flushEffects, i as injectSpy, p as provideAutoSpy, m as provideAutoSpyForToken, r as renderShallow, j as runEffect, s as settleResource, k as stable } from './zoneless-LsBDcSNZ.js';
 import { InjectionToken, Provider, Type, Signal, WritableSignal } from '@angular/core';
 import { TestAPI } from 'vitest';
 import { C as ClassType, S as Spy, k as ClassSpyConfiguration, o as OnlyMethodKeysOf, g as AddSpyMethodsByReturnTypes } from './types-CQLPjw8z.js';
 export { I as InjectionLog, T as TrackInjectionsOptions, a as TrackedProvider, t as trackInjections } from './track-injections-CAqxzlhV.js';
 export { A as AccessorImplementations, R as RestoreProp, c as countMockedProps, m as mockAccessorsProp, a as mockReadonlyProp, b as mockReadonlyPropGetter, d as mockValueProp, r as restoreMockedProps } from './prop-mock-Dp2ZMFqj.js';
-export { C as CallbackSubscribable, E as EmissionObserver, a as EmissionOptions, b as EmissionSource, S as SubscribableLike, e as expectCompletion, f as expectEmission, g as expectEmissions, h as expectError, i as expectNoEmission, s as setEmissionTimeout } from './expect-emission-BDuFuqTb.js';
+export { C as CallbackSubscribable, E as EmissionObserver, a as EmissionOptions, b as EmissionSource, S as SubscribableLike, e as expectCompletion, f as expectEmission, g as expectEmissions, h as expectError, i as expectNoEmission, s as setEmissionTimeout } from './expect-emission-Dy5CvsF2.js';
 import '@angular/core/testing';
 
 /**