# vitest-auto-spy — instructions for AI coding agents You are looking at the agent-facing reference for **`vitest-auto-spy`**: typed test spies generated from a class, a type, or nothing at all, on Vitest / `bun:test` / `node:test` / Rstest. This file is written for an agent **using** the library in someone's test suite. It is shipped inside the npm package, so it is readable with no network: ``` node_modules/vitest-auto-spy/AGENTS.md ``` Working on the library's own source instead? Read `CONTRIBUTING.md` in the repository. Setting this up for a team? `npx vitest-auto-spy init` writes a pointer to this file into the instruction files this repository's agents actually read — `AGENTS.md` (Codex, Cursor, Copilot and most of the field), `CLAUDE.md` (Claude Code) and `GEMINI.md` (Gemini CLI), plus the glob-scoped rule file of any tool whose own directory already exists. `--check` is the CI form. Full table: . | Resource | Where | | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Spec patterns at scale | | | Task recipes | · `/guides/mocking-local-storage` · `/guides/mocking-prisma` · `/guides/storybook-angular` | | Docs index for LLMs | | | Entire docs as one file | | | Human docs | | | Source | | | Types | `node_modules/vitest-auto-spy/dist/index.d.ts` (and one per subpath) | **Read `dist/*.d.ts` before inventing a call.** Every export is typed and documented there, and the type is the authority when this file and the code disagree. --- ## 1. Pick the entry point first Each entry registers its mock adapter **on import**. Importing the wrong one leaves the wrong adapter installed and spies fail at runtime. | Runner / framework | Import from | | -------------------- | ----------------------------- | | Vitest (default) | `vitest-auto-spy` | | `bun test` | `vitest-auto-spy/bun` | | `bun test` + Angular | `vitest-auto-spy/bun-angular` | | `node --test` | `vitest-auto-spy/node` | | `rstest run` | `vitest-auto-spy/rstest` | | Angular + Vitest | `vitest-auto-spy/angular` | | NestJS | `vitest-auto-spy/nestjs` | | React | `vitest-auto-spy/react` | | Vue / Pinia | `vitest-auto-spy/vue` | | Svelte | `vitest-auto-spy/svelte` | Add-ons, orthogonal to the runner: | Add-on | Import | Needed for | | ------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Observable spies | `import 'vitest-auto-spy/rxjs'` | `nextWith` & friends. **Side-effect import, once**, and in a file the `tsconfig` includes (§4) | | observer-spy shim | `vitest-auto-spy/observer-spy` | `subscribeSpyTo` — the `@hirez_io/observer-spy` surface (§20). Its own entry so `/rxjs` does not carry it | | Console spies | `vitest-auto-spy/console` | silent typed spies over the global `console` — `installConsoleSpies()` per test, `restoreConsole()` after | | DOM stubs | `vitest-auto-spy/dom-stubs` | `stubIntersectionObserver` / `stubResizeObserver` / `stubMutationObserver` / `stubObserver`, `stubMediaElement`, `stubAbortController`, `stubWebStorage` (§12), `intersectionEntry` / `resizeEntry` / `mutationRecord`. **Moved off the root in 4.0.0** | | Run diagnostics | `vitest-auto-spy/diagnostics` | `compareTestRuns`, `summarizeTestRun`, `formatTestRunComparison`, `diffByField`. **Moved off the root in 4.0.0** | | Angular HTTP | `vitest-auto-spy/angular-http` | `provideHttpTesting`, `expectRequest` — `httpResource()` / `HttpClient` (§13). Optional `@angular/common` peer, this entry only | | Angular router | `vitest-auto-spy/angular-router` | `provideActivatedRoute`, `injectActivatedRoute` — an `ActivatedRoute` whose streams and snapshot share one record; `provideRouterDouble`, `injectRouterDouble` — a `Router` whose URL, `routerState` and `events` agree (§13). Optional `@angular/router` peer, this entry only | | Angular diagnostics | `vitest-auto-spy/angular/diagnostics` | `enableAngularDiagnostics` and the whole TestBed timing family (§13). Companion to `/angular` like `/angular-http` — no core re-export; **moved off `/angular` in 5.21.0** so importing spies stops evaluating it | | Angular doubles | `vitest-auto-spy/angular/doubles` | The Material dialog trio and the `Window`/`Document` platform doubles (§13). Companion to `/angular`; registers the Vitest adapter, so its doubles spy out of the box; **moved off `/angular` in 5.21.0** | | Angular matchers | `vitest-auto-spy/angular/matchers` | `registerDirectiveMatchers`, `registerResourceMatchers`, `registerSignalMatchers` (§13). Companion to `/angular` — no core re-export; **moved off `/angular` in 5.21.0** | | Signal forms | `vitest-auto-spy/signal-forms` | `createForm`, `registerFormMatchers` — a signal form built where `form()` can inject, and `toHaveFieldErrors` over what it produced (§13). Optional `@angular/forms` peer, this entry only; Angular 22+ | | Setup helpers | `vitest-auto-spy/setup` | `setupAutoSpy()`, `setupFakeTimers()`, `blockNetwork()`, `stubResponse()`; the entry imports Vitest, so it is not for `bun test` | | Zone patch | `import 'vitest-auto-spy/zone'` | `fakeAsync` / `waitForAsync` on Vitest (§14) | | jasmine compat | `vitest-auto-spy/jasmine` | `.and` / `.calls` / `.withArgs`, the `jasmine` namespace (§20) | `vitest-auto-spy/jasmine` is Vitest-only, because it registers the Vitest adapter. On `bun test` and `node --test` call `enableJasmineCompat()` from `vitest-auto-spy/jasmine-compat` instead. `vitest-auto-spy/setup` is Vitest-only as well — `setupAutoSpy()` registers Vitest hooks. On `bun test` nothing restores a `spyOn`, a `mock*Prop` patch or a file-scope auto-spy between tests; put `afterEach(() => { restoreMockedProps(); mock.restore(); })` in a `--preload` file, and any `mock.module()` there too (inside a test it swaps bindings after the original module already ran). The rxjs peer is **>= 7.2**, not `>=7`. The observable layer used to pull `concatMap`, `delay`, `switchMap`, `take`, `takeUntil` and `takeWhile` from `rxjs/operators`; rxjs 8 removes that deep path, so the specifier moved to the root `rxjs` entry — which is where rxjs re-exported them in 7.2 — and the floor moved with it. Any Angular project already satisfies it: Angular 16 through 22 all peer on `^6.5.3 || ^7.4.0`. The Angular entries need **Angular >= 20** — `@angular/core`, `@angular/common`, `@angular/platform-browser` and `@angular/router`, all optional peers on the same range. Below 20 the failure is a link error, not a missing helper: `/angular` imports `ɵSIGNAL` (Angular 18+) as a value on the first line of its bundle, so on 16 and 17 the whole entry fails to load, and `/bun-angular` imports `provideZonelessChangeDetection` (Angular 20+; called `provideExperimentalZonelessChangeDetection` in 18 and 19), so on anything older the preload throws before the first spec. Angular 19 and everything under it is out of Angular's own support window as well, so the floor cuts nothing that still gets fixes. `@angular/platform-browser` is a declared peer since this major — `By` in the directive matchers and `platformBrowserTesting()` in the Bun preload are both value imports of it, and under pnpm's isolated layout it never resolved before. The package is **ESM**. Only `vitest-auto-spy/node` and `vitest-auto-spy/eslint-plugin` also ship a CommonJS build; every other subpath is ESM-only (a `require()` of a Vitest-backed entry always threw — Vitest refuses to be required). The plugin's CommonJS declaration is an `export =`, which is what `require('vitest-auto-spy/eslint-plugin')` actually returns — an `eslint.config.cts` / `.cjs` used to type-check the call that throws and reject the one that works. `vitest-auto-spy/package.json` resolves as well. Tools that read a dependency's manifest by specifier — Storybook, Nx, a renovate helper — used to get `ERR_PACKAGE_PATH_NOT_EXPORTED` and had nowhere to go from there. **Every peer is optional now, `vitest` included.** The range is unchanged (`>=2.1.0`); what changed is that a suite on `/bun` or `/node`, which never loads the Vitest runner, no longer installs it to satisfy a peer. The one thing still to know is that `/bun`, `/bun-angular` and `/node` declarations name Vitest's `Mock` type, so a project type-checking those entries without `vitest` installed will want it as a devDependency anyway; freeing that is a type change and waits for a major. --- ## 2. Pick the factory ``` Do you have a real class at runtime? ├── yes → createSpyFromClass(Class, config?) → Spy │ (an `abstract class` DI token counts — see below) └── no → Is the double CALLED by the code under test? ├── yes, and it is INJECTED (DI, a field) → createAutoMock(overrides?) → Spy ├── yes, and it is an ARGUMENT of the function under test, asserted on │ → autoMocked(overrides?) → T & Spy ├── yes, and reads chain (a.b.c()) → mockDeep(overrides?) → DeepMockProxy ├── yes, and CALLS chain (a.b().c()) → mockDeep({}, { selfReturning: true }) └── no, it is only READ (DTO, config, route snapshot) ├── one spec, a couple of fields → createMock(partial?) → T (no spies) └── many specs, one shared model → createFixtureFactory(defaults) → (overrides?) => T Object already built, other code already holds it? → createSpyFromInstance(obj, config?) → Spy, patched IN PLACE One standalone function? → createFunctionSpy('name') Code under test does `new Foo()`? → a real class? createSpyClass(Foo) → only a shape? mockConstructor(() => instance) → on a global? stubConstructor(globalThis, 'Image', factory) (a vi.fn() rejects `new` — see §12) ``` `createAutoMock` and `autoMocked` build the same object; they differ only in the type you get back, and the question that decides it is **how the double travels**. Through DI, it arrives as `Spy` and is only ever asserted on — `createAutoMock`. Handed to the function under test as an argument (`detectVpnClient(url, logger)`, `applyPreferredTracks(target, …)`, `setLocalConfigEnabled(storage, …)`), it has to satisfy `T` at the call site _and_ expose the spy helpers at the assertion, and `autoMocked()` is that intersection — otherwise every call site needs an `asInstance()` and the noise scales with the number of them. Both take the same second argument (`returns`, `name`, `strict`, `observablePropsToSpyOn`). `createMock()` 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. `createMock(undefined)` is the same call as `createMock()` and answers `{}`, **not** `undefined` — a forwarding helper with an optional `overrides` parameter relies on that. A fixture that means "no value" passes `undefined` itself: `getters.profile.mockReturnValue(undefined)`, never `mockReturnValue(createMock(undefined))`. **`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`, 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. **`passthrough: true` keeps the patched object working.** Unconfigured methods run the real implementation (with the instance as `this`) and are still recorded; any configuration takes the whole method over and `resetAutoSpy` hands it back. The Angular shape is `createSpyFromInstance(TestBed.inject(CartService), { passthrough: true })` — dependencies, `signal()` fields, `ɵprov` and the real `ngOnDestroy` keep working. Lifecycle hooks, discovered callables with an API of their own (signals) and discovered classes are left real rather than spied. Do **not** combine it with `strict: true` or `onUnstubbedCall` on the same call — that throws; a suite-wide strict yields to it. A `calledWith(1)` miss answers `undefined`, not the real method: configuring a method hands the whole method over. Use it to assert an interaction on a real collaborator; use a plain double when the test must not touch the real one. **`createFixture(defaults, overrides?)` / `createFixtureFactory(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 of in eight copies of a hundred-line literal. Overrides are deep-partial-checked and merge leaf by leaf; an overridden array replaces the default one. Every call hands back a fresh object and the defaults are copied at build time, which is what keeps one test's mutation out of the next test — across files, under `isolate: false`. The copy is deep through plain objects and arrays only: a `Date`, a `Map` or a class instance travels by reference, because rebuilding it would strip its prototype. Defaults that are a class instance with getters go through `withOverrides()` first. **`mockDeep` builds depth on property access, not on calls** — the distinction the tree now spells out, and the one that costs an afternoon otherwise. `mock.repo.user.find()` chains because every hop but the last is a _read_. A node that is **called** returns what it was configured to return, and by default that is `undefined`, so `mockDeep().channel('app').info('x')` is a `TypeError` at the second call — while `DeepMockProxy` types it perfectly, so nothing warns. Pass `{ selfReturning: true }` for a fluent API, or use `createAutoMock(undefined, { selfReturning: ['channel'] })` when only one method chains: ```ts const logger = mockDeep({}, { selfReturning: true }); logger.channel('app').info('started'); expect(logger.channel('app').info).toHaveBeenCalledWith('started'); ``` Both bridges exist, and which one you need depends on the direction. What a self-returning **call** hands back is typed as the _declared_ return type, not as a spy — `asSpy(…)` when the helpers are needed. The **whole mock** is a `DeepMockProxy`, which is not assignable to `T` for the same reason `Spy` is not (a mapped type cannot see private members) — `asInstance(…)` when it has to go somewhere typed against the real thing: ```ts const logger = mockDeep({}, { selfReturning: true }); boot(asInstance(logger)); // → AppLogger, for the API under test asSpy(logger.channel('app')).info.mockReturnValue(undefined); // → the helpers ``` **Arrays and unmocked calls on `mockDeep`.** A member read by a numeric index (`api.items[0]`) is a real `Array` of deep mocks from then on, and `map`, iteration and `toEqual` work on it. Read the member again after the first index: a handle taken before the first index is still a node. To make a call nobody configured fail, use `mockDeep({}, { fallbackMockImplementation: () => { throw … } })`. Options go in the **second** argument, not the first as in vitest-mock-extended. The precedence is configuration > fallback > `selfReturning`. A `calledWith` miss answers `undefined`, not the fallback; use `mustBeCalledWith` for "other arguments fail". For a callback API (`$transaction`), use `method.mockImplementation((run) => run(asInstance(mock)))`; there is no option for it. `vi.spyOn(mock.repo, 'find')` works on a member nobody has read and returns the node's own spy. `asInstance` did not take a deep mock before 3.5.0, which left it with nowhere to go: this tree sends you to `mockDeep` when the calls chain, and the result then fitted nothing that expected `T`. **A deep node asks what the spy surface is on every read**, rather than remembering the answer from the first deep mock of the worker. That matters under `isolate: false`, where the surface grows mid-run: `import 'vitest-auto-spy/rxjs'` in a later file adds `nextWith` and friends, and `setSpyEngine` swaps the whole prototype. With the answer cached, `deep.feed.items.nextWith(1)` in every double built after that resolved to a **child node** — callable, recorded, emitting nothing — while the spec waited on a stream that was never fed. **`selfReturning: true` chains a factory, not a `return this` builder**, and the difference decides where the calls are recorded. A called node answers _itself_, not the object the method was read off, so every hop moves one level deeper: `editor.chain().focus().insertContent('text')` records `insertContent` on `chain.focus`, while the `chain` handle the spec is holding still has none — and `expect(chain.insertContent).toHaveBeenCalled()` reports nothing although the chain ran. Either walk the same path in the assertion, or, for an API where every command answers the **same** object (tiptap's `ChainedCommands`, a query builder, a `mockReturnThis()` chain), build that object with `createAutoMock` instead, where `selfReturning` names methods that answer one double: ```ts const chain = createAutoMock(undefined, { selfReturning: ['focus', 'insertContent'] }); const editor = createAutoMock(undefined, { returns: { chain: asInstance(chain) } }); editor.chain().focus().insertContent('text').run(); expect(chain.insertContent).toHaveBeenCalledWith('text'); // one double, so the assertion is the obvious one ``` **An `abstract class` is a class.** `abstract class LocalStorage extends AbstractStorage {}`, provided in production as `{ provide: LocalStorage, useClass: BrowserLocalStorage }`, is the standard Angular DI-token idiom, and `provideAutoSpy(LocalStorage)` / `createSpyFromClass(LocalStorage)` take it — type and runtime both. Abstract members are erased before they reach a prototype, so there is nothing to read there; when discovery comes back empty the factory hands back the `createAutoMock` proxy instead of an empty object, and every method answers. Nothing to configure, and no reason to reach for `{ provide: X, useValue: createAutoMock() }` by hand any more. That holds while the class is **fully** abstract. One concrete member — a helper, a getter — and discovery is no longer empty, the fallback does not fire, and every `abstract` member is missing while `Spy` types it as present: the read is `undefined` and the call dies as `… is not a function` in production code. Pass `{ fillMissing: true }` there (`provideAutoSpy(LocalStorage, { fillMissing: true })`), which answers a name the prototype never carried with a spy. It is opt-in because `abstract` is erased at runtime — filling every unknown key by default would silence a real typo on every concrete class. **`overrides: { key: undefined }` is a seed, not an omission**, and the difference is load-bearing. `createAutoMock` reads its seed with `Reflect.ownKeys`, so a key written out with an explicit `undefined` **is** in the store: reading it answers `undefined`. Leave it out and the same read materialises a _function spy_ — which is truthy, and sends `if (this.lastFocus)` down the branch the spec was trying to close: ```ts createAutoMock({ currentFocus: undefined, navRoot: undefined, selectors: 'button, a' }); // ^ "this member is data, and there is none" — not the same as omitting it ``` This is the way to say "the member exists and is empty", and it is worth writing even when it looks redundant. **A getter in `overrides` stays a getter.** The seed is kept as a descriptor rather than read once while the double is assembled, so it runs at every read, with the double as `this` — and a seed written to **throw** ("this global is missing on this platform") fails where the code under test reads the member, not where the provider literal is evaluated. A `{ set }` seed is kept the same way and takes the write. Both used to be flattened as the double was built, which turned a throwing seed into a failure during `TestBed.configureTestingModule`, three frames from the branch under test. A **registration** is no exception, and it was the half that stayed broken one release longer: the merge that puts `registerAutoSpyDefaults` under a call site copied both sides with a spread, so a seeded getter was flattened on any class or token the registry knows — whether or not the registration names that key — while the same seed stayed live on one it does not. The merge copies descriptors now, and the seed behaves the same either way. ### What a Proxy-backed double cannot do `createAutoMock` and `mockDeep` build a Proxy, not an object, and there is one place where the difference shows: a Proxy answers only the operations its handler traps. Three of them used to be missing, and each produced a _silent_ wrong answer rather than an error — the worst failure mode this library can have, because a checking test becomes a non-checking one and only the proxy's source says so. Two are fixed; the third cannot be: | Operation | Before 3.5.0 | Now | | --------------------------------- | ------------------------------------------------- | -------------------------------------------------------- | | `mockValueProp` & the other three | patch landed on the target; the double ignored it | works, and `restoreMockedProps()` undoes it | | `delete mock.optionalMethod` | deleted nothing; the next read remade the spy | the member is absent, until something writes to it again | | `Object.assign(real, mock)` | copies only the keys already **read** | still does — see below | `ownKeys` cannot be completed: a type has no key list at runtime, which is the whole premise of these two factories. So a spec that installs a double by **copying it onto a real instance** — `Object.assign(player, engineDouble)` — gets whichever members happened to be touched first, and every other call goes to the real implementation, silently. Use `createSpyFromClass` there: it returns an ordinary object whose method keys are enumerable (lazy accessors, but enumerable), so the copy is complete. ### It answers everything, so it must not answer _these_ The same premise cuts the other way. A library that is handed an object and has to decide **what kind of thing it is** asks by probing a key — and a double that answers every property answers the probe too, at which point it stops being a double of `T` and becomes whatever was being looked for. Four names are therefore answered with `undefined` unless the spec seeds them, alongside `then` and every symbol, which always were: | Key | Probed by | The double became | | -------------- | --------------------------------------------- | ----------------- | | `schedule` | `popScheduler` in `of` / `from` / `merge` / … | a scheduler | | `lift` | `isObservable`, with `subscribe` | an Observable | | `@@observable` | `isInteropObservable` in `innerFrom` | an interop stream | | `getReader` | `isReadableStreamLike` in `innerFrom` | a ReadableStream | The one that cost an afternoon reads like nothing at all: ```ts of(autoMocked()); // an Observable that never emits ``` `of(...)` takes its **last argument** for a scheduler when `typeof x.schedule === 'function'`, so the whole double was eaten as one, `of()` was left with an empty argument list, and the emission was scheduled onto a spy that does nothing. The component under test kept its `null`, and what failed was an assertion about an unrelated `emit()` three concerns away — nothing in the failure mentions `of`. The workaround people find is `from([double])`; it is not needed any more. **`subscribe` is deliberately not on that list.** It is an ordinary method name — a store, an Angular `OutputEmitterRef`, an event bus — and `expect(store.subscribe).toHaveBeenCalledWith(cb)` is a real assertion. Denying `lift` and `@@observable` already breaks the impersonation, so `subscribe` on its own fools nothing: `from(double)` now fails with rxjs's own _"You provided an invalid object where a stream was expected"_, loudly and in the right file. If your type genuinely has one of the four, say so once and it comes back — the list is consulted after the seed store: ```ts createAutoMock({ schedule: vi.fn() }); ``` That is the trade the deny-list makes: without a seed the member is absent and the failure is an immediate `TypeError: … is not a function` at the call site, instead of a silent one in another file. A key is only added to that list with an observed mechanic behind it — never because the name sounds protocol-ish — because every entry costs somebody the ability to mock a member of that name without seeding it. The tree asks whether the double is _called_, and there is a second question worth asking: whether the code under test **writes to it**. `createAutoMock` is a proxy with a `set` trap over the same cache its `get` trap answers from, so an assignment sticks and is read back — which makes it the double for a DOM-ish object a library drives by assigning handlers, where a hand-written fake is otherwise the only option: ```ts const xhr = createAutoMock({ status: 0, timeout: 0, onload: null, onerror: null }); xhr.send.mockImplementation(() => respond(asInstance(xhr))); // production does `xhr.onload = () => resolve(xhr.status !== 0)` — the proxy remembers it ``` --- ### Cost, so it stops being a question Building a spy is not a thing to optimise. On a ten-method class, `npm run bench` on Node v24.19.0 and Vitest 4.1.11, measured 2026-09-04: `createSpyFromClass` plus two methods called **2.25 µs**, plus all ten 5.83 µs, `createAutoMock` plus four members 1.79 µs, a `calledWith` lookup 0.21 µs — five providers across two thousand tests is about two hundredths of a second. Call the factory in `beforeEach` and look at `TestBed` instead. The only two settings that cost: `{ lazySpies: false }` gives up the laziness `provideAutoSpy` defaults to, and `autoSpyAccessors: true` walks the prototype chain uncached on every call — name the accessors instead. Memory used to be the exception, and it no longer is for the default. `lazySpies: true` still defines one property per method, but the accessor pair behind it is now **shared by method name** across every double in the process, so the placeholder is no longer what an untouched double retains: an untouched 100-method double holds **215 B** where it held 25 593, and a 300-method one 284 B where it held 70 165 (`npm run bench:memory`, 2026-09-17, Node 24). The price is paid at construction on very wide classes — building a 300-method double costs about 28 % more — and materialising every method of one is about 26 % cheaper in exchange. That inverts the case for `lazySpies: 'proxy'`, which answers every method from a single trap object: it now retains **4 090 B** against the default's 215 B at 100 methods — 19× more — and still pays a trap on every read (53 ns against 7 ns) for the life of the double, because a `Proxy` cannot remove itself while the default leaves a plain data property behind once a method materialises. What is left of its advantage is build time on a wide class. The option is unchanged and still supported; there is no longer a memory reason to reach for it. A frozen or sealed double is fine now. `Object.freeze(spy)` — a deep-freeze fixture helper, a dev-mode state guard — used to make the first read of any method throw `Cannot redefine property` from inside the placeholder's getter; the spy is kept beside the double instead, so the read answers a stable mock and `mockReturnValue` on it works. On a merely sealed double an assignment still reaches the member. `vi.spyOn(double, 'load')` on a method nobody has read yet works again. Vitest reads an accessor by calling its getter with no receiver, and 5.19.0's shared getter answered that with `TypeError: Invalid value used as weak map key`. The call now wraps a forwarder: a configured `mockReturnValue` answers, an unconfigured call reaches the double's own spy (strict guard included), and `mockRestore()` / `vi.restoreAllMocks()` hand back that same spy with the calls it recorded. It is still redundant — the member already is a spy, so `double.load.mockReturnValue(…)` is the line to write — and a wrapped method called off its double (`const { load } = double; load()`) throws a message saying so. **Symbol-keyed methods are discovered and spied.** A method under a symbol the project owns — `[SERIALIZE]()`, `Symbol.for('app.render')` — is a method like any other, resets with the rest and shows up in `Reflect.ownKeys`. The runtime's own protocol symbols are deliberately left alone (everything on `Symbol` itself — `Symbol.iterator`, `Symbol.dispose`, `Symbol.toPrimitive` and the rest — plus `Symbol.for('nodejs.util.inspect.custom')`), because a double that answers those stops being a double of `T` and starts impersonating an iterable or a disposable. Discovery covers methods only: a symbol-keyed **getter or setter** is not found by `autoSpyAccessors`, so patch one with `mockAccessorsProp` (§9). --- ## 3. The 90% recipe Measured across a ~370-file Angular suite: `provideAutoSpy` appears in 371 files, `injectSpy` in 308, `mockReadonlyProp` in 127, `instanceMethodsToSpyOn` in 103, `observablePropsToSpyOn` in 79 — and bare `createSpyFromClass` in only 41. **In an Angular app the spy almost always arrives through DI.** Write that shape first. ```ts import { signal } from '@angular/core'; import { TestBed } from '@angular/core/testing'; import { of } from 'rxjs'; import { type Spy, injectSpy, mockReadonlyProp, provideAutoSpy } from 'vitest-auto-spy/angular'; describe('TaskService', () => { let projects: Spy; let feed: Spy; let service: TaskService; beforeEach(() => { TestBed.configureTestingModule({ providers: [ provideAutoSpy(NotificationService), // plain service — nothing to configure provideAutoSpy(ProjectStore, { instanceMethodsToSpyOn: ['current', 'isEmpty'] }), // signals provideAutoSpy(NewsFeedService, { observablePropsToSpyOn: ['connected$'] }), // Observable props ], }); projects = injectSpy(ProjectStore); feed = injectSpy(NewsFeedService); feed.connected$.nextWith(true); // seed the defaults every test needs, once projects.save.mockReturnValue(of(true)); service = TestBed.inject(TaskService); }); it('saves through the store', () => { service.save(task); expect(projects.save).toHaveBeenCalledWith(task); }); }); ``` Outside Angular, or for a class you construct yourself: ```ts import { type Spy, createSpyFromClass } from 'vitest-auto-spy'; let users: Spy; beforeEach(() => { users = createSpyFromClass(UserService); }); it('loads', async () => { users.load.calledWith(1).resolveWith({ id: 1 }); await expect(subject.open(1)).resolves.toEqual({ id: 1 }); expect(users.load).toHaveBeenCalledWith(1); }); ``` Four conventions that carry most of the value: 1. **One `configureTestingModule` per `describe`** — reconfiguring per `it()` pays for module compilation on every test, the largest avoidable cost in an Angular suite. 2. **Declare each spy as `Spy`, never as `T`** (§6). 3. **Seed defaults in `beforeEach`, override in the test.** An unconfigured method returns `undefined`, and the failure surfaces far from its cause. 4. **`provideAutoSpy` is lazy by default** — listing a wide service costs nothing for the methods a test never touches. --- ## 4. Helpers a spied method earns from its return type Every spied method is a real runner mock, so `mockReturnValue`, `mockImplementation`, `toHaveBeenCalledWith` and the rest all work as usual. On top of that: | Return type | Helpers added | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | anything | `calledWith(...args)` → `.mockReturnValue(v)` / `.returnValue(v)` / `.failWith(err)`, `mustBeCalledWith(...args)` → same, `failWith(err)` | | `Promise` | `resolveWith(v)`, `rejectWith(v)`, `resolveWithPerCall([{ value }, …])` | | `Observable` | `nextWith(v)`, `nextOneTimeWith(v)`, `nextWithValues(configs)`, `nextWithPerCall(configs)`, `throwWith(v)`, `complete()`, `returnSubject()` | `Observable` **properties** (not just methods) get the same helpers — list them in `observablePropsToSpyOn`. **What counts as an `Observable` is structural, and no declaration names rxjs (4.0.0).** A member earns the observable bundle when its type satisfies the exported `ObservableLike` — `subscribe` plus a promise-returning `forEach(next)`: rxjs's `Observable`, every `Subject`, Angular's `EventEmitter` — and, new in 4.0.0, an `Observable` from a _second copy_ of rxjs in the tree, which used to fall through to the plain-spy branch and produce `nextWith is not a function` with nothing pointing at the duplicate. `Promise`, arrays, `Signal` and Angular's `OutputEmitterRef` are not observables and do not earn it. `returnSubject()` and `nextWithPerCall()` return `SubjectOf` — rxjs's own `Subject` wherever `import 'vitest-auto-spy/rxjs'` is in the TypeScript program, the structural `SubjectLike` (`next` / `error` / `complete` / `asObservable` / `closed`) where it is not. The switch is one augmentable interface, `AutoSpyRxjsTypes`, which `/rxjs` fills in with `subject: Subject`; augment it yourself only to plug in a different subject type. If `const s: Subject = spy.m.returnSubject()` fails to compile, the import is missing from the program the specs are checked in — usually a Vitest `setupFiles` entry that no `tsconfig` `include` covers. That is the _only_ breaking change in 4.0.0; the reason for it is that `dist/types-*.d.ts` used to open with `import { Observable, Subject } from 'rxjs'` and load 189 rxjs `.d.ts` files into every consumer's program (303 files against 114 without it), `import type` included — TypeScript resolves a type-only import the same way. ```ts // argument dispatch — other arguments return undefined users.getName.calledWith(1).mockReturnValue('Ada'); // argument enforcement — other arguments throw users.getName.mustBeCalledWith(1).mockReturnValue('Ada'); // asymmetric matchers work in both, at any depth users.save.calledWith(expect.objectContaining({ id: 1 })).mockReturnValue(true); users.save.calledWith({ id: expect.any(Number), tags: [expect.any(String)] }).mockReturnValue(true); // re-registering the same arguments replaces the answer — matcher arguments included users.save.calledWith(expect.objectContaining({ id: 1 })).mockReturnValue(false); // promises users.load.resolveWith({ id: 1 }); users.load.rejectWith('FAKE ERROR'); users.load.resolveWithPerCall([{ value: a }, { value: b }]); expect(users.load.mock.settledResults).toEqual([{ type: 'fulfilled', value: { id: 1 } }]); // observables — requires `import 'vitest-auto-spy/rxjs'` once feed.items$.nextWith([item]); // emit, stream stays open feed.items$.nextOneTimeWith([item]); // emit once, then complete feed.items$.nextWithValues([{ value: a }, { value: b, delay: 100 }, { complete: true }]); const [first$, second$] = feed.watch$.nextWithPerCall([{ value: 'a' }, { value: 'b', doNotComplete: true }]); feed.items$.throwWith('FAKE ERROR'); const subject = feed.items$.returnSubject(); // ReplaySubject, for anything the helpers miss // throwing — `failWith`, on a spy of any return type cart.checkout.failWith(new HttpErrorResponse({ status: 500 })); // every call throws cart.checkout.calledWith(BAD_ID).failWith(new Error('unknown cart')); // only these arguments throw ``` `failWith` is the sync counterpart of `rejectWith`, and it is **not** called `throwWith` — that name belongs to the observable helper above, which errors the stream. At runtime every spy carries every bundle; only the return type in `Spy` tells them apart, so one name for both would mean whichever is attached last silently wins. On Vitest, `mockThrow` / `mockThrowOnce` (4.1) do the spy-level half of this too. `failWith` exists because Bun and `node:test` ship neither, and because **no** runtime can make one `calledWith` chain throw while its siblings answer normally — `mockImplementation` replaces the whole dispatch, which is the opposite of configuring one set of arguments. A `failWith` supersedes a `resolveWith` / `nextWith` / per-call batch configured before it, and is superseded by one configured after, so the outcome never depends on the order the spec happens to be written in. An exact argument list is matched before the asymmetric configs, and those are tried in registration order — a narrow config written first keeps its calls. Two matchers count as the same argument when they accept the same values (same matcher class, sample and inversion), which is what makes a second `calledWith(1, expect.anything())` an override rather than a second config sitting behind the first. A hand-rolled `{ asymmetricMatch }` object is compared by identity instead: its verdict is a closure, so only re-registering that same instance overrides. **A matcher counts wherever it sits, not only at the top level.** A config argument holding a matcher — or a function — anywhere inside it is compared structurally rather than as data: `calledWith({ id: expect.any(Number) })`, `calledWith([expect.any(String)])`, a matcher inside a `Map` value or a `Set` member. The same comparison decides the rest of an argument's shape, so it is worth knowing what it treats as equal: `Map` and `Set` are compared **without regard to insertion order**, a `Date` by its time, a `RegExp` by its source and flags, an `Error` by its `name` and `message` plus its own enumerable fields, a function by identity, and symbol-keyed properties participate like string ones. Cycles are handled, so a component graph with a back-edge is a legal argument. `mustBeCalledWith` uses the same map, and its `Wanted:` line renders a matcher as `Any` rather than as the object it serialises to. Each `calledWith(...)` / `mustBeCalledWith(...)` call hands back **its own** handle, so a chain kept in a variable stays attached to the arguments it was written with: ```ts const found = users.load.calledWith(1); users.load.calledWith(2).mockReturnValue(undefined); found.mockReturnValue({ id: 1 }); // configures 1, not 2 ``` `new` on a method spy works: `new sdk.Client()` — the shape `createAutoMock<{ Client: typeof Client }>()` and `mockDeep` produce — hands back the instance, or the object a `calledWith(...).mockReturnValue(...)` configured for those arguments. `mock.settledResults` is native on Vitest and polyfilled on Bun / `node:test`, so it is identical on all three. Entries are `{ type: 'fulfilled' | 'incomplete' | 'rejected', value }`. When the argument worth asserting on is one the **code under test built** — a callback, a config object, an `AbortSignal` — describing its shape is the wrong tool. `expect.any(Function)` says a function was passed; `captureArg` hands it to you so the test can call it: ```ts import { captureArg } from 'vitest-auto-spy'; const onDone = captureArg<() => void>(); expect(notifier.subscribe).toHaveBeenCalledWith('ready', onDone); onDone.value(); // and now exercise what was passed expect(component.finished()).toBe(true); ``` `.values` holds every value the captor was **offered**, oldest first — candidates, not matches. A captor in position 0 of `toHaveBeenCalledWith(captor, 3)` is asked about the first argument of every call the runner tries, including the ones the `3` then rejects, so `.values` can be longer than the set of calls the assertion accepted. `.captured` asks whether anything was recorded without triggering the "nothing was captured" throw that reading `.value` raises; `.reset()` lets one captor serve two phases. `captureArg({ where })` narrows both halves at once — the filter decides what is recorded **and** whether that position matches at all, so a rejected candidate leaves no entry in `.values` and the whole expectation fails on it: ```ts const config = captureArg({ where: (value) => (value as RequestInit)?.method === 'POST' }); expect(fetchSpy).toHaveBeenCalledWith(url, config); // only the POST call satisfies this expect(config.value.headers).toEqual({ 'x-trace': '1' }); ``` The filter receives the raw argument as `unknown`, so narrow it yourself. **Assertions only** — a captor without `where` matches every value, so putting one in `calledWith` would configure a return for every call, which is `mockReturnValue` spelled less clearly, and `calledWith` is typed to the method's own parameters so it will not compile anyway. **The observable helpers are backed by a `ReplaySubject(1)` that belongs to the spy, and it is configuration — so it must be reset with the rest of it.** Two failures used to come out of that buffer outliving the test that filled it, and both were silent: ```ts // test 1 service.createSeamlessTransition.nextWith(uri); // buffered // test 2 — the failure path is the point of this test service.createSeamlessTransition.throwWith(error); // subscriber gets `uri` FIRST, then the error ``` The code under test therefore ran the **success** branch on stale data, and the error branch arrived one emission late. The second: `error()` and `complete()` close a Subject permanently, so a later `nextWith` on that spy pushed into a dead subject and emitted nothing at all. Both are fixed — `resetAutoSpy(spy)` now drops the subject, and a terminated one is replaced on the next configuration. That holds for a subject a spec closed **itself**, too: `spy.items$.returnSubject().complete()` marks the stream closed, so the next `nextWith` opens a new one rather than disappearing. `nextWithValues` on an observable **property** builds a new stream, which a subscriber that already holds the old one never sees — the spec's values go nowhere and the assertion below reads the initial state. That case is reported now rather than passing silently; `nextWith` pushes into the subject the current subscriber is on and is the one to reach for mid-test. What that does **not** change: `vi.clearAllMocks()` and `clearMocks: true` still cannot reach it, for the same reason they cannot reach a `calledWith` chain — that state lives in this library's closures, not on the runner's mock. So when a spy outlives a test — a TestBed built in `beforeAll`, a spy hoisted to `describe` scope — put `resetAutoSpy(spy)` in `beforeEach`. Inside one test the sequence `nextWith(a)` then `throwWith(e)` still means "emit a, then fail"; only a reset or a terminal call starts a new stream. --- ## 5. `createSpyFromClass` configuration ```ts createSpyFromClass(MyService); // every method on the prototype chain createSpyFromClass(MyService, ['reload', 'count']); // those two ADDED to the discovered ones createSpyFromClass(MyService, { methodsToSpyOn: ['reload'], // ADDS (jest-auto-spies semantics) onlyMethodsToSpyOn: ['getName'], // RESTRICTS — skips prototype discovery instanceMethodsToSpyOn: ['reload'], // ADDS; same behaviour, clearer name observablePropsToSpyOn: ['products$'], gettersToSpyOn: ['userName'], settersToSpyOn: ['userName'], autoSpyAccessors: true, // discover every accessor on the prototype chain lazySpies: true, // build each method spy on first access ('proxy' for very wide classes) returns: { getProducts: of([]) }, // what a spied METHOD answers selfReturning: ['where'], // a method that answers the double itself, for a chained call overrides: { products$: subject }, // a member that is not a method result }); ``` | Key | Semantics | | ------------------------ | --------------------------------------------------------------------------------------------------------- | | `methodsToSpyOn` | **Additive**, as in `jest-auto-spies`. Same behaviour as `instanceMethodsToSpyOn`. | | `onlyMethodsToSpyOn` | **Exhaustive whitelist.** Skips discovery; anything not listed is absent. | | `instanceMethodsToSpyOn` | **Additive.** The name to prefer in new code (see below). | | `autoSpyAccessors` | Merged with the explicit getter/setter lists. | | `lazySpies` | Behaviour-identical; only changes _when_ each spy is built. `'proxy'` also changes _what holds the name_. | | `strict` | Throw on a method nobody configured, instead of answering `undefined` (below). | | `onUnstubbedCall` | The general form of `strict`; its return value becomes the call's return value. | | `selfReturning` | The named methods answer the double itself — a default like `returns`; a name in both answers `returns`. | **`instanceMethodsToSpyOn` is not an edge case — it is a top-5 option** (103 of ~370 spec files in the reference suite). Method discovery walks the _prototype chain_; a callable assigned to an **instance field** is invisible to it: - an Angular `signal()` / `computed()` field — the dominant case in a signals codebase - an arrow-function property — `readonly reload = (): void => {}` - anything on an ngrx `signalStore()`, which puts **everything** on the instance - **members Angular's own classes moved onto the instance** — `Router.currentNavigation` in Angular 20 is `currentNavigation = this.navigationTransitions.currentNavigation.asReadonly()` ```ts createSpyFromClass(TaskStore, { instanceMethodsToSpyOn: ['count', 'reload'] }); provideAutoSpy(ProjectStore, { instanceMethodsToSpyOn: ['current', 'isEmpty'] }); provideAutoSpy(Router, { instanceMethodsToSpyOn: ['currentNavigation'] }); ``` **The failure this produces says nothing about any of it.** The member is simply not on the spy, so the next line reads `undefined` and configuring it throws: ``` TypeError: Cannot read properties of undefined (reading 'mockReturnValue') ``` There is no better message to be had at runtime, and it is worth saying why rather than leaving it looking like an oversight. Instance fields do not exist until a constructor has run, and this library never constructs the class — that is what makes a spy safe to build from a service whose constructor talks to the network. The only alternative would be to answer an unknown member with _something_, and that something would be truthy: `if (service.optionalThing)` in the code under test would then take the wrong branch, silently, which is the exact failure mode the protocol deny-list in §2 exists to remove. A loud `TypeError` on the spec's own line is the better of the two. For an ngrx `signalStore()`, prefer `createAutoMock()` over listing every member: it mocks from the type, needs no prototype, and the list cannot fall behind the store. Its **signal** members want `mockSignalProp`, not a method spy — a store's state is read during the first render, so a method spy there answers `undefined` to the template. The symptom of getting this wrong is **a spy that is never called and no warning at all**: the additive lists exist precisely to name things the prototype does not have, so a typo in one cannot be told apart from an instance field and stays silent. Only `onlyMethodsToSpyOn` warns, because only a restricting list can be silently destructive — a misspelling there leaves the real method unspied, and the code under test then calls something that is not there: `[vitest-auto-spy] createSpyFromClass(X): onlyMethodsToSpyOn names method(s) that are not on the class prototype: …`. Also true, and worth not re-deriving: - **Inherited methods are spied** — discovery walks the whole chain (`Object.prototype` excluded). - **Constructor bodies never run.** The spy is assembled from the prototype. - **Abstract classes are accepted**, type and runtime both — `ClassType` carries an abstract construct signature, and when the prototype turns out to be empty (abstract members are erased before emit) the factory hands back the `createAutoMock` proxy instead of an empty object. Do **not** pass a concrete subclass instead; this file used to say so, and it was wrong twice over. - **An overloaded method is not collapsed.** The worry that `Spy` types every generated `api-mgw` client against its last signature does not hold: a four-overload `MgwContentsService.getMoviesBySlug` types as it should, and hand-written `{ m: vi.fn() }` doubles for those services convert with no changes to the assertions. When the _first_ signature is the useful one, name it on the **declaration only** — the factory's result assigns to it, so the type argument is not written twice: ```ts let mapping: Spy; mapping = createSpyFromClass(MgwMappingService); // no second type argument here ``` **The symptom that leads here says nothing about overloads**, which is why the option is hard to find from the error. A stub of the real response shape is rejected on the spec's own line — `TS2345: Argument of type 'Page' is not assignable to parameter of type 'HttpEvent'` — on `nextWith(body)`, `resolveWith(body)`, `calledWith(…).returnValue(body)` or `mockReturnValue(of(body))` against a generated `observe` client. Neither the double nor the stub is wrong; both are being checked against the signature nobody calls. Reach for `overload`, never for `@ts-expect-error`: one migration wrote sixty of those across twenty-five files before anyone found this option, and each one stops checking the response shape that line exists to describe. **Name the method rather than the whole double.** `'first'` on the type moves _every_ overloaded member, and on a wide type that breaks the ones nobody was fixing — `Spy` for one method collected five `TS2769`s on `download`. `overload` also takes a map: ```ts let perf: Spy; ``` A name the type does not have never matches, so a rename leaves a dead entry rather than a red build. The default stays `'last'` because "the useful signature" is not decidable from the type: on a generated `observe` client it is the first, on a four-overload `api-mgw` client the last, and both live in one suite. And **overload order is not always the author's** — `declare global` in a third-party package appends to a global interface (`web-vitals` does exactly this to `Performance.getEntriesByType`), so which signature is last depends on which packages are in the program and can move on a dependency bump. **A getter that returns a `Signal` goes in `instanceMethodsToSpyOn`**, not in `gettersToSpyOn`. `get isKidMode(): Signal { return this._isKidMode.asReadonly(); }` is read as a property and called as a function, and the accessor route makes you write `accessorSpies.getters.isKidMode.mockReturnValue(signal(false))` — two levels deeper than the value in question. Naming it as an instance method puts a plain spy at that key (the spy object has no class prototype, so nothing is being shadowed), and `service.isKidMode.mockReturnValue(false)` reads like every other member. `mockSignalProp` is the other answer when the value has to change during the test. ### The composition belongs to the class — `registerAutoSpyDefaults` A class is doubled the same way in every file that doubles it, so register that once instead of repeating it: ```ts // vitest.setup.ts, once registerAutoSpyDefaults(Router, { observablePropsToSpyOn: ['events'], gettersToSpyOn: ['url'] }); // every spec, from then on provideAutoSpy(Router); provideAutoSpy(Router, { instanceMethodsToSpyOn: ['currentNavigation'] }); // ADDS to the registration ``` The call site is **merged** into the registration, not substituted for it: lists unioned (registration first, no repeats), `returns` / `overrides` merged key by key with the call site winning, scalars decided by the call site when it names the key. The bare-array form counts as `{ methodsToSpyOn: [...] }`. Registration is by class identity, so a subclass inherits nothing — walking the prototype chain would let one registration change doubles in files nobody was looking at. A second registration for the same class replaces the first, because two of them in one suite is the drift this removes rather than a merge to perform. `clearAutoSpyDefaults(Class)` drops one, `clearAutoSpyDefaults()` the lot. `createSpyFromInstance(obj)` reads the registration of the class `obj.constructor` names, merged the same way; an object literal resolves none. One exception, because an instance is real: when the call site lists `onlyMethodsToSpyOn`, the rest of the object stays real, so the registration contributes only `strict`, `onUnstubbedCall`, `onUnstubbedRead` and the `returns` / `selfReturning` entries of the listed methods — not its accessor lists, its other method lists or its `overrides`. `registerAutoSpyDefaults(Router, { gettersToSpyOn: ['url'] })` therefore leaves `router.url` live under `createSpyFromInstance(router, { onlyMethodsToSpyOn: ['navigateByUrl'] })`. A `returns` or `selfReturning` name the call site itself wrote for a method it left real is reported as a misconfiguration and skipped. A setup file that registers more than a handful of classes can say them as one table instead of one call each. Rows apply in order, and each is checked against **its own** class — a key `Router` does not carry fails on that row, naming `Router`'s members and nothing else: ```ts registerAutoSpyDefaults([ [Router, { observablePropsToSpyOn: ['events'], gettersToSpyOn: ['url'] }], [DomainEventsService, { instanceMethodsToSpyOn: ['announce'] }], [BaseLocalStorage, { instanceMethodsToSpyOn: ['getItem', 'setItem'] }], ]); ``` A later row for a class an earlier row already named replaces it, exactly as a second call would. `AutoSpyDefaultEntry` is the row type, for a row built outside the literal. **An `InjectionToken` is a key too — import `registerAutoSpyDefaults` from `vitest-auto-spy/angular` for it.** Same registry, same merge; the core export takes a class only, because the core entry may not mention Angular's types. `provideAutoSpyForToken(TOKEN)` reads the registration exactly as `provideAutoSpy(Class)` reads a class's — both of its arguments are merged over it, and a registered `returns` stays a default a later `calledWith` / `resolveWith` wins over: ```ts import { registerAutoSpyDefaults } from 'vitest-auto-spy/angular'; registerAutoSpyDefaults(LOGGER, { returns: { info: undefined, err: undefined }, selfReturning: ['channel'] }); registerAutoSpyDefaults(NAVIGATION, { overrides: { activeRow$: of({}) }, returns: { setFocus: undefined } }); providers: [provideAutoSpyForToken(LOGGER), provideAutoSpyForToken(NAVIGATION, { activeRow$: rows$ })]; ``` A token row holds `AutoSpyTokenDefaults`: what `createAutoMock` takes (`returns`, `selfReturning`, `observablePropsToSpyOn`, `strict`, `name`) plus `overrides`, the seeds `provideAutoSpyForToken` takes second. Keys are checked against the token's `T`; a table may mix class rows and token rows; `clearAutoSpyDefaults(TOKEN)` from the same entry drops one. Handing a token to the **core** `registerAutoSpyDefaults` fails with `TS2345 … 'InjectionToken' is not assignable to parameter of type 'ClassType'` — the fix is the import, not a cast. **`selfReturning` names the methods that answer the double itself.** `returns` cannot say it — the double does not exist when the literal is written — and without it a chained call dies on `undefined`. It works on every factory and in a registration; a registered chain takes a link back out through the call site's `returns`, since lists only ever union. ### `strict` — a method nobody configured throws instead of answering `undefined` ```ts const users = createSpyFromClass(UserService, { strict: true }); users.load.resolveWith([]); users.currentTenant(); // throws here, not four frames later inside the component ``` ``` [vitest-auto-spy] Nothing configured Cart.checkout, and strict mode is on. Called as: Cart.checkout(1,'now') ``` Also on `createAutoMock`, `provideAutoSpy`, and suite-wide as `setupAutoSpy({ strict: true })` — which reaches a double whichever bundle of the package built it: the default lives on `globalThis`. Before this release it lived in module scope, and a setup file's `strict: true` reached no double a spec built. Precedence, first one set wins: the double's `onUnstubbedCall` → the double's explicit **`strict: false`** (the only way to exempt one double from a suite-wide default, a global handler included) → the global `onUnstubbedCall` → the double's `strict: true` → the global `strict`. - **It is not argument-level.** A `calledWith(1, 'now')` chain says the method is stubbed, so `checkout(9, 'later')` still answers `undefined`. Use `mustBeCalledWith` for that. - **`returns:` is a default in the spy's own container**: a `calledWith` / `resolveWith` / `failWith` configured later wins for its arguments or supersedes it, every other call still gets it, and `undefined` counts as configured. `returns: { save: undefined }` is how a `void` call is expected. `selfReturning: ['channel']` is the same kind of default, and counts as configured too. - **`mockReturnValue` / `mockImplementation` replace the dispatch**, so they never reach the guard — and a `calledWith` configured after them is never consulted. After the last `mockReturnValueOnce` the queue empties back onto the library dispatch and the next call **is** reported as unstubbed — seed `mockReturnValue(...)` too when a `Once` sequence is meant to run out. - **That pair is reported, in both orders.** `mockReturnValue` after a `calledWith` erases it; `calledWith` after a `mockReturnValue` is dead on arrival. Neither fails on its own — the spec goes green on a branch nobody configured — so the library says so as a misconfiguration (warn, or throw under the `strict` preset). The whole family replaces: `mockImplementation`, `mockReturnValue`, `mockReturnThis`, `mockThrow`, `mockResolvedValue`, `mockRejectedValue`. When both a fallback and a per-argument value are wanted, the fallback goes in the spy's container — `returns:` where the double is built, or `resolveWith` / `nextWith` / `failWith` — which a `calledWith` still wins over. The report is this library's own spy engine's, so Vitest and Rstest have it; Bun, `node:test` and `setSpyEngine('runner')` do not. The `Once` family is never reported. - **A throw something swallowed still fails the test.** Under `setupAutoSpy({ strict: true })` every strict throw is recorded, and one that a `try`/`catch` in the code under test or an RxJS error with no handler (its rethrow waits on a fake clock) kept from the test fails it after the test (`swallowedStrictCalls`, `'throw'` by default with `strict: true`). Provoking one on purpose: `expect(() => cart.total()).toThrow(…)` then `expect(takeStrictViolations()).toHaveLength(1)`. - **It does not reach** accessor spies, observable-property spies, `mockDeep` nodes, `console-spy`, `mockResourceProp`'s `reload` or a standalone `createFunctionSpy`. A strict double still answers `undefined` for an unconfigured getter or `items$`. `fillMissing` members **are** covered. - **The getter and the stream are reported after the test instead** — a read cannot throw, because a failure diff that prints the double reads it. `setupAutoSpy({ unconfiguredReads: 'warn' | 'throw' })` (default `'off'`, not in the preset) reports a strict double's getter read that reached no configuration and a subscription to a stream nothing fed **by the end of the test** — subscribe in `beforeEach`, `nextWith` in the test is fine. Counted from setup's `beforeEach` to its `afterEach`, so the spec's own hooks count. Configured means `accessorSpies.getters.x.mockReturnValue(…)` / `mockImplementation`, `overrides: { x }` (call site or registration — a registered _list_ alone is not), `mockReadonlyProp`; for a stream any of `nextWith` / `throwWith` / `complete` / `returnSubject`. `undefined` meant: `mockReturnValue(undefined)`. `onUnstubbedRead({ className, member, kind, count })` — suite-wide or per double, same precedence as `onUnstubbedCall` — takes the findings instead of the report, from every double not `strict: false`: survey with it first. - **Angular lifecycle hooks are exempt.** `ngOnDestroy`, `ngOnInit`, `ngOnChanges`, `ngDoCheck` and the `ngAfter…` hooks answer `undefined` on a strict double: Angular calls `ngOnDestroy` itself on every provided value at teardown (a `createAutoMock` / `provideAutoSpyForToken` double always has one), and a throw there broke the teardown for every test after it. The calls are still recorded. - A class instance or DOM node in the `Called as:` line prints as `[ClassName]`, data up to 200 characters per argument; `provideAutoSpyForToken` names the token (`createAutoMock` takes `name`). - Use `onUnstubbedCall` to survey a suite before turning the throw on — it is handed `{ className, method, args }` and whatever it returns is what the call answers, so a handler that pushes to an array records the gap without failing anything. ### Getters and setters live in `accessorSpies` ```ts const settings = createSpyFromClass(SettingsService, { gettersToSpyOn: ['theme'], settersToSpyOn: ['theme'] }); settings.accessorSpies.getters.theme.mockReturnValue('dark'); expect(settings.theme).toBe('dark'); // the property itself stays typed as `string` settings.theme = 'light'; expect(settings.accessorSpies.setters.theme).toHaveBeenCalledWith('light'); ``` **Naming one half gets you the pair, when the class declares a pair.** `gettersToSpyOn: ['theme']` on a class with both a getter and a setter installs both spies — mirroring reads the prototype descriptor, so it only ever adds what the class already has, and a read-only member stays read-only. Before 3.5.0 the assignment landed on the no-op setter the scaffolding installs: the write vanished, `accessorSpies.setters.theme` was `undefined`, and the failure read `Cannot read properties of undefined` three steps from the configuration behind it. The bag is typed over every key of `T` unless the lists are repeated in the options type argument — `createSpyFromClass(Settings, { gettersToSpyOn: ['theme'] })` keys both halves by exactly the configured names, so `accessorSpies.setters.other` is a compile error instead of an `undefined` at run time. Use it when a spec reaches into the bag by name; a non-literal `string[]` falls back to the every-key bag. Only spy a getter when the spec asserts that it was **read**. To make one _answer_ something, on a spy that already exists, the pair above is one line — and it needs no `gettersToSpyOn` at the factory, which is the part that is otherwise found by trial: ```ts mockReadonlyProp(settings, 'theme', 'dark'); // no gettersToSpyOn, no accessorSpies ``` For a signal-valued property that is not merely convenience: a spied getter answers `undefined` until it is configured, while `mockReadonlyProp(component, 'items', signal([]))` keeps every `computed()` and `effect()` downstream of it reactive (§9). --- ## 6. `Spy` is not assignable to `T` — this is intentional `Spy` is a **mapped type**, so it drops `#private` and `private` members. ```ts let users: Spy = createSpyFromClass(UserService); // ✅ let users: UserService = createSpyFromClass(UserService); // ❌ private members missing ``` Do **not** patch this with `as any`, `as unknown as T`, or `@ts-expect-error`. Use the named views: ```ts import { asInstance, asSpy } from 'vitest-auto-spy'; asInstance(spy); // Spy → T, for an API typed against the class asSpy(TestBed.inject(CartService)); // T → Spy, for the helpers ``` Both are the same object at runtime. `injectSpy(X)` already returns `Spy`. The compiler reports this in four different ways, none of which contains both the words "spy" and "instance", which is why the fix is hard to find from the message alone: | Message | Direction | Fix | | ------------------------------------------------------------------------------------ | --------- | --------------------------------- | | `TS2352: … 'accessorSpies' is missing in type 'Router'` | `T` → spy | `asSpy(TestBed.inject(Router))` | | `TS2739` / `TS2740: Type 'Spy' is missing the following properties from type 'X'` | spy → `T` | `asInstance(spy)` | | `TS2345: Argument of type 'Spy' is not assignable to parameter of type 'X'` | spy → `T` | `asInstance(spy)` | | `is missing the following properties: _modalOpened, body, …` (private names) | — | declare `Spy`, not `Mocked` | That last row is its own trap: Vitest's `Mocked` keeps `T`'s **private** members, so the error lists private field names and reads as "the double is incomplete". It is not — the declaration is wrong. `Spy` covers the public surface on purpose. **A generic class needs its type argument spelled out.** `TestBed.inject` infers from the constructor and produces `Service`, and the `any` surfaces much later as a mismatch between `AddPromiseSpyMethods` and `WithMockReturnValue<…>` — eight levels deep, and nothing about it says "type parameter": ```ts const config = asSpy(TestBed.inject(FeatureFlagService)); // ✅ const config = injectSpy(FeatureFlagService); // ✅ ``` `injectSpy(X)` without the argument keeps a declared default when the constructor does not take the type parameter. When it does — `constructor(public data: T, …)`, the shape of most modal refs — 5.19.0 inferred `X`, and with the typed `accessorSpies` bag `Spy>` no longer assigns to `Spy>`. Such a class is now read at its **constraint**: `ModalRef` gives `Spy>`, `ConfigService` gives `Spy>`. A constructor cannot hand TypeScript the default here, so spell the argument out whenever the default or a particular instantiation is what the spec means: `injectSpy(ConfigService)`, `injectSpy>(ModalRef)`. It applies to `createSpyFromClass` with a configuration too, in one combination: an accessor list (or `overrides`) **and** `returns` on a generic class. TypeScript checks a generic class argument after the configuration, reads `T` back from `gettersToSpyOn: ['remoteConfig']` as `{ remoteConfig: any }`, and fails with `'isKeyEnabled' does not exist in type 'MethodReturns<{ remoteConfig: any; }>'`. Spell it out — `createSpyFromClass(…)`. `provideAutoSpy`, `overrideAutoSpy`, `overrideComponentProvider` and the class overload of `registerAutoSpyDefaults` (`/angular`) take `T` from the class alone, so there the inferred form compiles; the core `registerAutoSpyDefaults` needs the argument spelled out like `createSpyFromClass`. A token key needs nothing: `T` comes from the `InjectionToken` itself. **A declared default now reaches the double, and used not to.** `class RemoteConfigService` handed to `createSpyFromClass` / `injectSpy` inferred `T` as `unknown`, so every member typed against it read as `unknown` on a class that had said exactly what it should be. Two shapes caused it, both fixed: the `& { [key: string]: any }` intersection `ClassType` used to carry (an index signature makes inference drop the default) and the union in `injectSpy`'s token parameter (a union does too — a class now matches a bare construct-signature overload first). Spelling the argument out still works and is still the answer when the class has **no** default. **A generic _method_ is a different thing, and it does collapse.** `show(component: Type, data: U)` on a modal or factory service reaches `Spy` through `Parameters` / `ReturnType`, which instantiate the method's own type parameters — so the double types as `show(component: Type, data: unknown)`. No mapped type in TypeScript can preserve a generic signature, so this is a limit rather than a defect, and it is usually harmless: `unknown` accepts every argument and every seeded return, so `spy.show.calledWith(MyModal, data).mockReturnValue(ref)` compiles. It bites only where the instantiated type appears in a **contravariant** position; there, name the shape on a declaration of your own and assign the factory's result to it. --- ## 7. Resetting ```ts import { clearAutoSpy, resetAutoSpy } from 'vitest-auto-spy'; clearAutoSpy(service); // recorded calls only — configured returns survive resetAutoSpy(service); // calls AND configuration (calledWith / resolveWith / mockReturnValue) ``` Both cover method spies **and** accessor spies, on `createSpyFromClass` spies and `createAutoMock` proxies alike. Reach for these instead of looping over methods calling `mockClear` by hand. **`resetAutoSpy` is `vi.resetAllMocks()` for one double**, and two things it used to leave behind now go with the rest: a pending `mockReturnValueOnce` / `mockResolvedValueOnce` queue (it used to answer the first call _after_ the reset, in a later test) and an accessor spy's configuration (a `accessorSpies.getters.x.mockReturnValue(…)` used to survive and hand the next test the previous test's value). A spec that relied on a queued `Once` value outliving the reset reads `undefined` now. The double stays usable: the library's own dispatch is put back afterwards, so a fresh `calledWith` configures it as normal. Every double also carries `[Symbol.dispose]()` — it runs `resetAutoSpy(this)` — so an `afterEach` that exists only to reset one spy can be deleted: ```ts it('loads', () => { using cart = createSpyFromClass(Cart); // reset when the block ends cart.total.calledWith().mockReturnValue(42); expect(cart.total()).toBe(42); }); ``` `createAutoMock` proxies and **every `mockDeep` node** carry it (so `using` on a sub-tree resets that sub-tree). The key is non-enumerable, so a spread does not copy it, and there is no `[Symbol.asyncDispose]`. A standalone `createFunctionSpy` is **not** covered: Vitest's own `[Symbol.dispose]` on a host mock restores the original implementation instead — call `resetAutoSpy(spy)` there. If the project does not transpile `using`, call `spy[Symbol.dispose]()`. `src/lib/dispose-symbol.ts` installs `Symbol.dispose` when the realm has none, and `DISPOSE` — not `Symbol.dispose` — is what library code compares against. Node 22 has no explicit resource management in V8: it patches the symbol in itself, as `Symbol.for('nodejs.dispose')`, onto the main realm only, so under `jsdom` / `happy-dom` (a bare `vm` context) it is absent, the downlevelled `using` throws out of `tslib.__addDisposableResource`, and `spy[Symbol.dispose]` degrades into a property named `"undefined"`. The shim is the same registry symbol, so it is identical to Node's across realms. --- ## 8. Observable assertions (core entry — no rxjs needed) `expect()` inside a `subscribe()` callback is the classic green-but-empty test: if the stream never emits, the callback never runs and nothing is asserted. Invert it — **the assertion is the `await`**: ```ts import { expectCompletion, expectEmission, expectEmissions, expectError, expectNoEmission } from 'vitest-auto-spy'; await expect(expectEmission(component.visible$)).resolves.toBe(true); // the first VALUE, not a list await expect(expectEmission(tasks$)).resolves.toEqual({ id: 1 }); // the task itself, not `[task]` await expect(expectEmissions(source$, 3)).resolves.toEqual([1, 2, 3]); // the list is this one await expectNoEmission(source$, { timeout: 50 }); await expectCompletion(service.purgeCache()); // "it finished" — the value is not the point ``` Options: `{ timeout, label }`. `timeout` defaults to `1000` ms (`0` for `expectNoEmission`, whose wait is a quiet window rather than a watchdog). `0` and `Infinity` both mean **no watchdog** — the wait then runs to the runner's own test timeout, which is the trade. The source is duck-typed, so rxjs `Observable`s, `Subject`s, Angular `toObservable()` results, Angular `output()` (`OutputEmitterRef`, whose `subscribe` takes a bare callback) and hand-rolled subscribables all work — and every helper infers the emitted type, so `expectEmission(of(1))` is a `Promise`. `expectCompletion` is the one to reach for on a stream whose value is not the point — a save, a purge, an `Observable`, a `Subject` a teardown closes. `firstValueFrom` rejects such a stream with rxjs's `EmptyError`, and the workaround people arrive at, `lastValueFrom(x, { defaultValue: undefined })`, reads as though the default were the interesting part. Emissions do not fail it: it asserts termination, nothing about what came before. **To assert that production code pushed into a stream, do not use `observablePropsToSpyOn`.** That option points the other way: it gives the spec `nextWith` so it can _feed_ the double. When the question is whether the code under test called `next` on a property, the double needs a real `Subject` and a spy on its method: ```ts const forceRequery$ = new Subject(); mockValueProp(state, 'forceRequeryAndStartPlaybackAt$', forceRequery$); const next = vi.spyOn(forceRequery$, 'next'); service.seek(1000); expect(next).toHaveBeenCalledWith(1000); ``` `Spy` types an Observable property as `AddObservableSpyMethods & T[K]`, so `next` is there on the type either way — which is exactly why this is worth saying: the code compiles against the spy surface and asserts nothing. **When the error _is_ the assertion, use `expectError`.** The other helpers wrap a stream failure in a new `Error` whose message names the stream — right for reporting an unexpected failure, useless when the failure is the subject. `expectError` resolves _with_ the error, exactly as it was thrown: ```ts await expect(expectError(service.load())).resolves.toBe(originalError); expect(await expectError(process$)).toBeInstanceOf(UdmsStatusError); expect((await expectError(account$)) as Error).toHaveProperty('message', 'websso fail'); ``` It waits for the error however late it arrives, and fails — naming the stream — if the stream completes or stays quiet instead. The wrapped failures of the other helpers now also carry the original on `cause`, so `rejects.toMatchObject({ cause: original })` works; prefer `expectError`, which needs no unwrapping. `firstValueFrom(source$).rejects` remains fine too. **Which emission counts** — `skip` and `until`, for the stream whose first value is always stale: ```ts await expect(expectEmission(isXl$, { skip: 1 })).resolves.toBe(true); // a shareReplay / BehaviorSubject await expect(expectEmission(currentParams$, { until: (p) => p.channelId === expected })).resolves.toEqual(…); ``` Both say in the assertion what `source$.pipe(skip(1))` / `pipe(filter(…))` say in the source, and they keep the diagnosis: emissions that do not match are still counted, so a failure reads `4 emission(s) received` rather than `0` and tells "the wrong thing fired" apart from "nothing fired". **`advance` closes the window between subscribing and awaiting.** A stream driven by a `debounceTime`, a retry or a poll needs the clock moved _after_ something is listening, and `await` gives control away before the next statement runs: ```ts await expect(expectEmission(purchased$, { advance: () => vi.runAllTimers() })).resolves.toBe(false); ``` That replaces the fragile shape people arrive at — hold the promise, advance, then await — which breaks silently the moment somebody adds an `await` one line above it. It is a callback rather than an `advanceTimers: true` flag because these helpers are in the core entry, which contains no test runner: only the spec knows whether it is on `vi`, `bun:test` or `node:test`. A throw out of `advance` — or out of an `until` predicate — is reported as itself and tears the subscription down, rather than being lost while the wait runs on to the timeout. **These helpers subscribe as a subscriber, so a synchronous source stops at the value that settles the wait.** `expectEmission(from([1, 2, 3]).pipe(tap(spy)))` calls `tap` once, not three times, so `expect(spy).toHaveBeenCalledTimes(1)` is honest and a `finalize` runs at the stop; before, the producer ran to completion before anything could unsubscribe, and an endless synchronous source (`of(1).pipe(repeat())`) hung the worker instead of resolving. `expectEmissions(source$, 3)` stops at the third. A source that cannot be subscribed to at all is reported by name now, with a separate hint when what was passed is a promise. `expectEmissions(source$, 0)` throws at the call — a count below 1 is not something a stream can satisfy, and the message names `expectNoEmission` instead. A suite that wrote `expectEmissions(s, expected.length)` with an empty expectation is the one this changes. **The watchdog runs on real time, on purpose — even under fake timers, and even under zone.js.** A virtual one would race the timers the spec advances: `expectEmission(source$, { timeout: 200 })` followed by `vi.advanceTimersByTime(5_000)` would fire at 200 virtual ms and reject the stream the spec was about to advance into. Inside `fakeAsync` that used to happen anyway, because zone.js patches the global `setTimeout` and the watchdog was scheduled onto the virtual queue: a `tick(1_500)` towards a `debounceTime(2_000)` rejected the wait it was advancing. The timer is taken from `__zone_symbol__setTimeout` now, so it is outside the zone and `tick()` cannot reach it. The cost is that in a suite with global fake timers a _failing_ assertion spends a real second. Do **not** answer that with `{ timeout: 0 }` at every call site — that disables the watchdog, and the next silent stream hangs to the runner's own timeout with nothing useful in the message. Lower the default once instead: ```ts // vitest.setup.ts import { setEmissionTimeout } from 'vitest-auto-spy'; import { setupAutoSpy } from 'vitest-auto-spy/setup'; setupAutoSpy({ globalFakeTimers: true }); setEmissionTimeout(100); // the clock is frozen; a real second buys nothing ``` `setEmissionTimeout` takes `0` (no watchdog) and `Infinity` (the same), and **throws** on `NaN` and on a negative number rather than installing a default that fails every wait. The commonest way to reach it is arithmetic: `setEmissionTimeout(Number(process.env.EMISSION_TIMEOUT))` with the variable unset. **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 does not replay: ```ts const breadcrumbs = expectEmission(service.buildDynamicBreadcrumbs({ root })); // subscribed already router.events.nextWith(navigationEnd); // …so this emission is not missed await expect(breadcrumbs).resolves.toEqual([…]); ``` `firstValueFrom` cannot do this half: it also subscribes eagerly, but there is nowhere to put the line that triggers the source, because the `await` is the same statement as the subscription — so the test deadlocks against a source that only emits once something pokes it. Hold the promise first, poke, then await. ### `createLog()` — the order between the spies ```ts const log = createLog<'drop-cache' | 'flush-telemetry' | 'stop-engine'>(); engine.onShutdown(log.fn('drop-cache')); engine.onShutdown(log.fn('stop-engine')); engine.onShutdown(log.fn('flush-telemetry')); engine.shutdown(); expect(log.result()).toBe('drop-cache; flush-telemetry; stop-engine'); // fails with the real order ``` Emission helpers answer a sequence _within one source_. The order of calls **across** collaborators is the gap `toHaveBeenCalled` papers over — three green checks that would accept the sequence backwards — and `toHaveBeenCalledBefore` covers pairwise. One journal the code under test writes into (`add`, `fn(value)` for a labelled callback, `clear`, `items`, `result()`) makes the sequence a single comparable value; `T` is a string union so a step nobody declared is a compile error. In Angular, provide it and let the component report its own lifecycle: `providers: [{ provide: PANEL_LOG, useValue: log }]`. Ported from Angular's own `Log`, which the framework keeps three copies of. --- ## 9. Patching properties (and putting them back) ```ts import { mockAccessorsProp, mockReadonlyProp, mockReadonlyPropGetter, mockValueProp, restoreMockedProps } from 'vitest-auto-spy'; mockReadonlyProp(service, 'isReady', true); // static value, signals included mockReadonlyPropGetter(service, 'label', () => 'A'); // dynamic getter mockValueProp(service, 'retries', 3); // plain writable value mockAccessorsProp(service, 'theme'); // spied get + set restoreMockedProps(); // put every patch back; each helper also returns its own undo ``` `vi.restoreAllMocks()` does **not** undo these — it knows about spies, not about redefined properties. Never use bare `Object.defineProperty` in a spec: nothing restores the original descriptor, and under `isolate: false` the patch leaks into the next file. **They work on `createAutoMock` and `mockDeep` doubles too** — which they did not until 3.5.0. Both are Proxies, all four helpers are built on `Object.defineProperty`, and neither Proxy trapped it: the patch landed on the Proxy's own target, the `get` trap never looked there, nothing threw, and the test carried on reading the old value. If you have seen a spec build a double by hand — real getters plus a `createFunctionSpy` per method — this is usually why. **The second overload is a normal tool, not a last resort.** Each helper has a checked overload (`K extends keyof T`) and a `(object, property: PropertyKey, value: unknown)` one behind it, and the JSDoc calls the latter an escape hatch for `#private` fields. In practice it carries about half of the real calls, all of them legitimate: ```ts mockValueProp(router, 'routerState', { snapshot: { url: '/home' } }); // a partial fixture of a fat type mockValueProp(window, 'AudioContext', undefined); // "this platform does not ship the API" mockValueProp(transitionEvent, 'propertyName', 'opacity'); // a field a synthetic DOM event lacks mockValueProp(spy, 'products$', new Subject()); // a member the double does not have at all ``` The last one is worth knowing on its own: patching a key the object never had **works and is undone correctly** — the journal records the _absence_ of a descriptor and puts it back by deleting the property. That is how you add an Observable member that `provideAutoSpy` did not create because `observablePropsToSpyOn` was not passed. What the second overload costs is the property-name check, so a typo in the name compiles. Nothing checks the _value_ on either overload; that is deliberate, and the partial fixture above is why. **A read the constructor does cannot be seeded by any of these.** They patch an object that already exists, so the earliest they can run is after the double is built — and a component that reads `service.paymentParams.offer` in a field initializer or in its constructor has already read it by the time `TestBed.createComponent` returns: ```ts fixture = TestBed.createComponent(PaymentComponent); // ← TypeError thrown here, inside the component mockReadonlyProp(paymentService, 'paymentParams', params); // never reached ``` Nothing warns, because nothing of this library runs: the throw is a plain `TypeError` from the component's own line, and the stack names the component rather than the seeding that is missing. The only place early enough is the registration: ```ts providers: [provideAutoSpy(PaymentService, { overrides: { paymentParams: params } })]; providers: [provideAutoSpyForToken(STATE_TOKEN, { snapshot })]; // a token's second argument does the same ``` Three migration shards found this independently, each of them after the failure had pointed at the service. A `mock*Prop` after the render is right for everything a template or a method reads later — which is most of them — and wrong only for a constructor-time read. ### Properties of DOM objects — the same helpers, and the reason to look for them `document.fullscreenElement`, `document.visibilityState`, `document.cookie`, `navigator.userAgent`, `element.scrollHeight`: half the patching a browser suite does is on objects, not on `globalThis`, so the "globals go through `stubGlobal`" rule does not cover it. `mockValueProp` does — it is the port of `jest.replaceProperty`, and a project that never used that one walks straight past it. ```ts mockValueProp(document, 'fullscreenElement', videoElement); mockValueProp(navigator, 'userAgent', 'Tizen 6.0'); mockValueProp(element, 'scrollHeight', 400); ``` The hand-written form fails in three ways that all surface in **someone else's file**: - `Object.defineProperty(obj, key, { value })` defaults `configurable` to `false`, so the property can never be changed or removed again — for the rest of the worker; - the undo is written as the last line of the test, so a failing assertion skips it; - the real property is an **accessor on the prototype** (`document.fullscreenElement` is one), the patch writes a `value` over it, and "put the old descriptor back" is not the correct undo — deleting the own property is. `mockValueProp` records what was actually there and does the right one. --- ## 10. Setup file ```ts // vitest.setup.ts import 'vitest-auto-spy/rxjs'; // once — enables observable spies everywhere import { setupAutoSpy } from 'vitest-auto-spy/setup'; setupAutoSpy(); // { duplicateCopies: 'throw', restoreProps: true, restoreMocks: false } ``` `setupAutoSpy()` does three things: `restoreMockedProps()` in a global `afterEach`, a duplicate-install check that fails the run, and (opt-in) `vi.restoreAllMocks()`. Turn on `restoreMocks: true` when the suite runs with `isolate: false`. **The restore also runs from an `onTestFinished` net**, because the `afterEach` is not guaranteed to. Vitest calls `afterEach` hooks in _reverse_ registration order, so the setup file's is the last one, and a hook the spec file registered takes the chain down with it when it throws — the patches then travel into the next test and the failure surfaces somewhere that never touched them. One spec kept `afterEach(() => vi.restoreAllMocks())`; migrating it to `gettersToSpyOn` made the restored getter return `undefined`, `ngOnDestroy` called it as a signal, the `TypeError` aborted the hook, and a template error about a null profile appeared in a different `describe`. The net puts the properties back and warns with the count and the cause. `countMockedProps()` is exported if you would rather assert it: `afterEach(() => expect(countMockedProps()).toBe(0))`. **A `mock*Prop` patch written in a `describe` body or a `beforeAll` is reported**, because the sweep undoes it after the test it was applied during and nothing puts it back: the first test passes and every one after it reads the real member. `propsOutsideHooks` grades that — `'warn'` (default), `'throw'`, `'off'` — and `reportPropsOutsideHooks(reaction)` sets the same dial for a suite that wires its own hooks. Move the call into `beforeEach`. **The one that only bites at scale:** with `isolate: false`, a `setTimeout` or `requestAnimationFrame` a component schedules and never clears keeps running after its file is done, and fires while the **next** file is mid-test. It is reported against that innocent file, as `Schedulers cannot synchronously execute watches while scheduling`, `signal read during notification phase`, or an unhandled rejection naming a component the failing file never imported. If you see any of those, suspect the previous file, not the one that failed: ```ts setupAutoSpy({ strayTimers: true }); // wrap the schedulers, sweep the survivors in afterAll ``` The pieces are exported too — `trackStrayTimers()` (idempotent, returns the undo), `cancelStrayTimers()` (returns how many it cancelled), `countStrayTimers()` and `describeStrayTimers()` (each pending timer's kind, the spec file that scheduled it and up to five frames), all from `vitest-auto-spy/setup`. Use `expect(countStrayTimers()).toBe(0)` in an `afterEach` to make a leak fail rather than be tidied away, or take the per-file report from the sweep itself — `timers` carries the same origins, so the failure diff names the file and the scheduling call: ```ts setupAutoSpy({ strayTimers: true, onStrayTimers: ({ timers }) => expect(timers).toEqual([]) }); ``` A stray whose `file` is not the file that failed was scheduled after the previous file's sweep — the previous file is the one to fix. **`countStrayTimers()` cannot see a timer scheduled under fake timers, and that does not compose away.** `vi.useFakeTimers()` assigns its own `setTimeout` over the tracking wrapper, so everything the fake clock hands out bypasses the count entirely — which makes `expect(countStrayTimers()).toBe(0)` vacuous in any file running on a frozen clock, `setupAutoSpy({ strayTimers: true, globalFakeTimers: true })` included. Read `vi.getTimerCount()` for the fake clock's own backlog; the two answer different questions and neither covers the other. A handle cleared by the number it coerces to (`clearTimeout(+handle)`) or through its own `close()` is forgotten properly now, so those stopped being counted as strays. **With Vitest 4.1's `--detect-async-leaks`, run one or the other — not both silently.** The two arrive at the same timer from opposite ends and the quiet one wins: the sweep cancels in `afterAll`, Vitest collects its leaks afterwards, and a cancelled timeout is no longer referenced, so the run reports **no leaks** for a file that leaks. Cancelling is still the right default — a callback firing during a later file is the more expensive failure — so when both are on and no `onStrayTimers` is given, the sweep prints one line to stderr saying how many it took away and where the first three were scheduled; `onStrayTimers` gets all of them. Vitest's own report, with `strayTimers` off, points its code frame at the `setTimeout` in the spec, because the library's own scheduler wrappers go through `vi.defineHelper` and are dropped from the stack. **The one that keeps a suite green while it is wrong:** zone.js replaces the global `Promise`, and a rejection nobody handled is drained into `console.error` and no further — it never reaches `process.on('unhandledRejection')`, the channel Vitest watches, so the runner is never told and the file still exits 0. `compileComponents().then(() => expect(…))`, an `async` helper called without `await`, a `TypeError` thrown inside `import('…').then(…)` in production code: each of those is a passing test with a line of stderr behind it. One migrated suite — 1688 spec files, 11 587 tests, green — was hiding six of them, two being assertions that were simply false. ```ts setupAutoSpy({ strayRejections: true }); // fail the test the swallowed rejection surfaced in ``` Off by default, and it needs zone.js already loaded — this package never imports it, so the setup file does (`import 'zone.js';`) or the Angular builder does. Without it the call **throws** rather than quietly watching nothing. Native, non-zone rejections already fail a Vitest run, and nothing here touches them. The pieces are exported too — `trackStrayRejections()` (idempotent, returns the undo), `flushStrayRejections()` (takes what was captured and starts again from empty) and `countStrayRejections()`. The count is complete; the **reasons** retained are capped at 100, so a file rejecting in a loop cannot hold its whole run's worth of stacks. A promise rejected with `undefined` is reported as that rather than as `[object Object]`. The `no-floating-assertion` lint rule catches the commonest shape before it ever runs (§16). **`onUnhandledError` is not this.** Vitest 4.0 added a config callback for errors the _runner_ hears about, and under zone.js the runner never hears about these at all — zone.js drains the rejection into `console.error` before `process.on('unhandledRejection')` would fire, so there is nothing for that callback to filter. Use `onUnhandledError` to triage the native failures Vitest already reports; use `strayRejections` to find the ones it never sees. A rejection the runner has **already** blamed the finished test for is not reported again. An `async` test that fails an assertion leaves its own `AssertionError` in both places, so a red run used to print two messages per failure and the second one sent the reader hunting for a defect that was not there. What is left is what the check is for: the rejections that fail no test at all. **The one that gets slower the longer the run goes on:** every `vi.fn()` and `vi.spyOn()` is added to one `Set` inside `@vitest/spy`, because that is what `vi.clearAllMocks()` walks, and nothing takes anything out of it again. With `isolate: false` the set is created once per worker and only grows: `clearMocks: true` then walks every mock of every file already run **before every single test**, and the worker holds all of them at once — their recorded arguments included, and through those whole component trees. ```ts setupAutoSpy({ pruneMockRegistry: true }); // keep only the mocks that outlive a file ``` The part to understand before turning it on is what must **not** be pruned. A pruned mock is one `clearMocks` can no longer see, so its calls accumulate silently — harmless for a mock that dies with its file, a bug for the module-level `vi.fn()` in a shared `*.mock.ts` that six spec files import. The split is therefore drawn where it is observable: what is already in the registry when a file's hooks start was created while the module graph was evaluated and is kept; everything added after that belongs to the file and goes when it ends. One case lands on the wrong side — a module first loaded by a dynamic `import()` inside a test — and says so explicitly: ```ts export const navigation = { setFocus: keepMockRegistered(vi.fn()) }; ``` The mocks it keeps, it also guards. Staying registered means `vi.resetAllMocks()` reaches them too — it walks the same set and calls `mockReset()`, which puts an implementation back only when it was passed to `vi.fn(implementation)`; behaviour chained on with `.mockReturnValue(…)` or `.mockReturnThis()` is simply lost. Under `isolate: false` that surfaces in a _different_ file later in the same worker, inside application code, as `Cannot read properties of undefined` against a shared double that spec never touched — and `vi.restoreAllMocks()` does not cause it (Vitest 4 walks `MOCK_RESTORE` there, which only `vi.spyOn` writes to), so probing with that one comes back green and sends the search the wrong way. The implementation a long-lived mock carried when it was classified is therefore remembered and put back, in `beforeEach`, but only when it has gone missing. `trackMockRegistry()` installs the hooks on its own, `pruneMockRegistry()` is the one-shot sweep (it returns how many went), `restoreLongLivedImplementations()` is that repair (it returns how many it put back) and `getMockRegistrySize()` reports what is left. One entry is never pruned, and it is not one of yours: the Vitest adapter registers a single `vi.fn()` whose `mockClear` sweeps this library's own spies. Dropping it would turn `vi.clearAllMocks()` into a silent no-op for every double in the run, so it carries a mark the pruner skips. Why the library needs a mock of its own for that is the next section. ### What a method spy is, and the one thing that differs from `vi.fn()` A method spy is **not** a `vi.fn()`. It is this library's own mock function: one shared prototype carrying the whole `Mock` surface, call state allocated on the first call rather than at creation, and no entry in any global registry. `vi.fn()` assigns some twenty-five closures as own properties of every mock it makes and allocates six arrays up front — per method, on every double a spec builds — and that cost is most of what a wide service used to pay for methods no test touches. Everything a spec can observe is the same, and the suite pins it by putting the two side by side: - `vi.isMockFunction(spy.load)`, `expect(spy.load).toHaveBeenCalledWith(…)`, `toHaveReturned`, `toHaveResolved`, `toHaveBeenNthCalledWith` — every matcher reads `_isMockFunction`, `mock.*` and `getMockName()`, all of which the spy implements with the runner's semantics. - `spy.load.mock.calls` / `.results` / `.settledResults` / `.instances` / `.contexts` / `.invocationCallOrder` / `.lastCall`, `mockReturnValue`, `mockResolvedValue`, `mockImplementation(Once)`, `withImplementation`, `mockClear` / `mockReset` / `mockRestore`, `mockName`, `using`. - `vi.clearAllMocks()`, `vi.resetAllMocks()`, and the `clearMocks` / `mockReset` config keys, which Vitest applies through those two functions. **The one difference.** `mock.invocationCallOrder` counts on this library's own scale, so `expect(a).toHaveBeenCalledBefore(b)` is exact between two auto-spies and **wrong** between an auto-spy and a hand-written `vi.fn()` — not an error, an answer, computed from two counters that never met. `@vitest/spy` keeps its own in a module-private variable it neither exports nor lets anything advance, so the scales cannot be reconciled after the fact; they drift apart by however many calls of each kind the run has already made. Measured in a converted suite: a double reporting `[164, 165, 167, 168, 169]` beside a `vi.fn()` reporting `[28]` for its single call in the same test, under an assertion that had been passing — because `jest-auto-spies` built both halves with `jest.fn()`, which did share one counter. Three earlier calls of one family are enough to invert the verdict. Nothing else in the library or in Vitest reads that field. If a suite needs the comparison, compare two doubles of the same family, or switch the whole run back to the runner's factory: ```ts // vitest.setup.ts import { setSpyEngine } from 'vitest-auto-spy/setup'; setSpyEngine('runner'); // every double built afterwards is `vi.fn()` per method, as before 4.1 ``` **On Vitest 5 the registry story changes, and this library follows it.** Vitest 5 keeps registered mocks behind `WeakRef`s and its `clearAllMocks()` visits only the ones _called_ since the last sweep — so a spy that is not a `vi.fn()` has to make itself reachable to that sweep deliberately. It does, which is why `vi.clearAllMocks()`, `vi.resetAllMocks()` and the `clearMocks: true` default (new in Vitest 5) clear these doubles exactly as they clear the runner's own. Nothing in a spec changes, and the peer range still starts at 2.1 — one install spans Vitest 2.1 through 5.x. What each config flag does to an auto-spy, measured on both spy engines: `clearMocks` empties the calls and keeps the configuration; `mockReset` empties the calls and drops `mockReturnValue` / `mockImplementation` but **keeps `calledWith` rules**; `restoreMocks` never touches an auto-spy (it only undoes `vi.spyOn`). Do not claim the flags skip auto-spies — a sweep sentinel in the Vitest adapter routes the first two. `resetAutoSpy(spy)` is the call that drops everything, `calledWith` included. `mockReset()` on a `vi.spyOn(…)` runs the **real** method again (Vitest ≥ 3). What Vitest 5 does break is the runner's own doing, not this library's: with `clearMocks` on by default, a test asserting on a call that an **earlier** test or a `beforeAll` recorded now reads zero. Count it in a plain variable rather than in the spy, or set `clearMocks: false`. **The one exception to "nothing in a spec changes".** `setupAutoSpy({ pruneMockRegistry: true })` discovers long-lived mocks by walking the runner's registry, which Vitest 5 no longer exposes — the automatic half is a no-op there. `keepMockRegistered(mock)` works on every version and is the fix; recommend it whenever a suite on Vitest 5 loses a shared mock's implementation to `vi.resetAllMocks()`. `getSpyEngine()` reports the current one, `'auto-spy'` is the default, and doubles already built keep the engine they were built with. The switch is Vitest-only: on Bun and `node:test` the runner's own matchers recognise only the runner's own mocks, so those adapters keep using them. Two more switches, both about the environment rather than the spies: ```ts setupAutoSpy({ blockNetwork: true }); // fetch rejects, XHR fails, sendBeacon answers false ``` Both DOMs leak, through different holes. happy-dom implements `fetch`, so a component pulling a remote asset really fetches it, nothing asserts on the response, and the aborts at teardown fail the run with **no test named** — a green run exiting 1 with `DOMException [AbortError]`. jsdom implements `XMLHttpRequest` in full, and the libraries that never left XHR (a VAST player pinging every tracker through a hand-rolled one) reach the internet once per ping per test, printing jsdom's `AggregateError at Object.dispatchError` for each connection that failed — so what a green run prints depends on whether the machine has a route out. Every channel is closed by default; the object is for narrowing it: | option | default | what it does | | -------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------- | | `fetch` | `true` | `fetch` rejects, naming what was requested | | `xhr` | `'reject'` | `'reject'` fails the request (`status` 0, an `error` event); `'empty'` answers 200 with an empty body; `false` leaves XHR alone | | `beacon` | `true` | `navigator.sendBeacon` answers `false` — only where the environment has one | `'reject'` is the default because it is what `fetch` does: the code takes its failure branch, which is the branch a unit test should be asserting on. `'empty'` is for a request whose response nobody reads — a tracker ping, an analytics beacon — where failing it only trades one kind of noise for another: ```ts setupAutoSpy({ blockNetwork: { xhr: 'empty' } }); // the ad-player suite's setting ``` **Called twice, the last caller's mode wins.** The setup file installs from its own `beforeEach`, which runs before the spec's, so a spec calling `blockNetwork({ xhr: 'reject' })` because the failure branch is what it is testing used to be served the setup file's empty 200 and pass on the wrong branch. The stubs are also installed once rather than re-journalled per test, so `restoreProps: false` no longer grows the restore journal for the length of the run. A `data:` URL is always let through, and it is the only thing that is: that is the scheme a spec serves its own fixtures from (`xhr.open('GET', \`data:application/xml,\${encodeURIComponent(vast)}\`)`), and the only one a DOM answers without a socket. A **relative** URL is not exempt either — the DOM resolves it against the document origin, so a spec that reaches `/config`and passes is resting on nothing listening on that port.`WebSocket`and`EventSource`are left alone: their failure is an event on an object the code keeps and reconnects, so there is no blanket answer that is not itself a behaviour change —`stubConstructor(globalThis, 'WebSocket', …)` is the tool for a spec with one. - `stubResponse(init?)` (`/setup`) builds a real `Response` — never write `{ ok, json } as Response`. Plain data in `body` goes out as JSON with `application/json`; an `ok` that disagrees with `status` throws. A body can be read once: for a stub answering several calls use `mockImplementation(async () => stubResponse(…))`, not `mockResolvedValue`. - **`body: null` is the JSON literal, and only `undefined` or an omitted `body` send no body.** It reverses what the field used to mean: `null` sent no body, so `.json()` threw `Unexpected end of JSON input` on it while `0`, `false`, `[]` and `{}` round-tripped — the one literal a reader had no reason to expect to be different, and the shape a backend answering "nothing here" (an empty login, an absent profile) really sends. A spec that meant "no body" drops the field. `{ body: null, status: 204 }` throws by name rather than letting the constructor raise "Response with null body status cannot have body" about a field whose old meaning was the opposite; 205 and 304 are the same. - `blockNetwork` leaves `fetch` alone while `Symbol.for('fetch-interceptor')` is on `globalThis` (MSW `setupServer`, nock 14), so MSW handlers keep answering; XHR stays blocked for what MSW does not handle. MSW's `onUnhandledRequest: 'error'` exempts asset-looking URLs (`.svg`, `.json`, fonts…); a last `http.all('*', () => HttpResponse.error())` is the hard floor. MSW's browser `setupWorker` has not been checked. `restoreTimerGlobals` is on by default and needs no thought unless you turn it off: uninstalling fake timers under happy-dom **deletes** `Date` instead of restoring it (the global is inherited from the realm, not owned by `globalThis`), and with `isolate: false` the next file dies inside Vitest's 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 own and defaults it to 10 000 ms. Carry a preset's `testTimeout: 30000` into the runner config and stop there, and every hook in the suite silently runs on a third of what its tests get. Worse, the failure is filed against the wrong thing: a `beforeEach` timeout is attributed to the **test**, with the test's duration pinned at the limit, so the report reads `× should create 10045ms` and sends the reader looking for ten seconds of work inside a body that never ran. The hint appends both numbers and the field to set. It says nothing when the budgets agree — then the hook really is slow — and nothing for `beforeEach(fn, 300)`, which chose its own limit. `beforeAll` is out of reach by construction: its timeout is reported as a failed _suite_, every test is skipped and no `afterEach` runs. **When migrating a runner config off Jest, set both timeouts side by side**, and treat the single Jest number as belonging to both fields: ```ts test: { testTimeout: 30_000, // Jest had one budget for both; Vitest defaults this to 10_000 on its own. hookTimeout: 30_000, } ``` `frozenClockHint` is the same seam aimed at the other half of a timeout. A frozen clock turns waiting into waiting forever — `await new Promise(r => setTimeout(r, 10))` never resolves unless something advances it — and the runner's own advice ("pass a timeout value as the last argument") is the one repair that cannot work: the callback is not late, it is never scheduled to run. Under `globalFakeTimers` nothing in the spec says the clock is fake at all, so the timeout lands in a file that never mentions a timer. The hint reports `vi.isFakeTimers()` and `vi.getTimerCount()` — facts, not a guess — and stays silent when the clock is real or its queue is empty. The shape that reaches this with no timer in sight is an HTTP spec. `setImmediate` is among the globals `vi.useFakeTimers()` replaces by default, and Express ends a request that matched no route through `finalhandler`, which schedules on `setImmediate`. So the 404 is never written and the test dies on its timeout: in such a file, "the test hung" means _the route did not match_, not "the server is slow". One thing this cannot see through — a spec whose own `afterEach` calls `vi.useRealTimers()`, because hooks run in reverse registration order and the clock is real again by the time the hint reads it. Nothing is reported then, rather than something wrong. `angularBuildHint` is the third read-only hint, and the only one that speaks before a test rather than after one. `@angular/build` in `[22.1.5, 22.1.7)` builds the unit-test bundle with esbuild code splitting off — every spec a self-contained bundle, `--coverage` growing by hundreds of megabytes with no plateau (791 chunks / 596 MB on a 784-spec suite) — and the builder says nothing. The `doctor` check `angular-build-splitting-off` reports it, but has to be run; this line is printed from inside the affected run, to stderr, once per worker. The builder is recognised by the marker its own `vitest-mock-patch` setup file sets (`Symbol.for('@angular/cli/vitest-mock-patch')` on `globalThis`, before any user setup file), so a plain Vitest run reads nothing; under the builder the version comes from the nearest `node_modules/@angular/build/package.json` above the working directory. That read is the one place the library touches the disk — one file, read-only, through `process.getBuiltinModule` so `/setup` still loads with no `process` — and `scripts/check-dist.mjs` allows `node:fs` in `dist/setup.js` for exactly that. Silent outside the builder, outside the window, and on a Node before `getBuiltinModule`. `setupAutoSpy({ angularBuildHint: false })` turns it off. One more field of the same family differs quietly and changes only the report: `slowTestThreshold` is `5` in Jest (**seconds**) and `300` in Vitest (**milliseconds**), so a migrated suite starts marking most of its files slow. That is a unit change, not a regression. Fake timers: ```ts import { advanceTimers, setupFakeTimers } from 'vitest-auto-spy/setup'; setupFakeTimers(); // install + restore, paired await advanceTimers(5_000); // advance AND drain the microtasks a bare advanceTimersByTime leaves ``` Coming from a Jest project that had `fakeTimers: { enableGlobally: true }`, every one of its tests was written against a frozen clock. Turning that back on file by file is a thousand edits; turn it on once instead: ```ts setupAutoSpy({ globalFakeTimers: true }); // or a vi.useFakeTimers() config ``` Both ends are guarded, which is the half a hand-written pair of hooks gets wrong: a spec that drives the clock itself would otherwise reach a second `vi.useRealTimers()`, and that one leaves the environment without `clearInterval` — which explodes during teardown of whichever file runs next. `globalFakeTimers` also keeps the clock fake **between** tests, and that half is not decoration: a `beforeAll` inside a nested `describe` runs after the previous test's `afterEach`, so a `beforeEach`-only pair leaves it on real timers and the block fails with `the timers APIs are not mocked` without touching a timer itself. For one `describe` instead of the whole run: `setupFakeTimers(config, { betweenTests: true })`. Whatever you turn on, the hooks belong to the spec file whose collection imported the setup module. If something keeps that module in the cache across files — `@angular/build:unit-test` under `--coverage` serves every test file as a wrapper around the built bundle, so the setup module is never re-evaluated — only the first file of each worker gets them, and the rest fail somewhere unrelated. Run coverage with `--isolate`, or call `setupAutoSpy()` from something evaluated per file. ### Freezing and counting the clock ```ts import { mockNow, mockSystemTime, useCountingClock, withSystemTime } from 'vitest-auto-spy/setup'; mockSystemTime('2025-04-30T00:00:00Z'); // works whether or not fakes are already installed await withSystemTime('2025-04-30T00:00:00Z', async () => { … }); // scoped, restores itself const clock = useCountingClock(); // Date.now() → 1, 2, 3 …, reset before every test mockNow(() => nextTimestamp()); // any Date.now source, re-applied before every test ``` **An assertion that contains a date must set the clock.** Otherwise the expected string is computed from `new Date()` and the test starts failing on its own some days after it was written — which reads as a regression and is not one. `vi.spyOn(globalThis, 'Date')` is not the way. Fake timers already own that global, so it throws `Date is not a constructor` with a stack in production code and no mention of timers. `mockSystemTime` does the right thing either way. Two rules about which of these composes with which, both of them earned: - **`withSystemTime` puts the previous time back**, including when fake timers were already running. Its undo used to be a no-op there, so the clock stayed where the callback left it for the rest of the test. - **`mockSystemTime()` installs `Date` and nothing else**, so `advanceTimers()` under it has nothing to advance. It used to pass having done nothing; it now refuses and names `setupFakeTimers()`. `setupFakeTimers(config)` installs the config it was given rather than deferring to whatever fakes were already up — a nested call, a global pair plus a local one, and the `Date`-only case all now end with the clock the call asked for, where the outer configuration used to win silently. `useCountingClock` exists because under fake timers every call inside one test reports the _same_ "now", so a spec that asserts on **order** or **duration** — analytics batches, tracing, a rate limiter, a TTL cache — cannot express its expectation at all. Patching `Date.now` by hand does not survive: `vi.useFakeTimers()` installs a fresh `Date` on every call, so a module-scope or `beforeAll` patch is left on an object nothing reads, and the naive undo re-attaches a dead clock's `now` to the live one. ### Asserting focus ```ts registerFocusMatchers(); // once, in the setup file expect(fixture.nativeElement.querySelector('.play')).toHaveFocus(); ``` The two idioms it replaces both fail unhelpfully: `expect(document.activeElement).toBe(el)` prints two whole DOM subtrees, and `expect(el === document.activeElement).toBe(true)` prints `expected false to deeply equal true`. The matcher separates the causes instead — the query found nothing, the element is not in the document, focus is still on `` (nothing claimed it), or focus is on another element, which it names as `button#save.primary` rather than as a subtree. ### Shared fixtures are functions, not constants Under `isolate: false` a module is evaluated **once per worker**, so this is one set of spies shared by every file that imports it, registered against whichever file got there first — and the others' `clearMocks` never reaches them. The symptom is a 30-second timeout, in a different file each run. ```ts // ❌ __mocks__/context.ts export const mockActionContext = { actions: { navigateToSection: vi.fn() } }; export const checkoutProvider = { provide: CheckoutState, useValue: { load: vi.fn() } }; // ✅ export const createActionContext = () => ({ actions: { navigateToSection: vi.fn() } }); export const createCheckoutProvider = () => ({ provide: CheckoutState, useValue: { load: vi.fn() } }); ``` A spec file must **export nothing**: under `isolate: false` an exported spec file is imported by its neighbours and loses its own suite. Put shared doubles in a `*.mock.ts` next to them, as factories. The `no-shared-module-level-mock` lint rule (§16) finds these mechanically. ### A stub must be re-installed for every test Every stub this library installs is taken off again by `restoreMockedProps()` after each test — that is what keeps it out of the next file. So a stub installed once at `describe` level, or in a `beforeAll`, is gone from the second test on, and what fails is an assertion about the component with the stub sitting ten lines above it, apparently in force. The same ordering bites the other way: a project-wide setup file installs its defaults in a root `beforeEach`, and root hooks run **before** a file's own — so a `beforeAll` in a spec loses to them silently, while a `beforeEach` wins. ```ts import { installPerTest } from 'vitest-auto-spy/setup'; const observers = installPerTest(() => stubIntersectionObserver({ autoEmit: true })); it('…', () => expect(observers().last.targets).toEqual([host])); ``` It hands back a **reader**, not the handle: the handle is a different object each test. ### Naming the file that sealed a global ```ts setupAutoSpy({ guardGlobals: 'throw' }); // or 'warn' while a suite is being cleaned up ``` `Object.defineProperty(document, 'cookie', { value })` defaults `configurable` to `false`, so the property can no longer be redefined _or_ deleted. Under `isolate: false` every later file in the worker inherits it, and what fails is some library, every other run, with nothing naming the file that did it. The guard compares `globalThis`, `document`, `navigator`, `location`, `screen` and the DOM prototypes a Jest-era stub reaches for — `Element`, `HTMLElement`, `HTMLCanvasElement`, `HTMLMediaElement`, `Node`, `EventTarget` — around every test, symbol keys included, and reports only what appeared and cannot be removed. **Its blind spot is an existing name redefined in place.** The guard reads a descriptor only for a key that was not there before, so `Object.defineProperty(document, 'cookie', { value, configurable: false })` over the `cookie` the environment already has is invisible to it: the name was in the snapshot, and only its configurability changed. What it catches is the addition — the shape that actually breaks a later file, because the next `defineProperty` of a name nothing expected is the one that throws. The snapshot is taken once per file, in `beforeAll`, rather than per test, and the comparison is also run after every `afterAll`, so a write made in a `beforeAll` or an `afterAll` is reported too. ### Naming the file that polluted `Object.prototype` ```ts setupAutoSpy(); // prototypePollution: 'throw' by default — 'warn' sweeps and only reports ``` Vitest walks a file's hooks with `for…in` in `mergeHooks`, so one own enumerable key on `Object.prototype` is spread as if it were an array during **collect**: `TypeError: Spread syntax requires ...iterable[Symbol.iterator] to be a function`, with no stack — every frame of it is filtered out by `stackIgnorePatterns`. Under `isolate: false` the key outlives its file, so **every later spec file in that worker fails to collect** while the run still reports success: `145 failed | 1613 passed` over `11880 passed | 0 failed`, zero failing tests because those files never ran. The guard compares `Object.prototype` / `Array.prototype` / `Function.prototype` around every test, takes the key back off and names the file. The write is nearly always accidental: `Object.getPrototypeOf(instance)` **is** `Object.prototype` when `instance` is an object literal from a `useValue` provider or a test double — patch the prototype of the class the object came from. `guardPrototypePollution(reaction)` from `/setup` registers the same check on its own, for a suite that does not call `setupAutoSpy()`. **A key an earlier file left behind is taken back before the next one is collected.** The per-test comparison cannot see a write made while a spec file was being imported or collected, or in its `afterAll` — all three happen outside any test, and the file that then fails to collect is the innocent one. `setupAutoSpy()` therefore also checks at the moment it is called, which is the one seam Vitest leaves between files: the key is deleted, a line goes to **stderr** naming it, and **nothing fails** — the file that would fail is not the file that wrote it. A key that refuses to be deleted is adopted into the baseline rather than reported once per file for the rest of the run. The in-file check still throws at its default grade; the file's own baseline is taken in `beforeAll` and re-checked after every `afterAll`, so a write made in either is covered as well. ### Naming the test that left an attribute on `` ```ts setupAutoSpy({ documentPollution: 'throw' }); // default 'off'; 'throw' under preset: 'strict' setupAutoSpy({ documentPollution: { reaction: 'throw', nodes: true, ignoreAttributes: [/^data-cdk-/], ignoreNodes: 'style' } }); ``` Under `isolate: false` every spec file in a worker shares one document. An attribute a component set on `` — `renderer.setAttribute(document.body, 'data-reset-focus', '')` in an `effect` — that nothing took off changes the branch a later file's code takes, so that file fails, only when the two share a worker and never alone. The guard records the attributes of ``, `` and `` before each test and compares them from `onTestFinished` — **after** the TestBed destroyed the fixtures in its own `afterEach`, so what a component removes in `ngOnDestroy` / `DestroyRef.onDestroy` is never reported. Every attribute added, changed or removed is named with both values, put back, and fails that test. An empty `class` or `style` reads as the attribute being absent, in both directions — `classList.add` followed by `remove` leaves `class=""` where there was none and nothing observable changed; any other empty value, `data-reset-focus=""` included, is still reported. A change made in a `beforeAll` and never undone fails the file, checked from a `beforeAll` cleanup after every `afterAll`. `nodes: true` also watches the child elements of `` and ``; it is off by default because a module that injects a stylesheet on first import does so once per worker. Blind spots: a write made while the spec file is imported, and a fixture kept alive by `teardown: { destroyAfterEach: false }` (reported against the test that rendered it). `guardDocumentPollution(option)` from `/setup` registers the same check on its own. Vitest only, like every `/setup` guard — `bun:test`, `node:test` and Rstest have no setup entry to host it. ### Failing on console output nothing absorbed ```ts setupAutoSpy({ strayConsole: 'throw' }); // default 'off'; 'warn' prints the same report without failing ``` Any call to a console method that writes (`log`, `info`, `warn`, `error`, `debug`, `trace`, `table`, `dir`, `dirxml`, `timeLog`, `timeEnd`, `count`; `group` with a label; a falsy `assert`) made during a test that nothing absorbed fails **that test**, quoting the method, the first three lines and the first frame outside `node_modules`: ``` [vitest-auto-spy] "CartService > reports a failed load" wrote to the console 1 time(s) and nothing absorbed it: - console.error: Error: load failed at CartService.load (src/app/cart.service.ts:41:15) ``` - **Absorbed** means the call never reached the console: a `/console` spy installed for the test or the file, `vi.spyOn(console, m).mockImplementation(…)`, any replacement that does not call through. A bare `vi.spyOn(console, m)` calls through and **counts**. - **This library's own `'warn'`-grade reports are not stray console output.** `guardGlobals`, `prototypePollution`, `unconfiguredReads`, `swallowedStrictCalls`, `misconfiguration`, the duplicate-copy report, the skipped-teardown net and the `test.concurrent` notice write past the guard's wrapper, so `'warn'` stays a warning under `strayConsole: 'throw'` instead of failing the test it is advising about. A `vi.spyOn(console, 'warn')` a test installs still absorbs them — the channel checks that the guard's own wrapper is the installed method and steps aside when anything sits on top of it. - Output **outside any test** — collection/import, `beforeAll` / `afterAll`, a callback after its test ended — fails the **file** in `afterAll` (`… outside any test …`). - Every console method a test replaced is put back after it; one a file replaced, after the file. - Under the guard, **importing `vitest-auto-spy/console` installs nothing** — call `installConsoleSpies()` in a `beforeEach` (or at the top of the file). Spies an import installed before the guard armed are taken off. - `strayConsole: { allow: ['…', /…/] }` is the last resort, for environment noise no spec can reach. Output written to `process.stdout` / `process.stderr` directly, and jsdom's own virtual console, is not seen. - The wrapper forwards every call unchanged, so Vitest's attribution and `onConsoleLog` still work. `guardStrayConsole(reaction)` registers the same guard on its own. ### One grade for everything — `preset: 'strict'` ```ts setupAutoSpy({ preset: 'strict' }); ``` Sets `duplicateCopies`, `propsOutsideHooks`, `guardGlobals`, `prototypePollution`, `documentPollution`, `strayConsole` and `misconfiguration` to `'throw'`, turns `strayTimers` on, and `strayRejections` on when zone.js is loaded. An option passed alongside still wins. **Not** included: `strict` (strict doubles change what an unconfigured call returns — a semantic switch, not a grade; the name was taken, hence `preset`) and `unconfiguredReads`, its read side (survey with `onUnstubbedRead` before turning it on), `blockNetwork` (changes the code under test), `restoreMocks` (drops `beforeAll` spies), failing on stray-timer counts (the sweep fails the file from `afterAll`, and a callback scheduled after the previous file's sweep is charged to the next — opt in with `onStrayTimers: ({ timers }) => expect(timers).toEqual([])`, whose diff names each one's file), and `enableAngularDiagnostics()`, which lives in `/angular/diagnostics` — call it in the same setup file as the Angular half of strict. `misconfiguration: 'throw'` on its own makes the library's misuse reports — an `onlyMethodsToSpyOn` typo, `gettersToSpyOn` naming a method, a `returns` key no spy answers to, `injectSpy` handed a real instance, a `jasmine.DEFAULT_TIMEOUT_INTERVAL` write, `providedMethodNames` — throw at the call site, every occurrence. The grade is process-wide and released after the file. The printed grade of the `injectSpy` warning is de-duplicated per token **per spec file**, no longer per worker. `withoutStrayTimerTracking(work)` runs setup work whose timers `strayTimers` neither counts nor cancels — jsdom answers every Web Storage write with a real `setTimeout(…, 0)`, and the library's own storage probe runs under it. **`test.concurrent` earns one warning per worker, and it is worth reading rather than silencing.** The per-test guards assume one test at a time: the document snapshot, the console window and the unconfigured-read counter are opened and judged per test, so with two in flight a finding can be charged to the other one — or cleared before anything sees it. The restores still run for every test, and the skipped-teardown net now remembers per test rather than per file, which is the half that was simply wrong. Run the files that need a guard sequentially, or keep `test.concurrent` for files whose setup passes `strayConsole: 'off'`, `documentPollution: 'off'` and `unconfiguredReads: 'off'`. **What `/setup` costs per test**, measured on happy-dom over 10 000 empty tests (2026-09-17, Node 24): the default `setupAutoSpy()` **19 µs**, `guardGlobals` **59 µs** (it snapshots once per file now, not once per test), `documentPollution` **23 µs** — it shares the `onTestFinished` the teardown net registers anyway — and `preset: 'strict'` **67 µs**. `documentPollution: { nodes: true }` over a `` of 1000 children is **0.19 ms** per test rather than 7.1 ms, because the children are walked as a sibling chain instead of through a live `HTMLCollection`; an `ignoreNodes` selector's answer for an element is decided at snapshot time and reused for that test. ### Hook order differs from Jest Vitest runs `afterEach` hooks as a stack (innermost / last-registered first); Jest ran them in declaration order. A ported suite where a spec's `afterEach` depends on a patch the setup file installed needs `sequence: { hooks: 'list' }` in the Vitest config, or the setup file's teardown runs first and the spec's hook operates on an already-restored environment. --- ## 11. Waiting: four queues, and which tool drives each Under Jest these were hard to tell apart; under Vitest with a real bundler they are four separate mechanisms, and a test that waits on the wrong one fails with a message that names none of them. | What is pending | What drives it | What does **not** | | ------------------------------------------------- | -------------------------------------------------- | ----------------------------------------- | | change detection | `fixture.detectChanges()` | anything `await`ed | | effects + `afterNextRender` + CD | `await stable(fixture)` (`…/angular`) | `detectChanges()` alone | | timers, debounces, polling | `await advanceTimers(ms)` (`…/setup`) | `await Promise.resolve()` | | a dynamic `import()`, native `async` in a dep | `await flushEventLoop()` / `settleDynamicImport()` | `tick()`, `flushMicrotasks()`, microtasks | | an `httpResource()` / `resource()` / `rxResource` | `await settleResource(r)` (`…/angular`) | `flushEventLoopUntil` — it never ticks | ```ts import { flushEventLoop, settleDynamicImport } from 'vitest-auto-spy'; fixture.debugElement.query(By.css('.open')).nativeElement.click(); // production code: await import(…) await settleDynamicImport(() => import('./profile-select.modal')); ``` Three rules worth stating outright, because each of them cost a day somewhere: - **`afterNextRender` does not run on `detectChanges()`.** A component that fills a form there is still empty when the assertion reads it. `await stable(fixture)` (or `await fixture.whenStable()`) is what runs the after-render phase. - **`fixture.whenRenderingDone()` is not a stronger `whenStable()`.** With an animation renderer installed it degrades to `Promise.resolve()`. Use `stable(fixture)`. - **`fakeAsync` / `tick()` / `flushMicrotasks()` never reach the module loader.** Spinning `await Promise.resolve()` ten times looks like it works and instead lands the continuation after teardown — a green run with `NG0205: Injector has already been destroyed` in "Unhandled Errors" and a non-zero exit code. **`stable()` and `flushEffects()` are not zoneless-only, and their tick runs inside the `NgZone` so that they are not.** `TestBed.createComponent` builds the component inside `ngZone.run(…)`, so an `effect()` its constructor registers records the zone's inner zone as its own. A bare `TestBed.tick()` from a test body runs in the runner's zone, so Angular hops back into the recorded one to run a **dirty** effect, and leaving that hop takes the zone from unstable to stable. `provideZoneChangeDetection()` — which `@angular/build:unit-test` installs for every suite that loads zone.js — answers `NgZone.onMicrotaskEmpty` with `ApplicationRef._tick()`, guarded against its own scheduler but not against `ApplicationRef._runningTick`, so the tick already on the stack is re-entered: `NG0101: ApplicationRef.tick is called recursively`. Angular hands that to `ErrorHandler` instead of throwing it at the call site, so a suite that does not fail on console output stays green with the change detection it asked for unfinished. Measured on an Angular 22 suite of 1771 spec files: 451 `componentRef.setInput` calls rewritten to `setInputs` turned **57 green files red** on `NG0101`, and none of them after the tick moved inside the zone. Under zoneless `NgZone` is a `NoopNgZone` whose `run` is a straight call, so it costs nothing there. One thing is genuinely new for a zone-based consumer: leaving the zone reports it stable, so the same subscriber ticks once more — counted on `ApplicationRef.afterTick`, one `flushEffects()` is 1 → 2 application ticks, which is what `fixture.detectChanges()` has always done in the same position. Do not "simplify" either helper back to a bare `TestBed.tick()`; `src/zone-tests/stable.zone-test.ts` is the guard. `flushEventLoopUntil(isDone, { turns, label })` is the same thing with a condition and a budget — for a chunk becoming reachable, an SDK reporting itself ready, a queue draining. Use it instead of a hand-tuned turn count: the count depends on the dependency, not on the spec, and a condition that never holds fails naming the `label` rather than hanging until the runner's timeout. **Not for an Angular `resource()` / `httpResource()`.** Those need a change-detection _tick_, and this helper only takes event-loop turns — a resource awaited through it finishes the whole budget having issued zero requests. `settleResource(resource, { turns, label, allowIdle })` from `vitest-auto-spy/angular` is that wait. `flushEventLoop(turns?)` takes real event-loop turns even while the timers are faked, without touching the clock. It is the honest name for the `await vi.advanceTimersByTimeAsync(0)` trick, which reads as "move the timers" in a test that has no timers and gets deleted as noise. --- ## 12. Doubles for what the code builds itself Production code that does `new Foo()` cannot be served by a `vi.fn()`. Vitest only forwards `new` to an implementation that is itself constructible, and **an arrow function is not**: the call is recorded, the body never runs, `new` hands back an empty object. The warning Vitest prints ("the mock did not use 'function' or 'class'") is nowhere near the failure, which arrives as `TypeError: (cb) => {…} is not a constructor` with a stack **in production code** — or as a green test for the wrong reason, when the resulting `undefined` is swallowed by a `catch`. ```ts import { createSpyClass, mockConstructor, stubConstructor } from 'vitest-auto-spy'; // a real class exists → full auto-spy instances mockValueProp(globalThis, 'Worker', createSpyClass(BackgroundWorker)); // only a type / a shape exists → a runner mock that is also a constructor const LicenseClient = mockConstructor(() => ({ prepareRequest: vi.fn() })); // it lives on a global (or any object) → the same, installed and auto-restored const Image = stubConstructor(globalThis, 'Image', () => ({ src: '' })); tracker.ping(); expect(Image).toHaveBeenCalledTimes(1); expect(Image.instances[0].src).toBe('https://tns.example/hit'); ``` `mockConstructor` stays a runner mock, so `toHaveBeenCalledWith` / `mockClear` work as usual, and it throws a named error if it is ever called **without** `new`. `stubConstructor` installs through `mockValueProp`, so `restoreMockedProps()` puts the platform's constructor back. **Static members are opt-in — `createSpyClass(Class, config, { statics: true })`.** Production code that reaches the class rather than an instance (`BackgroundWorker.isSupported()`, `Client.fromToken(t)`, a `VERSION` constant) finds nothing on the double otherwise, and the failure is a `TypeError` on the class, not on the spy: ```ts const WorkerSpy = createSpyClass(BackgroundWorker, undefined, { statics: true }); WorkerSpy.isSupported.mockReturnValue(true); // needs a cast — see below ``` What the option copies, walking the class's own prototype chain so inherited statics come too: a static **function** becomes a full spy of its own, a static **data member** is copied by value, and a static **accessor** is skipped and never evaluated — a getter that reads configuration or touches the network must not run because a double was built. `prototype`, `length`, `name`, `caller`, `arguments` and the double's own `calls` / `instances` are never overwritten. It is off by default for that last reason: a class with a static named `calls` would otherwise shadow the construction log. **The statics are not typed** — the return type is still `ConstructorSpy`, so reading one needs a cast at the spec; type them and this note goes. For the three observers, prefer the purpose-built stubs (§13). For `AbortController` — which breaks in a jsdom run for a reason involving none of the three parties in the stack trace — use `stubAbortController()`. The stub carries `AbortSignal.abort()`, `AbortSignal.timeout()` and `AbortSignal.any()` as well — the three statics are how modern code makes a signal without a controller, `fetch(url, { signal: AbortSignal.timeout(5_000) })` most of all. `timeout()` aborts through `setTimeout`, so `vi.useFakeTimers()` drives it exactly as it drives the platform's, and it aborts with a `TimeoutError` rather than an `AbortError` because that is the distinction the platform draws. A signal's `reason` is the platform's `DOMException`, so code branching on `signal.reason.name === 'AbortError'` takes the same branch it takes in a browser. ### `