vitest-auto-spy 5.3.0 → 5.5.0

package/AGENTS.md

@@ -643,9 +643,9 @@ Also true, and worth not re-deriving:
   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
+  **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<Response, { overload:
-  'first' }>` for one method collected five `TS2769`s on `download`. `overload` also takes a map:
+'first' }>` for one method collected five `TS2769`s on `download`. `overload` also takes a map:
 
   ```ts
   let perf: Spy<Performance, { overload: { getEntriesByType: 'first' } }>;
@@ -691,6 +691,21 @@ A second registration for the same class replaces the first, because two of them
 drift this removes rather than a merge to perform. `clearAutoSpyDefaults(Class)` drops one,
 `clearAutoSpyDefaults()` the lot.
 
+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<T>` is the row type, for a row built outside the literal.
+
 ### `strict` — a method nobody configured throws instead of answering `undefined`
 
 ```ts
@@ -808,7 +823,7 @@ carry (an index signature makes inference drop the default) and the union in `in
 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<T, U>(component: Type<T>,
+**A generic _method_ is a different thing, and it does collapse.** `show<T, U>(component: Type<T>,
 data: U)` on a modal or factory service reaches `Spy<T>` through `Parameters` / `ReturnType`, which
 instantiate the method's own type parameters — so the double types as `show(component: Type<unknown>,
 data: unknown)`. No mapped type in TypeScript can preserve a generic signature, so this is a limit
@@ -1031,6 +1046,29 @@ property. That is how you add an Observable member that `provideAutoSpy` did not
 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`,
@@ -1489,6 +1527,25 @@ worker inherits it, and what fails is some library, every other run, with nothin
 that did it. The guard compares `globalThis` / `document` / `navigator` around every test and reports
 only what appeared and cannot be removed.
 
+### 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()`.
+
 ### Hook order differs from Jest
 
 Vitest runs `afterEach` hooks as a stack (innermost / last-registered first); Jest ran them in
