vitest-auto-spy 3.13.1 → 3.15.0

package/AGENTS.md

@@ -49,14 +49,19 @@ adapter installed and spies fail at runtime.
 | Vue / Pinia          | `vitest-auto-spy/vue`         |
 | Svelte               | `vitest-auto-spy/svelte`      |
 
-Four add-ons, orthogonal to the runner:
+Five add-ons, orthogonal to the runner:
 
-| Add-on           | Import                          | Needed for                                          |
-| ---------------- | ------------------------------- | --------------------------------------------------- |
-| Observable spies | `import 'vitest-auto-spy/rxjs'` | `nextWith` & friends. **Side-effect import, once.** |
-| Console spies    | `vitest-auto-spy/console`       | silent typed spies over the global `console`        |
-| Setup helpers    | `vitest-auto-spy/setup`         | `setupAutoSpy()`, `setupFakeTimers()`               |
-| Zone patch       | `import 'vitest-auto-spy/zone'` | `fakeAsync` / `waitForAsync` on Vitest (§14)        |
+| Add-on            | Import                          | Needed for                                                                                                |
+| ----------------- | ------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| Observable spies  | `import 'vitest-auto-spy/rxjs'` | `nextWith` & friends. **Side-effect import, once.**                                                       |
+| observer-spy shim | `vitest-auto-spy/observer-spy`  | `subscribeSpyTo` — the `@hirez_io/observer-spy` surface (§20). Its own entry so `/rxjs` does not carry it |
+| Console spies     | `vitest-auto-spy/console`       | silent typed spies over the global `console`                                                              |
+| Setup helpers     | `vitest-auto-spy/setup`         | `setupAutoSpy()`, `setupFakeTimers()`                                                                     |
+| Zone patch        | `import 'vitest-auto-spy/zone'` | `fakeAsync` / `waitForAsync` on Vitest (§14)                                                              |
+| jasmine compat    | `vitest-auto-spy/jasmine`       | `.and` / `.calls` / `.withArgs`, the `jasmine` namespace (§20)                                            |
+
+`vitest-auto-spy/jasmine` is Vitest-only, because it registers the Vitest adapter. On `bun test` and
+`node --test` call `enableJasmineCompat()` from `vitest-auto-spy/jasmine-compat` instead.
 
 The package is **ESM**. Only `vitest-auto-spy/node` and `vitest-auto-spy/eslint-plugin` also ship a
 CommonJS build; every other subpath is ESM-only (a `require()` of a Vitest-backed entry always threw —
@@ -344,7 +349,7 @@ Every spied method is a real runner mock, so `mockReturnValue`, `mockImplementat
 
 | Return type     | Helpers added                                                                                                                               |
 | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| anything        | `calledWith(...args)` → `.mockReturnValue(v)` / `.returnValue(v)`, `mustBeCalledWith(...args)` → same                                       |
+| anything        | `calledWith(...args)` → `.mockReturnValue(v)` / `.returnValue(v)` / `.failWith(err)`, `mustBeCalledWith(...args)` → same, `failWith(err)`   |
 | `Promise<T>`    | `resolveWith(v)`, `rejectWith(v)`, `resolveWithPerCall([{ value }, …])`                                                                     |
 | `Observable<T>` | `nextWith(v)`, `nextOneTimeWith(v)`, `nextWithValues(configs)`, `nextWithPerCall(configs)`, `throwWith(v)`, `complete()`, `returnSubject()` |
 
@@ -374,8 +379,24 @@ feed.items$.nextWithValues([{ value: a }, { value: b, delay: 100 }, { complete:
 const [first$, second$] = feed.watch$.nextWithPerCall([{ value: 'a' }, { value: 'b', doNotComplete: true }]);
 feed.items$.throwWith('FAKE ERROR');
 const subject = feed.items$.returnSubject(); // ReplaySubject, for anything the helpers miss
+
+// throwing — `failWith`, on a spy of any return type
+cart.checkout.failWith(new HttpErrorResponse({ status: 500 })); // every call throws
+cart.checkout.calledWith(BAD_ID).failWith(new Error('unknown cart')); // only these arguments throw
 ```
 
+`failWith` is the sync counterpart of `rejectWith`, and it is **not** called `throwWith` — that name
+belongs to the observable helper above, which errors the stream. At runtime every spy carries every
+bundle; only the return type in `Spy<T>` tells them apart, so one name for both would mean whichever
+is attached last silently wins.
+
+On Vitest, `mockThrow` / `mockThrowOnce` (4.1) do the spy-level half of this too. `failWith` exists
+because Bun and `node:test` ship neither, and because **no** runtime can make one `calledWith` chain
+throw while its siblings answer normally — `mockImplementation` replaces the whole dispatch, which is
+the opposite of configuring one set of arguments. A `failWith` supersedes a `resolveWith` /
+`nextWith` / per-call batch configured before it, and is superseded by one configured after, so the
+outcome never depends on the order the spec happens to be written in.
+
 An exact argument list is matched before the asymmetric configs, and those are tried in
 registration order — a narrow config written first keeps its calls. Two matchers count as the same
 argument when they accept the same values (same matcher class, sample and inversion), which is what
@@ -917,7 +938,21 @@ setupAutoSpy({ strayTimers: true }); // wrap the schedulers, sweep the survivors
 The pieces are exported too — `trackStrayTimers()` (idempotent, returns the undo),
 `cancelStrayTimers()` (returns how many it cancelled) and `countStrayTimers()`, all from
 `vitest-auto-spy/setup`. Use `expect(countStrayTimers()).toBe(0)` in an `afterEach` to make a leak
-fail rather than be tidied away.
+fail rather than be tidied away, or take the per-file count from the sweep itself:
+
+```ts
+setupAutoSpy({ strayTimers: true, onStrayTimers: ({ cancelled }) => expect(cancelled).toBe(0) });
+```
+
+**With Vitest 4.1's `--detect-async-leaks`, run one or the other — not both silently.** The two
+arrive at the same timer from opposite ends and the quiet one wins: the sweep cancels in `afterAll`,
+Vitest collects its leaks afterwards, and a cancelled timeout is no longer referenced, so the run
+reports **no leaks** for a file that leaks. Cancelling is still the right default — a callback firing
+during a later file is the more expensive failure — so when both are on and no `onStrayTimers` is
+given, the sweep prints one line to stderr saying how many it took away. To see _where_ each one was
+scheduled, re-run that file with `strayTimers` off and read Vitest's report; the code frame points
+at the `setTimeout` in the spec, because the library's own scheduler wrappers go through
+`vi.defineHelper` and are dropped from the stack.
 
 **The one that keeps a suite green while it is wrong:** zone.js replaces the global `Promise`, and a
 rejection nobody handled is drained into `console.error` and no further — it never reaches
@@ -939,6 +974,12 @@ undo), `flushStrayRejections()` (takes what was captured and starts again from e
 `countStrayRejections()`. The `no-floating-assertion` lint rule catches the commonest shape before
 it ever runs (§16).
 
+**`onUnhandledError` is not this.** Vitest 4.0 added a config callback for errors the _runner_ hears
+about, and under zone.js the runner never hears about these at all — zone.js drains the rejection
+into `console.error` before `process.on('unhandledRejection')` would fire, so there is nothing for
+that callback to filter. Use `onUnhandledError` to triage the native failures Vitest already reports;
+use `strayRejections` to find the ones it never sees.
+
 A rejection the runner has **already** blamed the finished test for is not reported again. An
 `async` test that fails an assertion leaves its own `AssertionError` in both places, so a red run
 used to print two messages per failure and the second one sent the reader hunting for a defect that
@@ -970,7 +1011,7 @@ export const navigation = { setFocus: keepMockRegistered(vi.fn()) };
 The mocks it keeps, it also guards. Staying registered means `vi.resetAllMocks()` reaches them too —
 it walks the same set and calls `mockReset()`, which puts an implementation back only when it was
 passed to `vi.fn(implementation)`; behaviour chained on with `.mockReturnValue(…)` or
-`.mockReturnThis()` is simply lost. Under `isolate: false` that surfaces in a *different* file later
+`.mockReturnThis()` is simply lost. Under `isolate: false` that surfaces in a _different_ file later
 in the same worker, inside application code, as `Cannot read properties of undefined` against a
 shared double that spec never touched — and `vi.restoreAllMocks()` does not cause it (Vitest 4 walks
 `MOCK_RESTORE` there, which only `vi.spyOn` writes to), so probing with that one comes back green and
@@ -1349,6 +1390,44 @@ const myService = injectSpy(MyService); // Spy<MyService>
 `{ lazySpies: false }` to opt out. The spies never touch `NgZone`, so they work zoneless and with
 zone.js alike.
 
+### The same thing as fixtures — `extendWithAutoSpies` (Vitest 4.1+)
+
+The block above, written once instead of once per dependency, with the types inferred rather than
+declared:
+
+```ts
+import { test as base } from 'vitest';
+import { extendWithAutoSpies } from 'vitest-auto-spy/angular';
+
+const test = extendWithAutoSpies(base, {
+  cart: CartService,
+  api: [ApiService, { returns: { get: of([]) } }],
+  passcode: PASSCODE_TOKEN,
+});
+
+test('checks out', async ({ cart }) => {
+  cart.checkout.resolveWith(true);
+
+  await expect(cart.checkout(1)).resolves.toBe(true);
+});
+```
+
+No `let cart: Spy<CartService>` that is `undefined` between tests, and a test that never destructures
+`api` never builds it. Entries are a class, `[Class, config]` with whatever `provideAutoSpy` takes,
+or an `InjectionToken` (built from the token's own type, like `provideAutoSpyForToken`). Extra
+providers — the component under test, a real service, `provideHttpClient()` — go in the third
+argument and are registered in the same call, ahead of the generated ones, so a token named there
+wins.
+
+**It takes the whole map at once, and that is a `TestBed` constraint rather than a typing one.** The
+composing form — `base.extend('cart', …).extend('api', …)` — cannot work: fixtures resolve
+independently, so `cart` would configure the testing module _and_ inject, which instantiates it, and
+`api` would then reach `configureTestingModule` after instantiation and fail with Angular's own
+"Cannot configure the test module when the test module has already been instantiated". A `beforeEach`
+that configures the module further still composes, because it runs before any fixture resolves and
+repeated `configureTestingModule` calls merge right up until the first injection. A `beforeEach` that
+**injects** does not, and nothing can repair that from here.
+
 The token may be an **abstract class** — `abstract class LocalStorage extends AbstractStorage {}`,
 the shape production provides with `useClass`. Its members are erased before they reach a prototype,
 so there is nothing to discover; the factory notices and returns the `createAutoMock` proxy, which
@@ -1593,7 +1672,7 @@ TypeError: Cannot read properties of undefined (reading 'provide')
 
 Both obvious cures fail: `await import('@scope/lib')` at the top of `beforeEach` is already too late,
 and a static import at the top of the spec does not fix the order this bundler emits. Worse, the spec
-that breaks is one nobody touched — chunk boundaries move with file *contents*, so editing a type
+that breaks is one nobody touched — chunk boundaries move with file _contents_, so editing a type
 next door is enough.
 
 ```ts
@@ -1941,24 +2020,32 @@ import autoSpy from 'vitest-auto-spy/eslint-plugin';
 export default [{ files: ['**/*.spec.ts'], ...autoSpy.configs.recommended }];
 ```
 
-| 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`      | `warn`  | —                 | a hand-rolled `useValue` **or** `useFactory` → `provideAutoSpy(Class)` / `provideAutoSpyForToken(TOKEN)`                                  |
-| `prefer-create-spy-from-class` | `warn`  | —                 | an object literal of 2+ `vi.fn()`s → `createSpyFromClass` (a factory's own seed is exempt)                                                |
-| `prefer-inject-spy`            | `warn`  | 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`            | `warn`  | `--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`                | `warn`  | `--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                                                                                   |
-| `no-floating-assertion`        | `error` | —                 | `expect()` in a `.then()` nobody awaits → `expect(await promise)`                                                                         |
-| `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`    | `warn`  | —                 | `TestBed.inject()` in a hook, in a suite that still calls `override*`                                                                     |
-| `no-import-time-spread`        | `error` | suggest           | `export const x = [...Imported]` at module scope → a `TypeError` while the bundle loads                                                   |
-| `no-unregistered-inject-spy`   | `warn`  | —                 | `injectSpy(X)` for a token this file never registered → the real instance, whose spy helpers exist only for the compiler |
-
-Fourteen rules; two fix on their own, six offer suggestions. `no-mocked-for-spy` only ever touches a
+| 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`         | `warn`  | —                 | a hand-rolled `useValue` **or** `useFactory` → `provideAutoSpy(Class)` / `provideAutoSpyForToken(TOKEN)`                                  |
+| `prefer-create-spy-from-class`    | `warn`  | —                 | an object literal of 2+ `vi.fn()`s → `createSpyFromClass` (a factory's own seed is exempt)                                                |
+| `prefer-inject-spy`               | `warn`  | 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`               | `warn`  | `--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`                   | `warn`  | `--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`       | `warn`  | —                 | `TestBed.inject()` in a hook, in a suite that still calls `override*`                                                                     |
+| `no-import-time-spread`           | `error` | suggest           | `export const x = [...Imported]` at module scope → a `TypeError` while the bundle loads                                                   |
+| `no-unregistered-inject-spy`      | `warn`  | —                 | `injectSpy(X)` for a token this file never registered → the real instance, whose spy helpers exist only for the compiler                  |
+| `jasmine-namespace-without-entry` | `warn`  | —                 | `.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`           | `off`   | `--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                         |
+
+Nineteen rules; three fix on their own, seven offer suggestions. The last four are for a suite
+mid-migration off `jasmine-auto-spies` (§20); `prefer-native-spy-api` is **off** in the recommended
+config because it reports working code — the compatibility layer is what a suite runs on while it is
+being migrated. `no-mocked-for-spy` only ever touches a
 **type position**, where a wrong rewrite is a compile error rather than a test that quietly changed
 meaning — so `--fix` renames the type, adds `import type { Spy } from 'vitest-auto-spy'` and drops
 the orphaned `Mocked` import. Every type position, not only a `let`: a factory's return type, a
@@ -2073,75 +2160,83 @@ 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                                                                         |
-| `requested method(s) not found on the class prototype`                               | typo, or an instance-field callable                                                                                                                  | fix the name, or move it to `instanceMethodsToSpyOn`                                                                             |
-| `was configured with 'mustBeCalledWith'`                                             | the code called the spy with other arguments                                                                                                         | that is the assertion firing — fix the code, or relax to `calledWith`                                                            |
-| `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                                  |
-| `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)                                            |
-| `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, so it keeps the `readonly` of an abstract getter                                                                            | `Mutable<Spy<T>>` for direct assignment, or `mockValueProp` for a patch that is undone                                           |
-| `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)                                                                                                    |
+| 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                                                                          |
+| `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) |
+| `requested method(s) not found on the class prototype`                                       | typo, or an instance-field callable                                                                                                                  | fix the name, or move it to `instanceMethodsToSpyOn`                                                                              |
+| `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                                   |
+| `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)                                             |
+| `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, so it keeps the `readonly` of an abstract getter                                                                            | `Mutable<Spy<T>>` for direct assignment, or `mockValueProp` for a patch that is undone                                            |
+| `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)                                     |
 
 **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
@@ -2225,6 +2320,14 @@ npx tsc --noEmit                      # Spy<T> mistakes are compile errors, not
 npx vitest-auto-spy doctor            # suite-level defects that never fail a run
 ```
 
+**If you are an agent, add `--reporter=agent`** (Vitest 4.1). It is Vitest's own reporter, added for
+exactly this: the same failures, without the passing-test roll call and the repeated banners that
+make a run's output expensive to read and expensive to carry.
+
+```bash
+npx vitest run --reporter=agent path/to/file.spec.ts
+```
+
 Type errors matter here more than usual: most of this library's guarantees are type-level, so a
 suite that runs green but does not type-check is not done.
 
@@ -2274,3 +2377,132 @@ source.replace(from, () => to); // not source.replace(from, to)
 **`node.getStart()` excludes leading comments.** A codemod that replaces a range starting there
 silently eats the `// eslint-disable-next-line` above the node. Use `node.getFullStart()`, or count
 the comments before and after and compare against `HEAD`.
+
+---
+
+## 20. Migrating a suite off `jasmine-auto-spies`
+
+`jasmine-auto-spies` and `jest-auto-spies` are the same library twice — both thin layers over
+`@hirez_io/auto-spies-core`, with identical configuration keys (`methodsToSpyOn`,
+`observablePropsToSpyOn`, `gettersToSpyOn`, `settersToSpyOn`) and identical helper names.
+**Exactly one thing differs**: upstream parks its async helpers behind `.and`, because that is where
+jasmine keeps its own spy strategies.
+
+```ts
+spy.load.and.nextWith(account); // jasmine-auto-spies
+spy.load.nextWith(account); // jest-auto-spies, and this library
+```
+
+**Land it green first, rewrite second.** `vitest-auto-spy/jasmine` puts `.and`, `.calls` and
+`.withArgs` back on every spy, so the import specifier is the only edit needed to get the suite
+running — and the first red run then has one candidate cause instead of two:
+
+```diff
+- import { createSpyFromClass, provideAutoSpy, type Spy } from 'jasmine-auto-spies';
++ import { createSpyFromClass, provideAutoSpy, type Spy } from 'vitest-auto-spy/jasmine';
+```
+
+```bash
+npx vitest-auto-spy codemod --from jasmine            # dry run
+npx vitest-auto-spy codemod --from jasmine --write    # apply, then drop the import
+npx vitest-auto-spy codemod --from jasmine --verify   # match the result, not the diff
+```
+
+`import { jasmine } from 'vitest-auto-spy/jasmine'` restores the whole `jasmine` namespace
+(`objectContaining`, `any`, `createSpyObj`, `clock()`, `addMatchers`, and the eight asymmetric
+matchers Vitest has no twin for) for the specs that never touched auto-spies. Nothing is installed
+on `globalThis` — it is one explicit line per file, which the codemod later deletes.
+
+### The renames, once the suite is green
+
+| jasmine                                    | here                                                       |
+| ------------------------------------------ | ---------------------------------------------------------- |
+| `spy.m.and.returnValue(v)`                 | `spy.m.mockReturnValue(v)`                                 |
+| `spy.m.and.callFake(fn)`                   | `spy.m.mockImplementation(fn)`                             |
+| `spy.m.and.stub()`                         | `spy.m.mockImplementation(() => undefined)`                |
+| `spy.m.and.returnValues(a, b)`             | `.mockReturnValueOnce(a).mockReturnValueOnce(b)`           |
+| `spy.m.and.throwError('boom')`             | `.mockImplementation(() => { throw new Error('boom'); })`  |
+| `spy.m.and.resolveTo(v)`                   | `spy.m.mockResolvedValue(v)`                               |
+| `spy.m.and.nextWith(v)` / `resolveWith(v)` | `spy.m.nextWith(v)` / `spy.m.resolveWith(v)` — drop `.and` |
+| `spy.m.withArgs(a).and.returnValue(v)`     | `spy.m.calledWith(a).mockReturnValue(v)`                   |
+| `spy.m.calls.count()` / `argsFor(i)`       | `spy.m.mock.calls.length` / `spy.m.mock.calls[i]`          |
+| `spy.m.calls.reset()`                      | `spy.m.mockClear()`                                        |
+| `jasmine.createSpy('n')`                   | `vi.fn()` — or `createFunctionSpy<F>('n')`, which is typed |
+| `jasmine.any(X)` / `objectContaining({…})` | `expect.any(X)` / `expect.objectContaining({…})`           |
+| `jasmine.clock().tick(n)`                  | `vi.advanceTimersByTime(n)` — or `await advanceTimers(n)`  |
+| `jasmine.SpyObj<T>` / `jasmine.Spy`        | `Spy<T>` from this package / `Mock` from `vitest`          |
+| `expect(x).toBeTrue()` / `toHaveSize(n)`   | `.toBe(true)` / `.toHaveLength(n)`                         |
+| `expect(spy).toHaveBeenCalledOnceWith(a)`  | `.toHaveBeenCalledExactlyOnceWith(a)`                      |
+| `fail(msg)`                                | `expect.fail(msg)` — there is no `vi.fail`                 |
+
+### Four traps, all of them silent
+
+1. **`spyOn(o, 'm')` inverts.** jasmine's `spyOn` installs a **stub**; `vi.spyOn` **calls through**.
+   A bare rename compiles, passes, and starts running the real implementation inside every spec that
+   installed the spy in order to stop it. Write
+   `vi.spyOn(o, 'm').mockImplementation(() => undefined)` — the codemod appends exactly that, and a
+   file whose only jasmine construct is `spyOn(` is deliberately **not** auto-detected: that suite
+   has to say `--from jasmine` out loud.
+2. **`.withContext('msg')` does not throw — it loses the message.** Vitest's chai layer ships an
+   `@internal` method of that name expecting a _flags object_; handed a string it walks the string's
+   character indices, sets nonsense flags and returns the assertion. The chain runs, the failure
+   reads `AssertionError: expected 2 to be 3`, and the label is gone. Write
+   `expect(actual, 'msg').toBe(expected)`.
+3. **`.calls.saveArgumentsByValue()` is a no-op here.** No runner in this family copies call
+   arguments. The call still runs, nothing fails, and a spec that relied on it silently starts
+   asserting on post-mutation state. Take the copy at call time, inside a `mockImplementation`.
+4. **`.and.callThrough()` means something different.** Upstream had no original to call through to
+   and silently answered `undefined`; here it restores **this library's own dispatch**, so a
+   `calledWith` chain decides the value again. The codemod leaves it byte-for-byte and names the
+   line, because there is no expression it could become.
+
+`jasmine.DEFAULT_TIMEOUT_INTERVAL` is a config setting, not a statement: set **both**
+`testTimeout` (default 5 000 ms) and `hookTimeout` (default 10 000 ms), or
+`vi.setConfig({ testTimeout: n, hookTimeout: n })` per file. Assigning to it on the namespace warns
+once naming both rather than silently swallowing the write.
+
+`it('x', (done) => …)` is **not** rewritten by anything — a callback signature is a control-flow
+shape, not a name. Use `async` + `await`; `no-done-callback` reports both the parameter and any
+`done.fail(…)`.
+
+On Bun and `node:test` the entry cannot be imported (it registers the Vitest adapter, which means
+importing `vitest`). Call `enableJasmineCompat()` from `vitest-auto-spy/jasmine-compat` once, in a
+setup file — spies built **before** the call do not get the namespaces. Observables still come from
+`vitest-auto-spy/rxjs`. A project that never imports the entry pays one `undefined` check per spy
+and ships none of the code.
+
+### `@hirez_io/observer-spy` comes with it
+
+That package sits beside `jasmine-auto-spies` in almost every suite that has one, and is the larger
+of the two by an order of magnitude. `vitest-auto-spy/rxjs` exports the same surface —
+`subscribeSpyTo(source$, config?)`, `SubscriberSpy<T>`, `ObserverSpy<T>`, `ObserverSpyConfig` — so a
+migration does not have to rewrite every stream assertion in the same commit:
+
+```ts
+import { subscribeSpyTo } from 'vitest-auto-spy/observer-spy';
+
+const spy = subscribeSpyTo(service.load());
+
+expect(spy.getValues()).toEqual(['a', 'b']);
+expect(spy.receivedComplete()).toBe(true);
+```
+
+Four departures from upstream, each closing a defect: `getValues()` returns a **copy** (upstream
+hands back its live array) and is typed `T[]` (upstream: `any[]`); `getFirstValue()` /
+`getValueAt(i)` **throw** on an empty spy rather than returning `undefined` from a `T` signature;
+and an **unexpected** error is thrown by the value readers, carrying the original as `cause`, rather
+than rethrown out of the observer — under rxjs 7 that rethrow goes through `reportUnhandledError`
+and never reaches the subscribing line. `{ expectErrors: true }` keeps the readers open, as upstream.
+
+`autoUnsubscribe()`, `queueForAutoUnsubscribe()` and `fakeTime()` are **not implemented**. Use
+`using spy = subscribeSpyTo(source$)` — `SubscriberSpy` is disposable — and `setupFakeTimers()` with
+`await advanceTimers(ms)`, or rxjs's `TestScheduler` directly.
+
+**It is a bridge, and the destination differs in kind.** observer-spy is synchronous inspection:
+subscribe, let things happen, then read. A stream that never emits leaves a spy with no values, so a
+spec reading `getValues()` gets `[]`, asserts about it, and passes having observed nothing. §8's
+`expectEmission` / `expectEmissions` invert that — the assertion _is_ the await, and silence is a
+failure with a watchdog. Land the suite green on `subscribeSpyTo`, then move the assertions over.
+
+Full mapping, including what upstream cannot do at all:
+<https://asdalexey.github.io/vitest-auto-spy/migrating-jasmine>.