@@ -1965,13 +2022,13 @@ import { enableAngularDiagnostics } from 'vitest-auto-spy/angular';
 enableAngularDiagnostics(); // { ngModuleScopes, deadSchemas, unspiedProviders, pendingRequests }
 ```
 
-| Member             | Fails when                                                                       |
-| ------------------ | -------------------------------------------------------------------------------- |
-| `ngModuleScopes`   | a testing module imports an NgModule that contributes nothing at runtime         |
-| `deadSchemas`      | `schemas` sit next to a standalone component (`declarations` empty) — a no-op    |
-| `unspiedProviders` | `injectSpy` got a real instance; a `console.warn` alone, a throw under the group |
-| `pendingRequests`  | the test ended with unflushed `HttpTestingController` requests, named one by one |
-| `shadowedProviders` | a double on the testing module loses to the component's own `providers`         |
+| Member              | Fails when                                                                       |
+| ------------------- | -------------------------------------------------------------------------------- |
+| `ngModuleScopes`    | a testing module imports an NgModule that contributes nothing at runtime         |
+| `deadSchemas`       | `schemas` sit next to a standalone component (`declarations` empty) — a no-op    |
+| `unspiedProviders`  | `injectSpy` got a real instance; a `console.warn` alone, a throw under the group |
+| `pendingRequests`   | the test ended with unflushed `HttpTestingController` requests, named one by one |
+| `shadowedProviders` | a double on the testing module loses to the component's own `providers`          |
 
 Every member defaults to `true`, takes `false` to opt out, and a second call **replaces** the
 selection (safe from anywhere, including inside a test). `disableAngularDiagnostics()` turns the
@@ -2466,43 +2523,53 @@ export default [
 errors — `prefer-as-spy` (`TS2352`) and `no-mocked-for-spy` (`TS2322`). Spread its `rules` after a
 blanket downgrade so those keep their severity; do not copy the two names into a consumer's config.
 
-| Rule                              | Level   | Fix               | Flags                                                                                                                                     |
-| --------------------------------- | ------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| `no-expect-in-subscribe`          | `error` | suggest           | `expect()` inside `subscribe()` → `expectEmission` / `firstValueFrom`                                                                     |
-| `no-object-define-property`       | `error` | suggest           | `Object.defineProperty` in a spec → `mockReadonlyProp` / `mockValueProp`                                                                  |
-| `prefer-provide-auto-spy`         | `error` | —                 | a hand-rolled `useValue` **or** `useFactory` → `provideAutoSpy(Class)` / `provideAutoSpyForToken(TOKEN)`                                  |
-| `prefer-create-spy-from-class`    | `error` | —                 | an object literal of 2+ `vi.fn()`s → `createSpyFromClass` (a factory's own seed is exempt)                                                |
-| `prefer-inject-spy`               | `error` | suggest           | `vi.spyOn(TestBed.inject(X), 'm')`, inline or via a `const` → `injectSpy(X).m`                                                            |
-| `no-shared-module-level-mock`     | `error` | —                 | an **exported** value holding `vi.fn()`s → export a factory instead                                                                       |
-| `no-mocked-for-spy`               | `error` | `--fix` / suggest | `Mocked<T>` in any type position → `Spy<T>`, import and all — a suggestion where the assigned value is not from a factory of this library |
-| `prefer-as-spy`                   | `error` | `--fix`           | `TestBed.inject(X) as Spy<X>` → `asSpy<X>(TestBed.inject(X))`, import and all                                                             |
-| `no-done-callback`                | `error` | —                 | `it('x', (done) => …)` → `async` + an awaited assertion, and `done.fail(…)` at the call site                                              |
-| `no-floating-assertion`           | `error` | —                 | `expect()` in a `.then()` nobody awaits → `expect(await promise)`                                                                         |
-| `no-bare-called-with`             | `error` | —                 | `spy.m.calledWith(1);` as a statement — a stub nobody continued, asserting nothing; chai's `expect(fn).to.have.been.calledWith()` exempt  |
-| `no-overridden-provider`          | `error` | suggest           | two providers for one token in one array → the earlier one never runs; the exact duplicate can be deleted                                 |
-| `no-inject-before-override`       | `error` | —                 | `TestBed.inject()` / `injectSpy()` / `renderShallow()` in a hook, in a suite that still calls `override*`                                                                     |
-| `no-private-member-access`        | `error` | —                 | `instance['privateMember']`, `(instance as any).privateMember` (and `as unknown as`, and a decoy type), `vi.spyOn(Object.getPrototypeOf(x), 'm')` → drive the member through the public API. **Type-aware**: silent without `parserOptions.project`, and silent on an index signature |
-| `no-dead-schemas`                 | `error` | —                 | `schemas` on a testing module with no `declarations` — the schema applies to nothing; the file decides, so a `declarations` in another `configureTestingModule` call silences it |
-| `no-import-time-spread`           | `error` | suggest           | `export const x = [...Imported]` at module scope → a `TypeError` while the bundle loads                                                   |
-| `no-unregistered-inject-spy`      | `error` | —                 | `injectSpy(X)` for a token this file never registered → the real instance, whose spy helpers exist only for the compiler                  |
-| `prefer-render-shallow`           | `warn`  | suggest           | `TestBed.createComponent` in a file that never reads the template → `renderShallow(X)`; 0.24× the per-test cycle at 100 children          |
-| `prefer-observer-stub`            | `error` | —                 | a hand-rolled observer global → `stubIntersectionObserver()` / `stubResizeObserver()` / `stubMutationObserver()`; the manual save-and-restore goes too, `restoreMockedProps()` runs the undo |
-| `jasmine-namespace-without-entry` | `error` | —                 | `.and` / `.calls` / `.withArgs` on a library spy in a file that installs the compat layer nowhere — option: `{ setupModules: […] }`       |
-| `no-jasmine-globals`              | `error` | —                 | `jasmine.*`, bare `spyOn(` / `spyOnProperty(` / `spyOnAllFunctions(` / `fail(` / `pending(`, `.withContext(`                              |
-| `no-save-arguments-by-value`      | `error` | —                 | `spy.calls.saveArgumentsByValue()` — a no-op here, so the spec silently asserts on post-mutation state                                    |
-| `prefer-native-spy-api`           | `error` | `--fix` / suggest | `.and` / `.calls` where the spy's own API says the same thing — turn it on for the last mile off the jasmine shim                         |
-
-Twenty-three rules, **every one an `error` since 4.0.0 except `prefer-render-shallow`**; three fix on
-their own, eight offer suggestions. Twenty-two are syntactic; `no-private-member-access` is the one
+| Rule                              | Level   | Fix               | Flags                                                                                                                                                                                                                                                                                                                               |
+| --------------------------------- | ------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `no-expect-in-subscribe`          | `error` | suggest           | `expect()` inside `subscribe()` → `expectEmission` / `firstValueFrom`                                                                                                                                                                                                                                                               |
+| `no-object-define-property`       | `error` | suggest           | `Object.defineProperty` in a spec → `mockReadonlyProp` / `mockValueProp`                                                                                                                                                                                                                                                            |
+| `prefer-provide-auto-spy`         | `error` | —                 | a hand-rolled `useValue`, `useFactory`, `useClass` or `useExisting` (also `useValue: new StubMock()`), in a provider **or** a `TestBed.overrideProvider(X, { … })` → `provideAutoSpy(Class)` / `provideAutoSpyForToken(TOKEN)`. A name in the slot is followed one step, through an initialiser or a single `beforeEach` assignment |
+| `prefer-create-spy-from-class`    | `error` | —                 | an object literal of 2+ `vi.fn()`s → `createSpyFromClass` (a factory's own seed is exempt)                                                                                                                                                                                                                                          |
+| `no-stub-class-double`            | `warn`  | —                 | a class whose fields are `vi.fn()`s → `createSpyFromClass` / `provideAutoSpy` and delete the stub; a decorated, `implements`-ing, `extends`-ing or unnamed class is exempt — option: `{ minRunnerFns }`                                                                                                                             |
+| `no-structural-double`            | `warn`  | —                 | an object of `vi.fn()`s bound to a name declared `{ load: Mock }` → `createAutoMock<T>()`; a bare `let fn: Mock` is a callback and never reported — option: `{ minRunnerFns }`                                                                                                                                                      |
+| `prefer-inject-spy`               | `error` | suggest           | `vi.spyOn(TestBed.inject(X), 'm')`, inline or via a `const` → `injectSpy(X).m`                                                                                                                                                                                                                                                      |
+| `no-shared-module-level-mock`     | `error` | —                 | an **exported** value holding `vi.fn()`s → export a factory instead                                                                                                                                                                                                                                                                 |
+| `no-mocked-for-spy`               | `error` | `--fix` / suggest | `Mocked<T>` in any type position → `Spy<T>`, import and all — a suggestion where the assigned value is not from a factory of this library                                                                                                                                                                                           |
+| `prefer-as-spy`                   | `error` | `--fix`           | `TestBed.inject(X) as Spy<X>` → `asSpy<X>(TestBed.inject(X))`, import and all                                                                                                                                                                                                                                                       |
+| `no-done-callback`                | `error` | —                 | `it('x', (done) => …)` → `async` + an awaited assertion, and `done.fail(…)` at the call site                                                                                                                                                                                                                                        |
+| `no-floating-assertion`           | `error` | —                 | `expect()` in a `.then()` nobody awaits → `expect(await promise)`                                                                                                                                                                                                                                                                   |
+| `no-bare-called-with`             | `error` | —                 | `spy.m.calledWith(1);` as a statement — a stub nobody continued, asserting nothing; chai's `expect(fn).to.have.been.calledWith()` exempt                                                                                                                                                                                            |
+| `no-overridden-provider`          | `error` | suggest           | two providers for one token in one array, or one a `TestBed.overrideProvider` in the same hook replaces → the earlier one never runs; the exact duplicate can be deleted                                                                                                                                                            |
+| `no-inject-before-override`       | `error` | —                 | `TestBed.inject()` / `injectSpy()` / `renderShallow()` in a hook, in a suite that still calls `override*`                                                                                                                                                                                                                           |
+| `no-private-member-access`        | `error` | —                 | `instance['privateMember']`, `(instance as any).privateMember` (and `as unknown as`, and a decoy type), `vi.spyOn(Object.getPrototypeOf(x), 'm')` → drive the member through the public API. **Type-aware**: silent without `parserOptions.project`, and silent on an index signature                                               |
+| `no-dead-schemas`                 | `error` | —                 | `schemas` on a testing module with no `declarations` — the schema applies to nothing; the file decides, so a `declarations` in another `configureTestingModule` call silences it                                                                                                                                                    |
+| `no-import-time-spread`           | `error` | suggest           | `export const x = [...Imported]` at module scope → a `TypeError` while the bundle loads                                                                                                                                                                                                                                             |
+| `no-unregistered-inject-spy`      | `error` | —                 | `injectSpy(X)` for a token this file never registered → the real instance, whose spy helpers exist only for the compiler                                                                                                                                                                                                            |
+| `prefer-render-shallow`           | `warn`  | suggest           | `TestBed.createComponent` in a file that never reads the template → `renderShallow(X)`; 0.24× the per-test cycle at 100 children                                                                                                                                                                                                    |
+| `prefer-observer-stub`            | `error` | —                 | a hand-rolled observer global → `stubIntersectionObserver()` / `stubResizeObserver()` / `stubMutationObserver()`; the manual save-and-restore goes too, `restoreMockedProps()` runs the undo                                                                                                                                        |
+| `jasmine-namespace-without-entry` | `error` | —                 | `.and` / `.calls` / `.withArgs` on a library spy in a file that installs the compat layer nowhere — option: `{ setupModules: […] }`                                                                                                                                                                                                 |
+| `no-jasmine-globals`              | `error` | —                 | `jasmine.*`, bare `spyOn(` / `spyOnProperty(` / `spyOnAllFunctions(` / `fail(` / `pending(`, `.withContext(`                                                                                                                                                                                                                        |
+| `no-save-arguments-by-value`      | `error` | —                 | `spy.calls.saveArgumentsByValue()` — a no-op here, so the spec silently asserts on post-mutation state                                                                                                                                                                                                                              |
+| `prefer-native-spy-api`           | `error` | `--fix` / suggest | `.and` / `.calls` where the spy's own API says the same thing — turn it on for the last mile off the jasmine shim                                                                                                                                                                                                                   |
+
+Twenty-five rules, **every one an `error` since 4.0.0 except `prefer-render-shallow`,
+`no-stub-class-double` and `no-structural-double`**; three fix on their own, eight offer suggestions. Twenty-four are syntactic; `no-private-member-access` is the one
 that reads types, and it reports nothing at all without `parserOptions.project` / `projectService`
 rather than guessing. The config used to be a graded mix of `error` / `warn` / `off`, which decided for the
-consumer how much each finding mattered — a `warn` nothing reads is `off` with extra output. The one
-`warn` left is not a judgement about how much that finding matters but about what kind of finding it
-is: every other rule names something wrong or dead, while `prefer-render-shallow` names a file that
-could render more cheaply, and `renderShallow` is a migration a suite either takes or does not. At
-`error` the plugin would gate that migration — 491 findings across 398 of one consumer's 1759 spec
-files — so `recommended` would exist to be overridden. Set it to `'error'` once the project has decided
-to make the move. Three of
+consumer how much each finding mattered — a `warn` nothing reads is `off` with extra output. The
+three `warn`s left are not judgements about how much a finding matters. `prefer-render-shallow` is
+about the _kind_ of finding: every other rule names something wrong or dead, while this one names a
+file that could render more cheaply, and `renderShallow` is a migration a suite either takes or does
+not. At `error` the plugin would gate that migration — 491 findings across 398 of one consumer's
+1759 spec files — so `recommended` would exist to be overridden. `no-stub-class-double` and
+`no-structural-double` (5.5.0) are about the _evidence_: both report the same drift
+`prefer-create-spy-from-class` reports at `error`, but neither has a `provide:` beside it to settle
+the question, so each decides on a heuristic — and a project that disagrees with the reading has to
+be able to switch it off without losing the rule that reads a count. The counts are not the argument
+and moved a long way inside the release: measured on the same 1759 files, the two started at 12
+reports in 8 files and 115 in 74, and are 10 in 7 and 5 in 4 once `prefer-provide-auto-spy` learnt to
+follow a name into a `useValue` — 112 of those doubles are handed to Angular DI one name away, where
+a `provide:` settles it. That rule reports **154 times across 87 files** on the same suite, all at
+`error`. Set any of the three `warn`s to `'error'` once the batch is done. Three of
 them can report on a _correct_ project, and only one has an option:
 `jasmine-namespace-without-entry` takes `['error', { setupModules: ['./test-setup'] }]`, naming the
 file where `enableJasmineCompat()` is called; `prefer-native-spy-api` goes `'off'` for as long as a
@@ -2625,98 +2692,101 @@ packages, which a subpath export can never be.
 
 ## 17. Error → fix
 
-| Message contains                                                                                         | Cause                                                                                                                                                | Fix                                                                                                                                     |
-| -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| `No mock adapter registered`                                                                             | no runtime entry was imported, or the wrong one                                                                                                      | import `vitest-auto-spy` (Vitest) / `…/bun` / `…/node` once before creating spies                                                       |
-| `Observable spies require rxjs`                                                                          | the rxjs layer was never loaded                                                                                                                      | `import 'vitest-auto-spy/rxjs';` once, in the setup file                                                                                |
-| `Type 'SubjectLike<T>' is not assignable to type 'Subject<T>'`                                           | 4.0.0: `returnSubject()` is rxjs-typed only where `vitest-auto-spy/rxjs` is in the TypeScript program, and it is not in this one                     | put `import 'vitest-auto-spy/rxjs';` in a file the spec `tsconfig` includes — a `setupFiles` entry outside `include` is the usual cause |
-| `Cannot read properties of undefined (reading 'returnValue')` on `spy.m.and.…`                           | the jasmine namespaces are not installed — the spy was built before them, or nothing installed them at all                                           | import from `vitest-auto-spy/jasmine`; on Bun / `node:test`, `enableJasmineCompat()` in the setup file (§20)                            |
-| `spy.withArgs is not a function`                                                                         | the same, seen from the argument-matching side                                                                                                       | the same — or write `spy.m.calledWith(a).mockReturnValue(v)`, which needs no layer (§20)                                                |
-| `jasmine is not defined`                                                                                 | jasmine's global is the runner's, and Vitest declares none                                                                                           | `import { jasmine } from 'vitest-auto-spy/jasmine'`, then `codemod --from jasmine` to rewrite the members (§20)                         |
-| `done.fail is not a function`                                                                            | Vitest passes a `TestContext`, not jasmine's `done`; the line usually sits in an `error` callback nobody awaits, so the run stays **green**          | assert on the failure — `await expect(firstValueFrom(src$)).rejects.toMatchObject({ … })`, or `expect.fail(message)`                    |
-| a `.withContext('…')` message that never appears in the failure output                                   | Vitest's chai layer has an `@internal` `withContext(flags)`; handed a string it walks the character indices, sets nonsense flags and returns `this`  | `expect(actual, 'message').toBe(expected)` — the second argument of `expect` is the label. Nothing throws, so nothing warns (§20)       |
-| `names method(s) that are not on the class prototype`                                                   | typo, or an instance-field callable                                                                                                                  | fix the name, or move it to `instanceMethodsToSpyOn`                                                                                    |
-| `All declarations of 'Matchers' must have identical type parameters`                                     | a custom matcher declares `interface Matchers<T = any>` (the Vitest 4 shape) while Vitest 5 declares `Matchers<R, T>`                                | declare it on `Chai.Assertion` instead — that interface has no type parameters in either major, so one declaration merges on both (§10) |
-| `toHaveBeenCalledTimes` reads `0` for a call an earlier test made, after moving to Vitest 5              | `clearMocks` defaults to `true` on Vitest 5, so `vi.clearAllMocks()` runs before every test                                                          | count the calls in a plain variable instead of reading the spy, or set `clearMocks: false` (§10)                                        |
-| `was configured with 'mustBeCalledWith'`                                                                 | the code called the spy with other arguments                                                                                                         | that is the assertion firing — fix the code, or relax to `calledWith`                                                                   |
-| `extendWithAutoSpies needs Vitest 4.1 or newer`                                                          | the `test` handed in has only the object-form `extend` (Vitest ≤ 4.0); the builder form the helper is written against arrived in 4.1                 | upgrade Vitest, or keep `provideAutoSpy` + `injectSpy` in a `beforeEach` until then                                                     |
-| `advanceTimers() requires fake timers`                                                                   | no fake timers installed                                                                                                                             | `setupFakeTimers()` or `vi.useFakeTimers()` first                                                                                       |
-| `Nothing configured X.method, and strict mode is on`                                                     | a strict double was asked for a method no line configured                                                                                            | configure it (`mockReturnValue` / `resolveWith` / `nextWith` / `calledWith`), or `{ strict: false }` on that double (§5)                |
-| `Cannot redefine property: …` from a library accessor spy                                                | the target is an ES module namespace a bundler inlined                                                                                               | no spy library can win this — give the code a real seam (inject it, pass it in) and spy on that                                         |
-| `Cannot spy on this instance in place: it is not extensible`                                             | `createSpyFromInstance` was handed a frozen or sealed object                                                                                         | spy it before it is frozen, or build a separate double with `createSpyFromClass` (§2)                                                   |
-| `Cannot mock the property 'X': it is not configurable`                                                   | the member was defined with `configurable: false`, so it cannot be redefined                                                                         | members replaced before it are still restorable — `restoreSpiedInstance(instance)` or `restoreMockedProps()`                            |
-| `overrideComponentProvider(…): the override did not apply`                                               | the component injects a different token, or a later `overrideProvider` won                                                                           | pass the token the component actually injects (a base class, an `InjectionToken`), and override after nothing else re-configures        |
-| `the test ended with N unflushed HttpTestingController request(s)`                                       | `enableAngularDiagnostics({ pendingRequests })` — nothing answered them                                                                              | flush each (`controller.expectOne(url).flush(body)`), or `controller.verify()` where absence is the assertion (§13)                     |
-| `NgModule(s) with an empty runtime scope: …`                                                             | `ngModuleScopes` (or `assertNgModuleScopes`) — an AOT test bundle stripped `ɵɵsetNgModuleScope`, so the import contributes nothing                   | declare what the spec needs in the TestBed module directly; pass only modules expected to bring declarations (§13)                      |
-| `Cannot read properties of undefined (reading 'provide')`, stack inside `render3/di_setup`               | a barrel chunk had not run when the component's definition was built, so a provider slot is `undefined`                                              | `assertComponentDefIntact(Cmp)` before `createComponent` — it names the list and the index (§13)                                        |
-| `assertComponentDefIntact(): argument N is undefined, which carries no ɵcmp or ɵdir`                     | the class reference itself never arrived — the `Cannot read properties of undefined (reading 'ɵcmp')` case                                           | the same split barrel; import the component from its own module, not the barrel (§13)                                                   |
-| `TS1117: An object literal cannot have multiple properties with the same name`, in a fixture             | a hundred-line model literal copied into eight specs and edited independently                                                                        | one `createFixtureFactory<T>(defaults)`; note the runtime keeps the **second** key, so do not auto-fix by dropping one (§12)            |
-| `configureTestingModule was given N schema(s) that can never apply`                                      | `enableAngularDiagnostics({ deadSchemas })` — `schemas` next to a standalone component, with `declarations` empty                                    | drop the `schemas` entry and put the missing directive/pipe in the component's own `imports`, or use `createDirectiveHost` (§13)        |
-| `injectSpy(X): the injector returned a plain instance, not an auto-spy`                                  | the token is provided for real; a `console.warn` on its own, a **throw** under `enableAngularDiagnostics({ unspiedProviders })`                      | `provideAutoSpy(X)` / `provideAutoSpyForToken(TOKEN)`, or `TestBed.inject(X)` if the real thing is what the spec wants                  |
-| `trackInjections(...).get(X): that token is not tracked by this log`                                     | `get` only answers for tokens whose providers the log created                                                                                        | add the token to the `trackInjections([...])` list, or read it from the injector directly (§13)                                         |
-| `Spread syntax requires ...iterable[Symbol.iterator] to be a function`, at load time                     | a module-scope spread of an imported binding, inside a bundle                                                                                        | build the array in a function or a getter — `no-import-time-spread` (§16)                                                               |
-| `the timers APIs are not mocked` in a nested `describe`'s `beforeAll`                                    | fakes armed in `beforeEach` only; Jest armed them for the whole file                                                                                 | `setupFakeTimers(cfg, { betweenTests: true })` / `setupAutoSpy({ globalFakeTimers: true })`                                             |
-| setup-file hooks reaching only the first spec file of a worker                                           | the setup module stayed cached (Angular unit-test builder + coverage)                                                                                | run coverage with `--isolate`, or call `setupAutoSpy()` from a per-file module                                                          |
-| `no DOM could be installed`                                                                              | `bun-angular` preload with no DOM package                                                                                                            | `bun add -d @happy-dom/global-registrator` (or `jsdom`)                                                                                 |
-| `cannot read "…" referenced by …`                                                                        | a `templateUrl` / `styleUrls` path does not resolve                                                                                                  | fix the path, relative to the component file                                                                                            |
-| duplicate-copy report from `setupAutoSpy()`                                                              | two installs, or one loaded as both ESM and CJS                                                                                                      | dedupe the dependency; `setupAutoSpy({ duplicateCopies: 'warn' })` to downgrade                                                         |
-| `Type 'Spy<T>' is not assignable to type 'T'`                                                            | `Spy<T>` drops private members — by design                                                                                                           | declare as `Spy<T>`, or use `asInstance()` / `asSpy()` (§6)                                                                             |
-| a spy is never called, no warning                                                                        | the method is an instance field, not on the prototype                                                                                                | `instanceMethodsToSpyOn`, or `createAutoMock<T>()`                                                                                      |
-| `Cannot access '__vi_import_N__' before initialization`                                                  | `vi.mock()` on `@angular/core` or a relative path                                                                                                    | you cannot mock it — the specs are bundled. Assert the result instead                                                                   |
-| `AggregateError at Object.dispatchError`, for a request nothing asserts on                               | jsdom really served an `XMLHttpRequest` — `blockNetwork` used to cover only `fetch`                                                                  | `setupAutoSpy({ blockNetwork: true })`, or `{ xhr: 'empty' }` for tracker pings (§10)                                                   |
-| `localStorage.setItem is not a function`, or `localStorage` undefined                                    | Node's own Web Storage made Vitest's global filter skip the environment's — Node 25 and up, jsdom and happy-dom alike                                | on by default in `setupAutoSpy()`; `restoreWebStorage()` on its own (§10)                                                               |
-| `Schedulers cannot synchronously execute watches while scheduling`                                       | a timer from a **previous** file, under `isolate: false`                                                                                             | track and cancel pending timers/frames in the setup file (§10)                                                                          |
-| `signal read during notification phase`                                                                  | same — a stray `requestAnimationFrame` callback                                                                                                      | same                                                                                                                                    |
-| an assertion error printed to stderr, every test green and the run exiting 0                             | zone.js swallowed a rejection nobody handled                                                                                                         | `setupAutoSpy({ strayRejections: true })` fails the test it surfaced in (§10)                                                           |
-| an `expect()` inside a `.then()` that never seems to run                                                 | nothing awaits the chain, so the test ended first                                                                                                    | `await` the promise and assert the settled value — `no-floating-assertion` (§16)                                                        |
-| `trackStrayRejections() found no zone.js on the host`                                                    | `strayRejections` turned on where zone.js is not loaded                                                                                              | `import 'zone.js';` in the setup file, or drop the option                                                                               |
-| `… .destroy is not a function`                                                                           | an ngrx `rxMethod` replaced with a bare mock                                                                                                         | `Object.assign(vi.fn(), { destroy: vi.fn() })`                                                                                          |
-| `NullInjectorError` for a service you did provide                                                        | it is a component-level provider, not a module one                                                                                                   | `asSpy(fixture.debugElement.injector.get(X))`, not `injectSpy(X)`                                                                       |
-| `runEffect(): … not an EffectRef returned by effect()`                                                   | passed the callback, a signal, or an unassigned field                                                                                                | pass what `effect()` returned; a field may need its lifecycle hook to run first                                                         |
-| `X is not a constructor`, stack in production code                                                       | a `vi.fn(() => …)` where the code does `new X()`                                                                                                     | `mockConstructor` / `stubConstructor` / `createSpyClass` (§12)                                                                          |
-| `Date is not a constructor`                                                                              | `vi.spyOn(globalThis, 'Date')` — the fakes own it                                                                                                    | `mockSystemTime(date)` / `vi.setSystemTime`                                                                                             |
-| `TS2352: … 'accessorSpies' is missing in type 'X'`                                                       | `TestBed.inject(X) as Spy<X>`                                                                                                                        | `asSpy(TestBed.inject(X))` — never a double assertion (§6)                                                                              |
-| `TS2739` / `TS2740` / `TS2345` with `Spy<X>` on the left                                                 | a spy handed to an API typed against the class                                                                                                       | `asInstance(spy)` (§6)                                                                                                                  |
-| `is missing the following properties: _private, …`                                                       | declared as Vitest's `Mocked<T>`                                                                                                                     | declare `Spy<T>` (§6)                                                                                                                   |
-| `AddPromiseSpyMethods<unknown>` vs `WithMockReturnValue<…>`                                              | a generic class inferred as `Service<any>`                                                                                                           | `asSpy<Service>(…)` / `injectSpy<Service>(…)` (§6)                                                                                      |
-| `'addEventListener' called on an object that is not a valid instance of EventTarget`                     | Node's `AbortSignal` under jsdom + zone.js                                                                                                           | `stubAbortController()` (§12)                                                                                                           |
-| `vi.requireMock is not a function`                                                                       | a mechanical `jest.` → `vi.` rename                                                                                                                  | there is no equivalent — provide the double through the TestBed instead                                                                 |
-| a `vi.mock()` factory that never applies, only sometimes                                                 | under `isolate: false` the module was already in the worker's graph                                                                                  | do not mock it; inject the dependency, or `vi.hoisted()` + a real seam                                                                  |
-| a `vi.mock()` of a workspace alias that never applies at all                                             | a bundler inlined the module before the mock could be installed                                                                                      | `assertMocked(ns, { specifier })` to prove it, then inject instead of mocking                                                           |
-| `No "default" export is defined on the mock`, thrown inside a dependency                                 | a factory returning bare named exports; the dep probes `default`                                                                                     | `vi.mock('x', () => moduleNamespace({ … }))`                                                                                            |
-| `Not implemented: HTMLMediaElement.play`, or `duration` is `NaN` and cannot be set                       | jsdom implements the media elements as a shell                                                                                                       | `stubMediaElement({ duration })`, then `media.set(el, …)` to fire the events                                                            |
-| `Cannot set base providers because it has already been called`                                           | zone and zoneless spec files sharing one worker                                                                                                      | `setupAngularTestEnv({ zoneless, initZone, initZoneless })` (§13)                                                                       |
-| a stub that works in the first test of the file and in no other                                          | installed at `describe` level or in `beforeAll`, then restored away                                                                                  | install it in `beforeEach`, or `installPerTest(() => stub…())`                                                                          |
-| a third-party library failing every other run, no test named                                             | a test sealed a global with `Object.defineProperty` (non-configurable)                                                                               | `setupAutoSpy({ guardGlobals: 'throw' })` names the file; then `mockValueProp`                                                          |
-| `expected [ { at: 1, …(5) }, …(8) ] to deeply equal [ { …(6) }, … ]`                                     | one field moved in every element — usually a frozen clock or an id                                                                                   | `expect(diffByField(actual, expected)).toBeUndefined()`                                                                                 |
-| a hand-tuned number of turns waiting for a `resource()` to load                                          | a resource needs a change-detection **tick**, not event-loop turns; `flushEventLoopUntil` never ticks and the resource never even issues its request | `flushEffects()`, flush the request, then `await settleResource(r, { label })`                                                          |
-| a `resource()` assertion that passes but reads the **default** value                                     | the spec asserted before the resource left `loading`                                                                                                 | `await settleResource(r, { label })` — it fails loudly instead                                                                          |
-| a spec dying on the runner's 5 s file timeout right after `await stable(fixture)`                        | the fixture never stabilised — an unflushed request, a real `setInterval`                                                                            | `stable` now fails at 2000 ms naming the cause; raise `{ timeout }` only once neither is true                                           |
-| `flushEventLoopUntil` timing out on the **first** such test only, the rest green                         | a cold dynamic `import()` outran the turn budget; later tests hit the module cache                                                                   | `await settleDynamicImport(() => import('…'))` — await the module, do not count turns                                                   |
-| `Expected to be running in 'ProxyZone', but it was not found`                                            | `zone.js/testing` patches jasmine/mocha/jest, not Vitest                                                                                             | `import 'vitest-auto-spy/zone'` after zone.js, with `globals: true` (§14)                                                               |
-| `nextWith` demanding `HttpEvent<T>` on a generated API client                                            | `Parameters`/`ReturnType` read the **last** overload                                                                                                 | `asSpy<Client, { overload: 'first' }>(…)`, or `Overload<M, 0>`                                                                          |
-| `NG0303` / `NG0304` / nothing at all, from a directive spec                                              | the host is `standalone: false`, or the module is in the TestBed                                                                                     | `createDirectiveHost({ template, scope: [Module] })` (§13)                                                                              |
-| `TS2540: Cannot assign to 'X' because it is a read-only property`                                        | a `readonly` field of an object under test                                                                                                           | `mockValueProp(obj, 'X', value)` — on a class **getter**, `mockReadonlyProp`                                                            |
-| `TypeError: Cannot read properties of undefined (reading 'mockReturnValue')`                             | the member is an **instance field**, not on the prototype — `Router.currentNavigation` since Angular 20                                              | `provideAutoSpy(Router, { instanceMethodsToSpyOn: ['currentNavigation'] })` (§5)                                                        |
-| `throwWith` reaching the success branch first, with the previous test's value                            | the spy's `ReplaySubject(1)` outlived the test that filled it                                                                                        | upgrade; and `resetAutoSpy(spy)` in `beforeEach` when the TestBed is built in `beforeAll`                                               |
-| `TS2540` on a `Spy<T>` / `createAutoMock` member, which the runtime writes fine                          | `Spy<T>` is homomorphic and keeps the `readonly` of the source member — deliberately: on a member replaced by a **spied accessor** the assignment reaches the setter spy and the getter still answers `undefined`, so the type error is the loud version of a silent no-op | `mockValueProp(spy, 'X', value)` — it defines rather than assigns, so it works in both cases; `Mutable<Spy<T>>` is the opt-in for plain data members, and `Reflect.set` is **not** a way round it |
-| `TS2345` from `mockReturnValue` / `mockImplementation` / `mockResolvedValue` on a double that used to compile | the mock surface is `MockInstance<Method>`, so the stub is now checked against the method's own return type                                          | stub with what the method returns; if the double is meant to answer something else, the method's type or the spec's expectation is wrong |
-| `delete mock.optionalMethod` leaving the member present and truthy                                       | the Proxy had no `deleteProperty` trap before 3.5.0                                                                                                  | upgrade; before that, `mock.optionalMethod = undefined`                                                                                 |
-| half a double's methods reaching the real implementation after `Object.assign`                           | `ownKeys` on a type-driven Proxy lists only the keys already read                                                                                    | `createSpyFromClass(X)` — a real object, with enumerable method keys                                                                    |
-| `let s: MockInstance<() => unknown>` not matching anything                                               | `MockInstance<F>` is invariant in `F`; Jest's `SpyInstance` was not                                                                                  | `MockInstance<T['method']>`, or better `injectSpy(X).method`                                                                            |
-| two runs with the same totals, one of them missing a suite                                               | a lost `describe` and a fixed flake cancel out in the counters                                                                                       | `compareTestRuns(before, after)` — compare the set of names, not the numbers                                                            |
-| a 30 s timeout, in a different file each run                                                             | module-level `vi.fn()` in a fixture shared by files                                                                                                  | make the fixture a factory (§10)                                                                                                        |
-| a component's `afterNextRender` state is empty                                                           | `detectChanges()` does not run the after-render phase                                                                                                | `await stable(fixture)` (§11)                                                                                                           |
-| a green test whose only line about a call is `spy.m.calledWith(1);`                                      | that is a **stub**, not an assertion — chai's `expect(fn).to.have.been.calledWith(x)` is the one that checks                                         | continue the chain, or `expect(spy.m).toHaveBeenCalledWith(1)` — `no-bare-called-with` (§16)                                            |
-| `--detect-async-leaks` reporting no leaks in a suite that visibly leaks timers                           | `setupAutoSpy({ strayTimers: true })` cancelled them before Vitest collected                                                                         | re-run that file with `strayTimers` off; the warning on stderr says how many were taken (§10)                                           |
-| `createNestUnit(X): parameter #n of Y is typed as \`Object\``(or`undefined — usually a circular import`) | the compiler emitted no runtime class for that parameter — interface, union, primitive, or a circular import                                         | `@Inject(TOKEN)` plus a `providers` entry, or `@Optional()` to receive `undefined`; `@Inject(forwardRef(() => X))` for the import cycle |
-| `createNestUnit(X): Y declares n constructor parameter(s) but carries no design:paramtypes metadata`     | no `emitDecoratorMetadata` (esbuild / Vite), or `reflect-metadata` loaded after the class                                                            | tsc or SWC with `decoratorMetadata`, `@Injectable()`, `reflect-metadata` first; or `@Inject(X)` on every parameter                      |
-| `createNestUnit(X): A -> B -> A is a cycle among the classes built for real`                             | two exposed / `useClass` classes depend on each other; the helper does not resolve `forwardRef` cycles                                               | expose one side less, or provide it                                                                                                     |
-| `createNestUnit(X).spies.get(Y): the unit never asked for that token`                                    | same guard as `createWithAutoSpies` — the spy would not be the one the unit uses                                                                     | stub the token the unit actually injects (the message lists the auto-spied ones)                                                        |
-| `createNestUnit(X).spies.get(Y): Y is in \`expose\`, so the unit got a real instance`                    | an exposed class is real, not a spy                                                                                                                  | read the spies of its own collaborators, or drop it from `expose`                                                                       |
-| `no request matched …` (with the requests that were made listed)                                         | the URL, verb or predicate does not describe anything the code under test sent, or nothing subscribed                                                | read the list in the message — it is the requests that were actually made; then fix the URL, add `{ method }`, or subscribe (§13)       |
-| `this TestBed has no HttpTestingController`                                                              | `expectRequest` / `expectNoRequest` on a module that never got the testing backend                                                                   | `TestBed.configureTestingModule({ providers: [...provideHttpTesting()] })` from `vitest-auto-spy/angular-http` (§13)                    |
-| `the test ended with N unanswered request(s)`                                                            | `provideHttpTesting({ verifyOnTeardown })` found a request the spec never flushed                                                                    | answer it (`await expectRequest(url).flush(body)`), assert its absence (`expectNoRequest(url)`), or `{ verifyOnTeardown: false }` (§13) |
+| Message contains                                                                                              | Cause                                                                                                                                                                                                                                                                      | Fix                                                                                                                                                                                                                                                                                                       |
+| ------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `No mock adapter registered`                                                                                  | no runtime entry was imported, or the wrong one                                                                                                                                                                                                                            | import `vitest-auto-spy` (Vitest) / `…/bun` / `…/node` once before creating spies                                                                                                                                                                                                                         |
+| `Observable spies require rxjs`                                                                               | the rxjs layer was never loaded                                                                                                                                                                                                                                            | `import 'vitest-auto-spy/rxjs';` once, in the setup file                                                                                                                                                                                                                                                  |
+| `Type 'SubjectLike<T>' is not assignable to type 'Subject<T>'`                                                | 4.0.0: `returnSubject()` is rxjs-typed only where `vitest-auto-spy/rxjs` is in the TypeScript program, and it is not in this one                                                                                                                                           | put `import 'vitest-auto-spy/rxjs';` in a file the spec `tsconfig` includes — a `setupFiles` entry outside `include` is the usual cause                                                                                                                                                                   |
+| `Cannot read properties of undefined (reading 'returnValue')` on `spy.m.and.…`                                | the jasmine namespaces are not installed — the spy was built before them, or nothing installed them at all                                                                                                                                                                 | import from `vitest-auto-spy/jasmine`; on Bun / `node:test`, `enableJasmineCompat()` in the setup file (§20)                                                                                                                                                                                              |
+| `spy.withArgs is not a function`                                                                              | the same, seen from the argument-matching side                                                                                                                                                                                                                             | the same — or write `spy.m.calledWith(a).mockReturnValue(v)`, which needs no layer (§20)                                                                                                                                                                                                                  |
+| `jasmine is not defined`                                                                                      | jasmine's global is the runner's, and Vitest declares none                                                                                                                                                                                                                 | `import { jasmine } from 'vitest-auto-spy/jasmine'`, then `codemod --from jasmine` to rewrite the members (§20)                                                                                                                                                                                           |
+| `done.fail is not a function`                                                                                 | Vitest passes a `TestContext`, not jasmine's `done`; the line usually sits in an `error` callback nobody awaits, so the run stays **green**                                                                                                                                | assert on the failure — `await expect(firstValueFrom(src$)).rejects.toMatchObject({ … })`, or `expect.fail(message)`                                                                                                                                                                                      |
+| a `.withContext('…')` message that never appears in the failure output                                        | Vitest's chai layer has an `@internal` `withContext(flags)`; handed a string it walks the character indices, sets nonsense flags and returns `this`                                                                                                                        | `expect(actual, 'message').toBe(expected)` — the second argument of `expect` is the label. Nothing throws, so nothing warns (§20)                                                                                                                                                                         |
+| `names method(s) that are not on the class prototype`                                                         | typo, or an instance-field callable                                                                                                                                                                                                                                        | fix the name, or move it to `instanceMethodsToSpyOn`                                                                                                                                                                                                                                                      |
+| `All declarations of 'Matchers' must have identical type parameters`                                          | a custom matcher declares `interface Matchers<T = any>` (the Vitest 4 shape) while Vitest 5 declares `Matchers<R, T>`                                                                                                                                                      | declare it on `Chai.Assertion` instead — that interface has no type parameters in either major, so one declaration merges on both (§10)                                                                                                                                                                   |
+| `toHaveBeenCalledTimes` reads `0` for a call an earlier test made, after moving to Vitest 5                   | `clearMocks` defaults to `true` on Vitest 5, so `vi.clearAllMocks()` runs before every test                                                                                                                                                                                | count the calls in a plain variable instead of reading the spy, or set `clearMocks: false` (§10)                                                                                                                                                                                                          |
+| `was configured with 'mustBeCalledWith'`                                                                      | the code called the spy with other arguments                                                                                                                                                                                                                               | that is the assertion firing — fix the code, or relax to `calledWith`                                                                                                                                                                                                                                     |
+| `extendWithAutoSpies needs Vitest 4.1 or newer`                                                               | the `test` handed in has only the object-form `extend` (Vitest ≤ 4.0); the builder form the helper is written against arrived in 4.1                                                                                                                                       | upgrade Vitest, or keep `provideAutoSpy` + `injectSpy` in a `beforeEach` until then                                                                                                                                                                                                                       |
+| `advanceTimers() requires fake timers`                                                                        | no fake timers installed                                                                                                                                                                                                                                                   | `setupFakeTimers()` or `vi.useFakeTimers()` first                                                                                                                                                                                                                                                         |
+| `Nothing configured X.method, and strict mode is on`                                                          | a strict double was asked for a method no line configured                                                                                                                                                                                                                  | configure it (`mockReturnValue` / `resolveWith` / `nextWith` / `calledWith`), or `{ strict: false }` on that double (§5)                                                                                                                                                                                  |
+| `Cannot redefine property: …` from a library accessor spy                                                     | the target is an ES module namespace a bundler inlined                                                                                                                                                                                                                     | no spy library can win this — give the code a real seam (inject it, pass it in) and spy on that                                                                                                                                                                                                           |
+| `Cannot spy on this instance in place: it is not extensible`                                                  | `createSpyFromInstance` was handed a frozen or sealed object                                                                                                                                                                                                               | spy it before it is frozen, or build a separate double with `createSpyFromClass` (§2)                                                                                                                                                                                                                     |
+| `Cannot mock the property 'X': it is not configurable`                                                        | the member was defined with `configurable: false`, so it cannot be redefined                                                                                                                                                                                               | members replaced before it are still restorable — `restoreSpiedInstance(instance)` or `restoreMockedProps()`                                                                                                                                                                                              |
+| `overrideComponentProvider(…): the override did not apply`                                                    | the component injects a different token, or a later `overrideProvider` won                                                                                                                                                                                                 | pass the token the component actually injects (a base class, an `InjectionToken`), and override after nothing else re-configures                                                                                                                                                                          |
+| `the test ended with N unflushed HttpTestingController request(s)`                                            | `enableAngularDiagnostics({ pendingRequests })` — nothing answered them                                                                                                                                                                                                    | flush each (`controller.expectOne(url).flush(body)`), or `controller.verify()` where absence is the assertion (§13)                                                                                                                                                                                       |
+| `NgModule(s) with an empty runtime scope: …`                                                                  | `ngModuleScopes` (or `assertNgModuleScopes`) — an AOT test bundle stripped `ɵɵsetNgModuleScope`, so the import contributes nothing                                                                                                                                         | declare what the spec needs in the TestBed module directly; pass only modules expected to bring declarations (§13)                                                                                                                                                                                        |
+| `Cannot read properties of undefined`, stack inside the component's own constructor or a field initializer    | a member the double must **hold** rather than spy on is read while the component is being constructed, and the `mockReadonlyProp` that seeds it is written _below_ `TestBed.createComponent` — so it has not run yet, and never will                                       | seed it **before** construction: `provideAutoSpy(X, { overrides: { paymentParams: … } })`, or `provideAutoSpyForToken(TOKEN, { … })`. No later call can repair this — the throw happens inside `createComponent`, so the helper is not reached and cannot say so; the stack names the component (§9, §13) |
+| `arr.map(asInstance)` infers `unknown[]`                                                                      | `asInstance` is overloaded, and passing it **by reference** resolves against the `DeepMockProxy<T>` overload, from which `T` cannot be inferred                                                                                                                            | `arr.map((spy) => asInstance(spy))` — the arrow gives each call its own inference. For a fixed set, `asInstances(a, b, c)` keeps the tuple types (§6)                                                                                                                                                     |
+| `Cannot read properties of undefined (reading 'provide')`, stack inside `render3/di_setup`                    | a barrel chunk had not run when the component's definition was built, so a provider slot is `undefined`                                                                                                                                                                    | `assertComponentDefIntact(Cmp)` before `createComponent` — it names the list and the index (§13)                                                                                                                                                                                                          |
+| `assertComponentDefIntact(): argument N is undefined, which carries no ɵcmp or ɵdir`                          | the class reference itself never arrived — the `Cannot read properties of undefined (reading 'ɵcmp')` case                                                                                                                                                                 | the same split barrel; import the component from its own module, not the barrel (§13)                                                                                                                                                                                                                     |
+| `TS1117: An object literal cannot have multiple properties with the same name`, in a fixture                  | a hundred-line model literal copied into eight specs and edited independently                                                                                                                                                                                              | one `createFixtureFactory<T>(defaults)`; note the runtime keeps the **second** key, so do not auto-fix by dropping one (§12)                                                                                                                                                                              |
+| `configureTestingModule was given N schema(s) that can never apply`                                           | `enableAngularDiagnostics({ deadSchemas })` — `schemas` next to a standalone component, with `declarations` empty                                                                                                                                                          | drop the `schemas` entry and put the missing directive/pipe in the component's own `imports`, or use `createDirectiveHost` (§13)                                                                                                                                                                          |
+| `injectSpy(X): the injector returned a plain instance, not an auto-spy`                                       | the token is provided for real; a `console.warn` on its own, a **throw** under `enableAngularDiagnostics({ unspiedProviders })`                                                                                                                                            | `provideAutoSpy(X)` / `provideAutoSpyForToken(TOKEN)`, or `TestBed.inject(X)` if the real thing is what the spec wants                                                                                                                                                                                    |
+| `trackInjections(...).get(X): that token is not tracked by this log`                                          | `get` only answers for tokens whose providers the log created                                                                                                                                                                                                              | add the token to the `trackInjections([...])` list, or read it from the injector directly (§13)                                                                                                                                                                                                           |
+| `Spread syntax requires ...iterable[Symbol.iterator] to be a function`, at load time                          | a module-scope spread of an imported binding, inside a bundle                                                                                                                                                                                                              | build the array in a function or a getter — `no-import-time-spread` (§16)                                                                                                                                                                                                                                 |
+| `the timers APIs are not mocked` in a nested `describe`'s `beforeAll`                                         | fakes armed in `beforeEach` only; Jest armed them for the whole file                                                                                                                                                                                                       | `setupFakeTimers(cfg, { betweenTests: true })` / `setupAutoSpy({ globalFakeTimers: true })`                                                                                                                                                                                                               |
+| setup-file hooks reaching only the first spec file of a worker                                                | the setup module stayed cached (Angular unit-test builder + coverage)                                                                                                                                                                                                      | run coverage with `--isolate`, or call `setupAutoSpy()` from a per-file module                                                                                                                                                                                                                            |
+| `no DOM could be installed`                                                                                   | `bun-angular` preload with no DOM package                                                                                                                                                                                                                                  | `bun add -d @happy-dom/global-registrator` (or `jsdom`)                                                                                                                                                                                                                                                   |
+| `cannot read "…" referenced by …`                                                                             | a `templateUrl` / `styleUrls` path does not resolve                                                                                                                                                                                                                        | fix the path, relative to the component file                                                                                                                                                                                                                                                              |
+| duplicate-copy report from `setupAutoSpy()`                                                                   | two installs, or one loaded as both ESM and CJS                                                                                                                                                                                                                            | dedupe the dependency; `setupAutoSpy({ duplicateCopies: 'warn' })` to downgrade                                                                                                                                                                                                                           |
+| `Type 'Spy<T>' is not assignable to type 'T'`                                                                 | `Spy<T>` drops private members — by design                                                                                                                                                                                                                                 | declare as `Spy<T>`, or use `asInstance()` / `asSpy()` (§6)                                                                                                                                                                                                                                               |
+| a spy is never called, no warning                                                                             | the method is an instance field, not on the prototype                                                                                                                                                                                                                      | `instanceMethodsToSpyOn`, or `createAutoMock<T>()`                                                                                                                                                                                                                                                        |
+| `Cannot access '__vi_import_N__' before initialization`                                                       | `vi.mock()` on `@angular/core` or a relative path                                                                                                                                                                                                                          | you cannot mock it — the specs are bundled. Assert the result instead                                                                                                                                                                                                                                     |
+| `AggregateError at Object.dispatchError`, for a request nothing asserts on                                    | jsdom really served an `XMLHttpRequest` — `blockNetwork` used to cover only `fetch`                                                                                                                                                                                        | `setupAutoSpy({ blockNetwork: true })`, or `{ xhr: 'empty' }` for tracker pings (§10)                                                                                                                                                                                                                     |
+| `localStorage.setItem is not a function`, or `localStorage` undefined                                         | Node's own Web Storage made Vitest's global filter skip the environment's — Node 25 and up, jsdom and happy-dom alike                                                                                                                                                      | on by default in `setupAutoSpy()`; `restoreWebStorage()` on its own (§10)                                                                                                                                                                                                                                 |
+| `Schedulers cannot synchronously execute watches while scheduling`                                            | a timer from a **previous** file, under `isolate: false`                                                                                                                                                                                                                   | track and cancel pending timers/frames in the setup file (§10)                                                                                                                                                                                                                                            |
+| `signal read during notification phase`                                                                       | same — a stray `requestAnimationFrame` callback                                                                                                                                                                                                                            | same                                                                                                                                                                                                                                                                                                      |
+| an assertion error printed to stderr, every test green and the run exiting 0                                  | zone.js swallowed a rejection nobody handled                                                                                                                                                                                                                               | `setupAutoSpy({ strayRejections: true })` fails the test it surfaced in (§10)                                                                                                                                                                                                                             |
+| an `expect()` inside a `.then()` that never seems to run                                                      | nothing awaits the chain, so the test ended first                                                                                                                                                                                                                          | `await` the promise and assert the settled value — `no-floating-assertion` (§16)                                                                                                                                                                                                                          |
+| `trackStrayRejections() found no zone.js on the host`                                                         | `strayRejections` turned on where zone.js is not loaded                                                                                                                                                                                                                    | `import 'zone.js';` in the setup file, or drop the option                                                                                                                                                                                                                                                 |
+| `… .destroy is not a function`                                                                                | an ngrx `rxMethod` replaced with a bare mock                                                                                                                                                                                                                               | `Object.assign(vi.fn(), { destroy: vi.fn() })`                                                                                                                                                                                                                                                            |
+| `NullInjectorError` for a service you did provide                                                             | it is a component-level provider, not a module one                                                                                                                                                                                                                         | `asSpy(fixture.debugElement.injector.get(X))`, not `injectSpy(X)`                                                                                                                                                                                                                                         |
+| `runEffect(): … not an EffectRef returned by effect()`                                                        | passed the callback, a signal, or an unassigned field                                                                                                                                                                                                                      | pass what `effect()` returned; a field may need its lifecycle hook to run first                                                                                                                                                                                                                           |
+| `X is not a constructor`, stack in production code                                                            | a `vi.fn(() => …)` where the code does `new X()`                                                                                                                                                                                                                           | `mockConstructor` / `stubConstructor` / `createSpyClass` (§12)                                                                                                                                                                                                                                            |
+| `Date is not a constructor`                                                                                   | `vi.spyOn(globalThis, 'Date')` — the fakes own it                                                                                                                                                                                                                          | `mockSystemTime(date)` / `vi.setSystemTime`                                                                                                                                                                                                                                                               |
+| `TS2352: … 'accessorSpies' is missing in type 'X'`                                                            | `TestBed.inject(X) as Spy<X>`                                                                                                                                                                                                                                              | `asSpy(TestBed.inject(X))` — never a double assertion (§6)                                                                                                                                                                                                                                                |
+| `TS2739` / `TS2740` / `TS2345` with `Spy<X>` on the left                                                      | a spy handed to an API typed against the class                                                                                                                                                                                                                             | `asInstance(spy)` (§6)                                                                                                                                                                                                                                                                                    |
+| `is missing the following properties: _private, …`                                                            | declared as Vitest's `Mocked<T>`                                                                                                                                                                                                                                           | declare `Spy<T>` (§6)                                                                                                                                                                                                                                                                                     |
+| `AddPromiseSpyMethods<unknown>` vs `WithMockReturnValue<…>`                                                   | a generic class inferred as `Service<any>`                                                                                                                                                                                                                                 | `asSpy<Service>(…)` / `injectSpy<Service>(…)` (§6)                                                                                                                                                                                                                                                        |
+| `'addEventListener' called on an object that is not a valid instance of EventTarget`                          | Node's `AbortSignal` under jsdom + zone.js                                                                                                                                                                                                                                 | `stubAbortController()` (§12)                                                                                                                                                                                                                                                                             |
+| `vi.requireMock is not a function`                                                                            | a mechanical `jest.` → `vi.` rename                                                                                                                                                                                                                                        | there is no equivalent — provide the double through the TestBed instead                                                                                                                                                                                                                                   |
+| a `vi.mock()` factory that never applies, only sometimes                                                      | under `isolate: false` the module was already in the worker's graph                                                                                                                                                                                                        | do not mock it; inject the dependency, or `vi.hoisted()` + a real seam                                                                                                                                                                                                                                    |
+| a `vi.mock()` of a workspace alias that never applies at all                                                  | a bundler inlined the module before the mock could be installed                                                                                                                                                                                                            | `assertMocked(ns, { specifier })` to prove it, then inject instead of mocking                                                                                                                                                                                                                             |
+| `No "default" export is defined on the mock`, thrown inside a dependency                                      | a factory returning bare named exports; the dep probes `default`                                                                                                                                                                                                           | `vi.mock('x', () => moduleNamespace({ … }))`                                                                                                                                                                                                                                                              |
+| `Not implemented: HTMLMediaElement.play`, or `duration` is `NaN` and cannot be set                            | jsdom implements the media elements as a shell                                                                                                                                                                                                                             | `stubMediaElement({ duration })`, then `media.set(el, …)` to fire the events                                                                                                                                                                                                                              |
+| `Cannot set base providers because it has already been called`                                                | zone and zoneless spec files sharing one worker                                                                                                                                                                                                                            | `setupAngularTestEnv({ zoneless, initZone, initZoneless })` (§13)                                                                                                                                                                                                                                         |
+| a stub that works in the first test of the file and in no other                                               | installed at `describe` level or in `beforeAll`, then restored away                                                                                                                                                                                                        | install it in `beforeEach`, or `installPerTest(() => stub…())`                                                                                                                                                                                                                                            |
+| a third-party library failing every other run, no test named                                                  | a test sealed a global with `Object.defineProperty` (non-configurable)                                                                                                                                                                                                     | `setupAutoSpy({ guardGlobals: 'throw' })` names the file; then `mockValueProp`                                                                                                                                                                                                                            |
+| a block of files reported as failed suites with no stack, and zero failing tests                              | a test left an own enumerable key on `Object.prototype`; `mergeHooks` spreads it and collection dies                                                                                                                                                                       | `setupAutoSpy()` guards it by default; `prototypePollution` tunes the reaction                                                                                                                                                                                                                            |
+| `expected [ { at: 1, …(5) }, …(8) ] to deeply equal [ { …(6) }, … ]`                                          | one field moved in every element — usually a frozen clock or an id                                                                                                                                                                                                         | `expect(diffByField(actual, expected)).toBeUndefined()`                                                                                                                                                                                                                                                   |
+| a hand-tuned number of turns waiting for a `resource()` to load                                               | a resource needs a change-detection **tick**, not event-loop turns; `flushEventLoopUntil` never ticks and the resource never even issues its request                                                                                                                       | `flushEffects()`, flush the request, then `await settleResource(r, { label })`                                                                                                                                                                                                                            |
+| a `resource()` assertion that passes but reads the **default** value                                          | the spec asserted before the resource left `loading`                                                                                                                                                                                                                       | `await settleResource(r, { label })` — it fails loudly instead                                                                                                                                                                                                                                            |
+| a spec dying on the runner's 5 s file timeout right after `await stable(fixture)`                             | the fixture never stabilised — an unflushed request, a real `setInterval`                                                                                                                                                                                                  | `stable` now fails at 2000 ms naming the cause; raise `{ timeout }` only once neither is true                                                                                                                                                                                                             |
+| `flushEventLoopUntil` timing out on the **first** such test only, the rest green                              | a cold dynamic `import()` outran the turn budget; later tests hit the module cache                                                                                                                                                                                         | `await settleDynamicImport(() => import('…'))` — await the module, do not count turns                                                                                                                                                                                                                     |
+| `Expected to be running in 'ProxyZone', but it was not found`                                                 | `zone.js/testing` patches jasmine/mocha/jest, not Vitest                                                                                                                                                                                                                   | `import 'vitest-auto-spy/zone'` after zone.js, with `globals: true` (§14)                                                                                                                                                                                                                                 |
+| `nextWith` demanding `HttpEvent<T>` on a generated API client                                                 | `Parameters`/`ReturnType` read the **last** overload                                                                                                                                                                                                                       | `asSpy<Client, { overload: 'first' }>(…)`, or `Overload<M, 0>`                                                                                                                                                                                                                                            |
+| `NG0303` / `NG0304` / nothing at all, from a directive spec                                                   | the host is `standalone: false`, or the module is in the TestBed                                                                                                                                                                                                           | `createDirectiveHost({ template, scope: [Module] })` (§13)                                                                                                                                                                                                                                                |
+| `TS2540: Cannot assign to 'X' because it is a read-only property`                                             | a `readonly` field of an object under test                                                                                                                                                                                                                                 | `mockValueProp(obj, 'X', value)` — on a class **getter**, `mockReadonlyProp`                                                                                                                                                                                                                              |
+| `TypeError: Cannot read properties of undefined (reading 'mockReturnValue')`                                  | the member is an **instance field**, not on the prototype — `Router.currentNavigation` since Angular 20                                                                                                                                                                    | `provideAutoSpy(Router, { instanceMethodsToSpyOn: ['currentNavigation'] })` (§5)                                                                                                                                                                                                                          |
+| `throwWith` reaching the success branch first, with the previous test's value                                 | the spy's `ReplaySubject(1)` outlived the test that filled it                                                                                                                                                                                                              | upgrade; and `resetAutoSpy(spy)` in `beforeEach` when the TestBed is built in `beforeAll`                                                                                                                                                                                                                 |
+| `TS2540` on a `Spy<T>` / `createAutoMock` member, which the runtime writes fine                               | `Spy<T>` is homomorphic and keeps the `readonly` of the source member — deliberately: on a member replaced by a **spied accessor** the assignment reaches the setter spy and the getter still answers `undefined`, so the type error is the loud version of a silent no-op | `mockValueProp(spy, 'X', value)` — it defines rather than assigns, so it works in both cases; `Mutable<Spy<T>>` is the opt-in for plain data members, and `Reflect.set` is **not** a way round it                                                                                                         |
+| `TS2345` from `mockReturnValue` / `mockImplementation` / `mockResolvedValue` on a double that used to compile | the mock surface is `MockInstance<Method>`, so the stub is now checked against the method's own return type                                                                                                                                                                | stub with what the method returns; if the double is meant to answer something else, the method's type or the spec's expectation is wrong                                                                                                                                                                  |
+| `delete mock.optionalMethod` leaving the member present and truthy                                            | the Proxy had no `deleteProperty` trap before 3.5.0                                                                                                                                                                                                                        | upgrade; before that, `mock.optionalMethod = undefined`                                                                                                                                                                                                                                                   |
+| half a double's methods reaching the real implementation after `Object.assign`                                | `ownKeys` on a type-driven Proxy lists only the keys already read                                                                                                                                                                                                          | `createSpyFromClass(X)` — a real object, with enumerable method keys                                                                                                                                                                                                                                      |
+| `let s: MockInstance<() => unknown>` not matching anything                                                    | `MockInstance<F>` is invariant in `F`; Jest's `SpyInstance` was not                                                                                                                                                                                                        | `MockInstance<T['method']>`, or better `injectSpy(X).method`                                                                                                                                                                                                                                              |
+| two runs with the same totals, one of them missing a suite                                                    | a lost `describe` and a fixed flake cancel out in the counters                                                                                                                                                                                                             | `compareTestRuns(before, after)` — compare the set of names, not the numbers                                                                                                                                                                                                                              |
+| a 30 s timeout, in a different file each run                                                                  | module-level `vi.fn()` in a fixture shared by files                                                                                                                                                                                                                        | make the fixture a factory (§10)                                                                                                                                                                                                                                                                          |
+| a component's `afterNextRender` state is empty                                                                | `detectChanges()` does not run the after-render phase                                                                                                                                                                                                                      | `await stable(fixture)` (§11)                                                                                                                                                                                                                                                                             |
+| a green test whose only line about a call is `spy.m.calledWith(1);`                                           | that is a **stub**, not an assertion — chai's `expect(fn).to.have.been.calledWith(x)` is the one that checks                                                                                                                                                               | continue the chain, or `expect(spy.m).toHaveBeenCalledWith(1)` — `no-bare-called-with` (§16)                                                                                                                                                                                                              |
+| `--detect-async-leaks` reporting no leaks in a suite that visibly leaks timers                                | `setupAutoSpy({ strayTimers: true })` cancelled them before Vitest collected                                                                                                                                                                                               | re-run that file with `strayTimers` off; the warning on stderr says how many were taken (§10)                                                                                                                                                                                                             |
+| `createNestUnit(X): parameter #n of Y is typed as \`Object\``(or`undefined — usually a circular import`)      | the compiler emitted no runtime class for that parameter — interface, union, primitive, or a circular import                                                                                                                                                               | `@Inject(TOKEN)` plus a `providers` entry, or `@Optional()` to receive `undefined`; `@Inject(forwardRef(() => X))` for the import cycle                                                                                                                                                                   |
+| `createNestUnit(X): Y declares n constructor parameter(s) but carries no design:paramtypes metadata`          | no `emitDecoratorMetadata` (esbuild / Vite), or `reflect-metadata` loaded after the class                                                                                                                                                                                  | tsc or SWC with `decoratorMetadata`, `@Injectable()`, `reflect-metadata` first; or `@Inject(X)` on every parameter                                                                                                                                                                                        |
+| `createNestUnit(X): A -> B -> A is a cycle among the classes built for real`                                  | two exposed / `useClass` classes depend on each other; the helper does not resolve `forwardRef` cycles                                                                                                                                                                     | expose one side less, or provide it                                                                                                                                                                                                                                                                       |
+| `createNestUnit(X).spies.get(Y): the unit never asked for that token`                                         | same guard as `createWithAutoSpies` — the spy would not be the one the unit uses                                                                                                                                                                                           | stub the token the unit actually injects (the message lists the auto-spied ones)                                                                                                                                                                                                                          |
+| `createNestUnit(X).spies.get(Y): Y is in \`expose\`, so the unit got a real instance`                         | an exposed class is real, not a spy                                                                                                                                                                                                                                        | read the spies of its own collaborators, or drop it from `expose`                                                                                                                                                                                                                                         |
+| `no request matched …` (with the requests that were made listed)                                              | the URL, verb or predicate does not describe anything the code under test sent, or nothing subscribed                                                                                                                                                                      | read the list in the message — it is the requests that were actually made; then fix the URL, add `{ method }`, or subscribe (§13)                                                                                                                                                                         |
+| `this TestBed has no HttpTestingController`                                                                   | `expectRequest` / `expectNoRequest` on a module that never got the testing backend                                                                                                                                                                                         | `TestBed.configureTestingModule({ providers: [...provideHttpTesting()] })` from `vitest-auto-spy/angular-http` (§13)                                                                                                                                                                                      |
+| `the test ended with N unanswered request(s)`                                                                 | `provideHttpTesting({ verifyOnTeardown })` found a request the spec never flushed                                                                                                                                                                                          | answer it (`await expectRequest(url).flush(body)`), assert its absence (`expectNoRequest(url)`), or `{ verifyOnTeardown: false }` (§13)                                                                                                                                                                   |
 
 **Seven of these are library defects, not spec ones.** On anything below 3.8.0, upgrade and change
 nothing in the spec: `of(double)` never emitting; `accessorSpies.setters.X` still `undefined` after
@@ -2872,6 +2942,17 @@ re-exporting a whole directory). When `environment` + `setup` + `prepare` togeth
 of that trade rather than restating them — read that page before recommending the flag, since it
 raises peak memory.
 
+Two more findings are about settings rather than files. `perf-environment-engine` fires when
+`environment` dominates and a `vite(st).config.*` names `jsdom` while nothing in those configs
+mentions `happy-dom`: measured on this package's own 117-file Angular suite, `happy-dom` is 23.2 s of
+user CPU against jsdom's 26.5 s, and on a spec that builds a DOM and does nothing else the gap is
+253 ms against 119 ms per file. It is a swap, not a flag — `happy-dom` implements less of the
+platform — so take one project at a time. `perf-workers` fires on a run over a minute of summed CPU
+that declares no `maxWorkers`, and it is the one finding here about **memory**: one worker per core
+is the default, resident memory measured at 1.42 GB plus ~155 MB per worker, and a cap of four costs
+about 2.8 % of wall clock. Do not quote a worker count as universally right — it is a property of
+the machine.
+
 `--json <path>` re-analyses a report an earlier `--out <path>` run wrote, instead of running Vitest
 again. Full reference: <https://asdalexey.github.io/vitest-auto-spy/utilities/cli>.
 
@@ -2896,7 +2977,7 @@ migrated by hand. Run it after `--write`, and again after any manual clean-up. `
 select transforms by id, `--list` prints them. Full reference:
 <https://asdalexey.github.io/vitest-auto-spy/utilities/codemod>.
 
-Past 50 000 files the repository scan truncates and the run says so — *Nothing left to migrate* off a
+Past 50 000 files the repository scan truncates and the run says so — _Nothing left to migrate_ off a
 truncated list is a claim about a tree the tool never looked at. `VITEST_AUTO_SPY_SCAN_CAP` raises
 the cap.