vitest-auto-spy 3.4.0 → 3.6.0

package/AGENTS.md

@@ -12,6 +12,12 @@ node_modules/vitest-auto-spy/AGENTS.md
 
 Working on the library's own source instead? Read `CONTRIBUTING.md` in the repository.
 
+Setting this up for a team? The README section
+[Using this library with an AI agent](https://github.com/ASDAlexey/vitest-auto-spy#using-this-library-with-an-ai-agent)
+names the instruction file each agent reads — `AGENTS.md` for OpenAI Codex, Cursor, Copilot and most
+of the field, `CLAUDE.md` for Claude Code and for GLM (z.ai) or Kimi running inside it, `GEMINI.md`
+for Gemini CLI — and gives the two commands that install this pointer for all of them.
+
 | Resource                | Where                                                                |
 | ----------------------- | -------------------------------------------------------------------- |
 | Spec patterns at scale  | <https://asdalexey.github.io/vitest-auto-spy/recipes>                |
@@ -62,24 +68,176 @@ Vitest refuses to be required).
 ```
 Do you have a real class at runtime?
 ├── yes → createSpyFromClass(Class, config?)          → Spy<T>
+│         (an `abstract class` DI token counts — see below)
 └── no  → Is the double CALLED by the code under test?
-         ├── yes, and calls go one level deep → createAutoMock<T>(overrides?)  → Spy<T>
-         ├── yes, and calls chain (a.b.c())    → mockDeep<T>(overrides?)       → DeepMockProxy<T>
+         ├── yes, and it is INJECTED (DI, a field)  → createAutoMock<T>(overrides?)  → Spy<T>
+         ├── yes, and it is an ARGUMENT of the function under test, asserted on
+         │                                          → autoMocked<T>(overrides?)      → T & Spy<T>
+         ├── yes, and reads chain (a.b.c())         → mockDeep<T>(overrides?)        → DeepMockProxy<T>
+         ├── yes, and CALLS chain (a.b().c())       → mockDeep<T>({}, { selfReturning: true })
          └── no, it is only READ (DTO, config, route snapshot)
-                                                → createMock<T>(partial?)      → T   (no spies)
+                                                    → createMock<T>(partial?)        → T   (no spies)
 
 One standalone function?          → createFunctionSpy<Fn>('name')
 Code under test does `new Foo()`? → a real class?  createSpyClass(Foo)
                                   → only a shape?  mockConstructor<T>(() => instance)
                                   → on a global?   stubConstructor(globalThis, 'Image', factory)
                                     (a vi.fn() rejects `new` — see §12)
-Passed as an argument, not injected, and asserted on?
-                                  → autoMocked<T>()   (typed `T & Spy<T>`, no asInstance/asSpy)
 ```
 
+`createAutoMock` and `autoMocked` build the same object; they differ only in the type you get back,
+and the question that decides it is **how the double travels**. Through DI, it arrives as `Spy<T>`
+and is only ever asserted on — `createAutoMock`. Handed to the function under test as an argument
+(`detectVpnClient(url, logger)`, `applyPreferredTracks(target, …)`, `setLocalConfigEnabled(storage, …)`),
+it has to satisfy `T` at the call site *and* expose the spy helpers at the assertion, and
+`autoMocked<T>()` is that intersection — otherwise every call site needs an `asInstance()` and the
+noise scales with the number of them.
+
+
 `createMock<T>()` is the one to reach for on data shapes — it returns a plain `T`, so it satisfies a
 `no-type-assertion` lint rule without an `eslint-disable` on every fixture.
 
+**`mockDeep` builds depth on property access, not on calls** — the distinction the tree now spells
+out, and the one that costs an afternoon otherwise. `mock.repo.user.find()` chains because every hop
+but the last is a *read*. A node that is **called** returns what it was configured to return, and by
+default that is `undefined`, so `mockDeep<AppLogger>().channel('app').info('x')` is a `TypeError` at
+the second call — while `DeepMockProxy<AppLogger>` types it perfectly, so nothing warns. Pass
+`{ selfReturning: true }` for a fluent API, or use `createAutoMock<T>()` with
+`channel.mockReturnThis()` when only one method chains:
+
+```ts
+const logger = mockDeep<AppLogger>({}, { selfReturning: true });
+
+logger.channel('app').info('started');
+expect(logger.channel('app').info).toHaveBeenCalledWith('started');
+```
+
+Both bridges exist, and which one you need depends on the direction. What a self-returning **call**
+hands back is typed as the *declared* return type, not as a spy — `asSpy<T>(…)` when the helpers are
+needed. The **whole mock** is a `DeepMockProxy<T>`, which is not assignable to `T` for the same
+reason `Spy<T>` is not (a mapped type cannot see private members) — `asInstance(…)` when it has to
+go somewhere typed against the real thing:
+
+```ts
+const logger = mockDeep<AppLogger>({}, { selfReturning: true });
+
+boot(asInstance(logger)); //           → AppLogger, for the API under test
+asSpy<AppLogger>(logger.channel('app')).info.mockReturnValue(undefined); // → the helpers
+```
+
+`asInstance` did not take a deep mock before 3.5.0, which left it with nowhere to go: this tree
+sends you to `mockDeep` when the calls chain, and the result then fitted nothing that expected `T`.
+
+**An `abstract class` is a class.** `abstract class LocalStorage extends AbstractStorage {}`,
+provided in production as `{ provide: LocalStorage, useClass: BrowserLocalStorage }`, is the
+standard Angular DI-token idiom, and `provideAutoSpy(LocalStorage)` / `createSpyFromClass(LocalStorage)`
+take it — type and runtime both. Abstract members are erased before they reach a prototype, so there
+is nothing to read there; when discovery comes back empty the factory hands back the `createAutoMock`
+proxy instead of an empty object, and every method answers. Nothing to configure, and no reason to
+reach for `{ provide: X, useValue: createAutoMock<X>() }` by hand any more.
+
+That holds while the class is **fully** abstract. One concrete member — a helper, a getter — and
+discovery is no longer empty, the fallback does not fire, and every `abstract` member is missing
+while `Spy<T>` types it as present: the read is `undefined` and the call dies as
+`… is not a function` in production code. Pass `{ fillMissing: true }` there
+(`provideAutoSpy(LocalStorage, { fillMissing: true })`), which answers a name the prototype never
+carried with a spy. It is opt-in because `abstract` is erased at runtime — filling every unknown key
+by default would silence a real typo on every concrete class.
+
+**`overrides: { key: undefined }` is a seed, not an omission**, and the difference is load-bearing.
+`createAutoMock` reads its seed with `Reflect.ownKeys`, so a key written out with an explicit
+`undefined` **is** in the store: reading it answers `undefined`. Leave it out and the same read
+materialises a *function spy* — which is truthy, and sends `if (this.lastFocus)` down the branch the
+spec was trying to close:
+
+```ts
+createAutoMock<NavigationService>({ currentFocus: undefined, navRoot: undefined, selectors: 'button, a' });
+//                                  ^ "this member is data, and there is none" — not the same as omitting it
+```
+
+This is the way to say "the member exists and is empty", and it is worth writing even when it looks
+redundant.
+
+### What a Proxy-backed double cannot do
+
+`createAutoMock` and `mockDeep` build a Proxy, not an object, and there is one place where the
+difference shows: a Proxy answers only the operations its handler traps. Three of them used to be
+missing, and each produced a *silent* wrong answer rather than an error — the worst failure mode
+this library can have, because a checking test becomes a non-checking one and only the proxy's
+source says so. Two are fixed; the third cannot be:
+
+| Operation                            | Before 3.5.0                                     | Now                                                          |
+| ------------------------------------ | ------------------------------------------------ | ------------------------------------------------------------ |
+| `mockValueProp` & the other three     | patch landed on the target; the double ignored it | works, and `restoreMockedProps()` undoes it                  |
+| `delete mock.optionalMethod`          | deleted nothing; the next read remade the spy     | the member is absent, until something writes to it again     |
+| `Object.assign(real, mock)`           | copies only the keys already **read**             | still does — see below                                       |
+
+`ownKeys` cannot be completed: a type has no key list at runtime, which is the whole premise of
+these two factories. So a spec that installs a double by **copying it onto a real instance** —
+`Object.assign(player, engineDouble)` — gets whichever members happened to be touched first, and
+every other call goes to the real implementation, silently. Use `createSpyFromClass` there: it
+returns an ordinary object whose method keys are enumerable (lazy accessors, but enumerable), so
+the copy is complete.
+
+### It answers everything, so it must not answer *these*
+
+The same premise cuts the other way. A library that is handed an object and has to decide **what
+kind of thing it is** asks by probing a key — and a double that answers every property answers the
+probe too, at which point it stops being a double of `T` and becomes whatever was being looked for.
+Four names are therefore answered with `undefined` unless the spec seeds them, alongside `then` and
+every symbol, which always were:
+
+| Key            | Probed by                                     | The double became   |
+| -------------- | --------------------------------------------- | ------------------- |
+| `schedule`     | `popScheduler` in `of` / `from` / `merge` / … | a scheduler         |
+| `lift`         | `isObservable`, with `subscribe`              | an Observable       |
+| `@@observable` | `isInteropObservable` in `innerFrom`          | an interop stream   |
+| `getReader`    | `isReadableStreamLike` in `innerFrom`         | a ReadableStream    |
+
+The one that cost an afternoon reads like nothing at all:
+
+```ts
+of(autoMocked<AnimationItem>()); // an Observable that never emits
+```
+
+`of(...)` takes its **last argument** for a scheduler when `typeof x.schedule === 'function'`, so
+the whole double was eaten as one, `of()` was left with an empty argument list, and the emission was
+scheduled onto a spy that does nothing. The component under test kept its `null`, and what failed
+was an assertion about an unrelated `emit()` three concerns away — nothing in the failure mentions
+`of`. The workaround people find is `from([double])`; it is not needed any more.
+
+**`subscribe` is deliberately not on that list.** It is an ordinary method name — a store, an
+Angular `OutputEmitterRef`, an event bus — and `expect(store.subscribe).toHaveBeenCalledWith(cb)` is
+a real assertion. Denying `lift` and `@@observable` already breaks the impersonation, so `subscribe`
+on its own fools nothing: `from(double)` now fails with rxjs's own *"You provided an invalid object
+where a stream was expected"*, loudly and in the right file.
+
+If your type genuinely has one of the four, say so once and it comes back — the list is consulted
+after the seed store:
+
+```ts
+createAutoMock<TaskScheduler>({ schedule: vi.fn() });
+```
+
+That is the trade the deny-list makes: without a seed the member is absent and the failure is an
+immediate `TypeError: … is not a function` at the call site, instead of a silent one in another
+file. A key is only added to that list with an observed mechanic behind it — never because the name
+sounds protocol-ish — because every entry costs somebody the ability to mock a member of that name
+without seeding it.
+
+The tree asks whether the double is *called*, and there is a second question worth asking: whether
+the code under test **writes to it**. `createAutoMock` is a proxy with a `set` trap over the same
+cache its `get` trap answers from, so an assignment sticks and is read back — which makes it the
+double for a DOM-ish object a library drives by assigning handlers, where a hand-written fake is
+otherwise the only option:
+
+```ts
+const xhr = createAutoMock<XhrLike>({ status: 0, timeout: 0, onload: null, onerror: null });
+
+xhr.send.mockImplementation(() => respond(asInstance(xhr)));
+// production does `xhr.onload = () => resolve(xhr.status !== 0)` — the proxy remembers it
+```
+
 ---
 
 ### Cost, so it stops being a question
@@ -211,6 +369,31 @@ const subject = feed.items$.returnSubject(); // ReplaySubject, for anything the
 `mock.settledResults` is native on Vitest and polyfilled on Bun / `node:test`, so it is identical on
 all three. Entries are `{ type: 'fulfilled' | 'incomplete' | 'rejected', value }`.
 
+**The observable helpers are backed by a `ReplaySubject(1)` that belongs to the spy, and it is
+configuration — so it must be reset with the rest of it.** Two failures used to come out of that
+buffer outliving the test that filled it, and both were silent:
+
+```ts
+// test 1
+service.createSeamlessTransition.nextWith(uri); // buffered
+
+// test 2 — the failure path is the point of this test
+service.createSeamlessTransition.throwWith(error); // subscriber gets `uri` FIRST, then the error
+```
+
+The code under test therefore ran the **success** branch on stale data, and the error branch arrived
+one emission late. The second: `error()` and `complete()` close a Subject permanently, so a later
+`nextWith` on that spy pushed into a dead subject and emitted nothing at all. Both are fixed —
+`resetAutoSpy(spy)` now drops the subject, and a terminated one is replaced on the next
+configuration.
+
+What that does **not** change: `vi.clearAllMocks()` and `clearMocks: true` still cannot reach it,
+for the same reason they cannot reach a `calledWith` chain — that state lives in this library's
+closures, not on the runner's mock. So when a spy outlives a test — a TestBed built in `beforeAll`,
+a spy hoisted to `describe` scope — put `resetAutoSpy(spy)` in `beforeEach`. Inside one test the
+sequence `nextWith(a)` then `throwWith(e)` still means "emit a, then fail"; only a reset or a
+terminal call starts a new stream.
+
 ---
 
 ## 5. `createSpyFromClass` configuration
@@ -227,6 +410,8 @@ createSpyFromClass(MyService, {
   settersToSpyOn: ['userName'],
   autoSpyAccessors: true, // discover every accessor on the prototype chain
   lazySpies: true, // build each method spy on first access
+  returns: { getProducts: of([]) }, // what a spied METHOD answers
+  overrides: { products$: subject }, // a member that is not a method result
 });
 ```
 
@@ -245,12 +430,30 @@ the reference suite). Method discovery walks the _prototype chain_; a callable a
 - an Angular `signal()` / `computed()` field — the dominant case in a signals codebase
 - an arrow-function property — `readonly reload = (): void => {}`
 - anything on an ngrx `signalStore()`, which puts **everything** on the instance
+- **members Angular's own classes moved onto the instance** — `Router.currentNavigation` in
+  Angular 20 is `currentNavigation = this.navigationTransitions.currentNavigation.asReadonly()`
 
 ```ts
 createSpyFromClass(TaskStore, { instanceMethodsToSpyOn: ['count', 'reload'] });
 provideAutoSpy(ProjectStore, { instanceMethodsToSpyOn: ['current', 'isEmpty'] });
+provideAutoSpy(Router, { instanceMethodsToSpyOn: ['currentNavigation'] });
+```
+
+**The failure this produces says nothing about any of it.** The member is simply not on the spy, so
+the next line reads `undefined` and configuring it throws:
+
+```
+TypeError: Cannot read properties of undefined (reading 'mockReturnValue')
 ```
 
+There is no better message to be had at runtime, and it is worth saying why rather than leaving it
+looking like an oversight. Instance fields do not exist until a constructor has run, and this
+library never constructs the class — that is what makes a spy safe to build from a service whose
+constructor talks to the network. The only alternative would be to answer an unknown member with
+*something*, and that something would be truthy: `if (service.optionalThing)` in the code under test
+would then take the wrong branch, silently, which is the exact failure mode the protocol deny-list
+in §2 exists to remove. A loud `TypeError` on the spec's own line is the better of the two.
+
 For an ngrx `signalStore()`, prefer `createAutoMock<T>()` over listing every member: it mocks from
 the type, needs no prototype, and the list cannot fall behind the store.
 
@@ -267,8 +470,31 @@ Also true, and worth not re-deriving:
 
 - **Inherited methods are spied** — discovery walks the whole chain (`Object.prototype` excluded).
 - **Constructor bodies never run.** The spy is assembled from the prototype.
-- **Abstract classes work at runtime** but TypeScript refuses them as `ClassType<T>`. Pass a
-  concrete subclass and keep the abstract class as the DI token.
+- **Abstract classes are accepted**, type and runtime both — `ClassType<T>` carries an abstract
+  construct signature, and when the prototype turns out to be empty (abstract members are erased
+  before emit) the factory hands back the `createAutoMock` proxy instead of an empty object. Do
+  **not** pass a concrete subclass instead; this file used to say so, and it was wrong twice over.
+- **An overloaded method is not collapsed.** The worry that `Spy<T>` types every generated
+  `api-mgw` client against its last signature does not hold: a four-overload
+  `MgwContentsService.getMoviesBySlug` types as it should, and hand-written `{ m: vi.fn() }` doubles
+  for those services convert with no changes to the assertions. When the *first* signature is the
+  useful one, name it on the **declaration only** — the factory's result assigns to it, so the type
+  argument is not written twice:
+
+  ```ts
+  let mapping: Spy<MgwMappingService, { overload: 'first' }>;
+
+  mapping = createSpyFromClass(MgwMappingService); // no second type argument here
+  ```
+
+**A getter that returns a `Signal<T>` goes in `instanceMethodsToSpyOn`**, not in `gettersToSpyOn`.
+`get isKidMode(): Signal<boolean> { return this._isKidMode.asReadonly(); }` is read as a property
+and called as a function, and the accessor route makes you write
+`accessorSpies.getters.isKidMode.mockReturnValue(signal(false))` — two levels deeper than the value
+in question. Naming it as an instance method puts a plain spy at that key (the spy object has no
+class prototype, so nothing is being shadowed), and
+`service.isKidMode.mockReturnValue(false)` reads like every other member. `mockSignalProp` is the
+other answer when the value has to change during the test.
 
 ### Getters and setters live in `accessorSpies`
 
@@ -282,6 +508,25 @@ settings.theme = 'light';
 expect(settings.accessorSpies.setters.theme).toHaveBeenCalledWith('light');
 ```
 
+**Naming one half gets you the pair, when the class declares a pair.** `gettersToSpyOn: ['theme']`
+on a class with both a getter and a setter installs both spies — mirroring reads the prototype
+descriptor, so it only ever adds what the class already has, and a read-only member stays read-only.
+Before 3.5.0 the assignment landed on the no-op setter the scaffolding installs: the write vanished,
+`accessorSpies.setters.theme` was `undefined`, and the failure read
+`Cannot read properties of undefined` three steps from the configuration behind it.
+
+Only spy a getter when the spec asserts that it was **read**. To make one *answer* something, on a
+spy that already exists, the pair above is one line — and it needs no `gettersToSpyOn` at the
+factory, which is the part that is otherwise found by trial:
+
+```ts
+mockReadonlyProp(settings, 'theme', 'dark'); // no gettersToSpyOn, no accessorSpies
+```
+
+For a signal-valued property that is not merely convenience: a spied getter answers `undefined`
+until it is configured, while `mockReadonlyProp(component, 'items', signal([]))` keeps every
+`computed()` and `effect()` downstream of it reactive (§9).
+
 ---
 
 ## 6. `Spy<T>` is not assignable to `T` — this is intentional
@@ -350,16 +595,120 @@ proxies alike. Reach for these instead of looping over methods calling `mockClea
 emits, the callback never runs and nothing is asserted. Invert it — **the assertion is the `await`**:
 
 ```ts
-import { expectEmission, expectEmissions, expectNoEmission } from 'vitest-auto-spy';
+import { expectCompletion, expectEmission, expectEmissions, expectError, expectNoEmission } from 'vitest-auto-spy';
 
-await expect(expectEmission(component.visible$)).resolves.toEqual([task]);
-await expect(expectEmissions(source$, 3)).resolves.toEqual([1, 2, 3]);
+await expect(expectEmission(component.visible$)).resolves.toBe(true); // the first VALUE, not a list
+await expect(expectEmission(tasks$)).resolves.toEqual({ id: 1 }); // the task itself, not `[task]`
+await expect(expectEmissions(source$, 3)).resolves.toEqual([1, 2, 3]); // the list is this one
 await expectNoEmission(source$, { timeout: 50 });
+await expectCompletion(service.purgeCache()); // "it finished" — the value is not the point
+```
+
+Options: `{ timeout, label }`. `timeout` defaults to `1000` ms (`0` for `expectNoEmission`, whose
+wait is a quiet window rather than a watchdog). The source is duck-typed, so rxjs `Observable`s,
+`Subject`s, Angular `toObservable()` results, Angular `output()` (`OutputEmitterRef`, whose
+`subscribe` takes a bare callback) and hand-rolled subscribables all work — and every helper infers
+the emitted type, so `expectEmission(of(1))` is a `Promise<number>`.
+
+`expectCompletion` is the one to reach for on a stream whose value is not the point — a save, a
+purge, an `Observable<void>`, a `Subject` a teardown closes. `firstValueFrom` rejects such a stream
+with rxjs's `EmptyError`, and the workaround people arrive at,
+`lastValueFrom(x, { defaultValue: undefined })`, reads as though the default were the interesting
+part. Emissions do not fail it: it asserts termination, nothing about what came before.
+
+**To assert that production code pushed into a stream, do not use `observablePropsToSpyOn`.** That
+option points the other way: it gives the spec `nextWith` so it can *feed* the double. When the
+question is whether the code under test called `next` on a property, the double needs a real
+`Subject` and a spy on its method:
+
+```ts
+const forceRequery$ = new Subject<number>();
+
+mockValueProp(state, 'forceRequeryAndStartPlaybackAt$', forceRequery$);
+const next = vi.spyOn(forceRequery$, 'next');
+
+service.seek(1000);
+expect(next).toHaveBeenCalledWith(1000);
+```
+
+`Spy<T>` types an Observable property as `AddObservableSpyMethods<O> & T[K]`, so `next` is there on
+the type either way — which is exactly why this is worth saying: the code compiles against the spy
+surface and asserts nothing.
+
+**When the error *is* the assertion, use `expectError`.** The other helpers wrap a stream failure in
+a new `Error` whose message names the stream — right for reporting an unexpected failure, useless
+when the failure is the subject. `expectError` resolves *with* the error, exactly as it was thrown:
+
+```ts
+await expect(expectError(service.load())).resolves.toBe(originalError);
+expect(await expectError(process$)).toBeInstanceOf(UdmsStatusError);
+expect((await expectError(account$)) as Error).toHaveProperty('message', 'websso fail');
+```
+
+It waits for the error however late it arrives, and fails — naming the stream — if the stream
+completes or stays quiet instead. The wrapped failures of the other helpers now also carry the
+original on `cause`, so `rejects.toMatchObject({ cause: original })` works; prefer `expectError`,
+which needs no unwrapping. `firstValueFrom(source$).rejects` remains fine too.
+
+**Which emission counts** — `skip` and `until`, for the stream whose first value is always stale:
+
+```ts
+await expect(expectEmission(isXl$, { skip: 1 })).resolves.toBe(true); // a shareReplay / BehaviorSubject
+await expect(expectEmission(currentParams$, { until: (p) => p.channelId === expected })).resolves.toEqual(…);
+```
+
+Both say in the assertion what `source$.pipe(skip(1))` / `pipe(filter(…))` say in the source, and
+they keep the diagnosis: emissions that do not match are still counted, so a failure reads
+`4 emission(s) received` rather than `0` and tells "the wrong thing fired" apart from "nothing
+fired".
+
+**`advance` closes the window between subscribing and awaiting.** A stream driven by a
+`debounceTime`, a retry or a poll needs the clock moved *after* something is listening, and `await`
+gives control away before the next statement runs:
+
+```ts
+await expect(expectEmission(purchased$, { advance: () => vi.runAllTimers() })).resolves.toBe(false);
 ```
 
-Options: `{ timeout, label }`. `timeout` defaults to `1000` ms (`0` for `expectNoEmission`, and `0`
-disables the watchdog — use it under fake timers). The source is duck-typed, so rxjs `Observable`s,
-`Subject`s, Angular `toObservable()` results and hand-rolled subscribables all work.
+That replaces the fragile shape people arrive at — hold the promise, advance, then await — which
+breaks silently the moment somebody adds an `await` one line above it. It is a callback rather than
+an `advanceTimers: true` flag because these helpers are in the core entry, which contains no test
+runner: only the spec knows whether it is on `vi`, `bun:test` or `node:test`.
+
+**The watchdog runs on real time, on purpose — even under fake timers.** A virtual one would race
+the timers the spec advances: `expectEmission(source$, { timeout: 200 })` followed by
+`vi.advanceTimersByTime(5_000)` would fire at 200 virtual ms and reject the stream the spec was
+about to advance into. The cost is that in a suite with global fake timers a *failing* assertion
+spends a real second. Do **not** answer that with `{ timeout: 0 }` at every call site — that
+disables the watchdog, and the next silent stream hangs to the runner's own timeout with nothing
+useful in the message. Lower the default once instead:
+
+```ts
+// vitest.setup.ts
+import { setEmissionTimeout } from 'vitest-auto-spy';
+import { setupAutoSpy } from 'vitest-auto-spy/setup';
+
+setupAutoSpy({ globalFakeTimers: true });
+setEmissionTimeout(100); // the clock is frozen; a real second buys nothing
+```
+
+**`expectEmission` subscribes when you call it, not when you await it**, and that is load-bearing
+rather than an implementation detail. It is what converts the test whose source has to be poked
+*after* somebody is listening — a router event, a `Subject` the spec pushes into, anything that
+does not replay:
+
+```ts
+const breadcrumbs = expectEmission(service.buildDynamicBreadcrumbs({ root })); // subscribed already
+
+router.events.nextWith(navigationEnd); // …so this emission is not missed
+
+await expect(breadcrumbs).resolves.toEqual([…]);
+```
+
+`firstValueFrom` cannot do this half: it also subscribes eagerly, but there is nowhere to put the
+line that triggers the source, because the `await` is the same statement as the subscription — so
+the test deadlocks against a source that only emits once something pokes it. Hold the promise
+first, poke, then await.
 
 ---
 
@@ -380,6 +729,32 @@ restoreMockedProps(); // put every patch back; each helper also returns its own
 properties. Never use bare `Object.defineProperty` in a spec: nothing restores the original
 descriptor, and under `isolate: false` the patch leaks into the next file.
 
+**They work on `createAutoMock` and `mockDeep` doubles too** — which they did not until 3.5.0.
+Both are Proxies, all four helpers are built on `Object.defineProperty`, and neither Proxy trapped
+it: the patch landed on the Proxy's own target, the `get` trap never looked there, nothing threw,
+and the test carried on reading the old value. If you have seen a spec build a double by hand —
+real getters plus a `createFunctionSpy` per method — this is usually why.
+
+**The second overload is a normal tool, not a last resort.** Each helper has a checked overload
+(`K extends keyof T`) and a `(object, property: PropertyKey, value: unknown)` one behind it, and
+the JSDoc calls the latter an escape hatch for `#private` fields. In practice it carries about half
+of the real calls, all of them legitimate:
+
+```ts
+mockValueProp(router, 'routerState', { snapshot: { url: '/home' } }); // a partial fixture of a fat type
+mockValueProp(window, 'AudioContext', undefined); // "this platform does not ship the API"
+mockValueProp(transitionEvent, 'propertyName', 'opacity'); // a field a synthetic DOM event lacks
+mockValueProp(spy, 'products$', new Subject()); // a member the double does not have at all
+```
+
+The last one is worth knowing on its own: patching a key the object never had **works and is undone
+correctly** — the journal records the *absence* of a descriptor and puts it back by deleting the
+property. That is how you add an Observable member that `provideAutoSpy` did not create because
+`observablePropsToSpyOn` was not passed.
+
+What the second overload costs is the property-name check, so a typo in the name compiles. Nothing
+checks the *value* on either overload; that is deliberate, and the partial fixture above is why.
+
 ### Properties of DOM objects — the same helpers, and the reason to look for them
 
 `document.fullscreenElement`, `document.visibilityState`, `document.cookie`, `navigator.userAgent`,
@@ -420,6 +795,16 @@ setupAutoSpy(); // { duplicateCopies: 'throw', restoreProps: true, restoreMocks:
 check that fails the run, and (opt-in) `vi.restoreAllMocks()`. Turn on `restoreMocks: true` when the
 suite runs with `isolate: false`.
 
+**The restore also runs from an `onTestFinished` net**, because the `afterEach` is not guaranteed
+to. Vitest calls `afterEach` hooks in *reverse* registration order, so the setup file's is the last
+one, and a hook the spec file registered takes the chain down with it when it throws — the patches
+then travel into the next test and the failure surfaces somewhere that never touched them. One spec
+kept `afterEach(() => vi.restoreAllMocks())`; migrating it to `gettersToSpyOn` made the restored
+getter return `undefined`, `ngOnDestroy` called it as a signal, the `TypeError` aborted the hook,
+and a template error about a null profile appeared in a different `describe`. The net puts the
+properties back and warns with the count and the cause. `countMockedProps()` is exported if you
+would rather assert it: `afterEach(() => expect(countMockedProps()).toBe(0))`.
+
 **The one that only bites at scale:** with `isolate: false`, a `setTimeout` or
 `requestAnimationFrame` a component schedules and never clears keeps running after its file is done,
 and fires while the **next** file is mid-test. It is reported against that innocent file, as
@@ -456,6 +841,11 @@ 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).
 
+A rejection the runner has **already** blamed the finished test for is not reported again. An
+`async` test that fails an assertion leaves its own `AssertionError` in both places, so a red run
+used to print two messages per failure and the second one sent the reader hunting for a defect that
+was not there. What is left is what the check is for: the rejections that fail no test at all.
+
 **The one that gets slower the longer the run goes on:** every `vi.fn()` and `vi.spyOn()` is added
 to one `Set` inside `@vitest/spy`, because that is what `vi.clearAllMocks()` walks, and nothing takes
 anything out of it again. With `isolate: false` the set is created once per worker and only grows:
@@ -487,13 +877,45 @@ sweep (it returns how many went) and `getMockRegistrySize()` reports what is lef
 Two more switches, both about the environment rather than the spies:
 
 ```ts
-setupAutoSpy({ blockNetwork: true }); // reject every fetch, naming what was requested
+setupAutoSpy({ blockNetwork: true }); // fetch rejects, XHR fails, sendBeacon answers false
+```
+
+Under happy-dom, which — unlike jsdom — implements `fetch`: a component that pulls a remote asset
+really fetches it, nothing asserts on the response so the tests pass, and the aborts at teardown
+fail the run with **no test named**. If a green run exits 1 with `DOMException [AbortError]`, this
+is it.
+
+Under jsdom too, for the other half. jsdom implements `XMLHttpRequest` in full, and plenty of
+libraries never left it — `rmp-vast` pings every VAST tracker through a hand-rolled one
+(`FW.ajax`) — so a suite with `blockNetwork: true` already on was still reaching the internet, one
+ping per quartile per ad per test, and printing jsdom's `AggregateError at Object.dispatchError`
+for every connection that failed. What a green run prints then depends on whether the machine has a
+route out.
+
+Every channel is closed by default; the object is for narrowing it:
+
+| option   | default    | what it does                                                                       |
+| -------- | ---------- | ---------------------------------------------------------------------------------- |
+| `fetch`  | `true`     | `fetch` rejects, naming what was requested                                           |
+| `xhr`    | `'reject'` | `'reject'` fails the request (`status` 0, an `error` event); `'empty'` answers 200 with an empty body; `false` leaves XHR alone |
+| `beacon` | `true`     | `navigator.sendBeacon` answers `false` — only where the environment has one         |
+
+`'reject'` is the default because it is what `fetch` does: the code takes its failure branch, which
+is the branch a unit test should be asserting on. `'empty'` is for a request whose response nobody
+reads — a tracker ping, an analytics beacon — where failing it only trades one kind of noise for
+another:
+
+```ts
+setupAutoSpy({ blockNetwork: { xhr: 'empty' } }); // the ad-player suite's setting
 ```
 
-Only relevant under happy-dom, which — unlike jsdom — implements `fetch`. A component that pulls a
-remote asset then really fetches it; nothing asserts on the response, so the tests pass, and the
-aborts at teardown fail the run with **no test named**. If a green run exits 1 with
-`DOMException [AbortError]`, this is it.
+A `data:` URL is always let through, and it is the only thing that is: that is the scheme a spec
+serves its own fixtures from (`xhr.open('GET', \`data:application/xml,\${encodeURIComponent(vast)}\`)`),
+and the only one a DOM answers without a socket. A **relative** URL is not exempt either — the DOM
+resolves it against the document origin, so a spec that reaches `/config` and passes is resting on
+nothing listening on that port. `WebSocket` and `EventSource` are left alone: their failure is an
+event on an object the code keeps and reconnects, so there is no blanket answer that is not itself
+a behaviour change — `stubConstructor(globalThis, 'WebSocket', …)` is the tool for a spec with one.
 
 `restoreTimerGlobals` is on by default and needs no thought unless you turn it off: uninstalling
 fake timers under happy-dom **deletes** `Date` instead of restoring it (the global is inherited from
@@ -774,6 +1196,57 @@ 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 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
+answers every method of the declared type. `injectSpy(LocalStorage)` recognises it as an auto-spy
+and stays quiet.
+
+**Seed the double in the provider, not in the `beforeEach` under it.** Both factories take both
+halves — `returns` for what a spied method answers, `overrides` for a member that is not a method
+result:
+
+```ts
+provideAutoSpy(FavoritesService, {
+  returns: { load: of([]) },
+  overrides: { favoritesCacheUpdated$: of(undefined), favoriteVODs: [] },
+});
+
+provideAutoSpyForToken(PRODUCTS, undefined, { returns: { getProducts: of([]), getById: of(null) } });
+```
+
+A seeded `overrides` member is stored verbatim and is **no longer a spy**, so seed data there and
+name methods in `returns` when they must stay assertable. The reason to prefer this over a second
+statement is not brevity: the shortcut people take instead is an exported `const` provider carrying
+the values, and under `isolate: false` that is one set of spies shared by every file that imports
+it.
+
+**`observablePropsToSpyOn` works on a token too**, and matters more there than on a class. A class
+tells the factory which members are methods; a type does not, so *every* unnamed key of a
+token-driven double is a function spy — including an `Observable` property, which the code under
+test then subscribes to as if it were a function, failing far from the double:
+
+```ts
+provideAutoSpyForToken(FAVORITES, undefined, { observablePropsToSpyOn: ['favorites$'] });
+// …
+injectSpy(FAVORITES).favorites$.nextWith([{ id: 1 }]);
+```
+
+A member also named in `overrides` keeps its seed — hand the double a real `Subject` there when the
+spec drives the stream itself, and name it here when `nextWith` is what the spec wants. That is the
+same precedence the class-based factory uses. Before 3.5.0 this option existed only on the class
+path, and reaching a token with observable members meant going back to a hand-written double —
+which is exactly what `prefer-provide-auto-spy` and `prefer-create-spy-from-class` exist to prevent.
+
+**Do not write a local `injectSpy`.** A wrapper of the shape
+`TestBed.inject(token as never) as Spy<T>` — a double assertion, typed
+`<T>(token: abstract new (...args: never[]) => T)` — is a common thing to find already in a
+repository, and the library's is strictly wider: it takes `ClassType<T>`, an `InjectionToken<T>` and
+an abstract constructor, warns when the injector hands back something that is not a spy, and has no
+assertion for the project's lint rules to argue with. Two functions with the same name and different
+signatures means the import order decides which one a file gets. Delete the local one, or re-export
+the library's under that name.
+
 ### Signals — which helper depends on whose signal it is
 
 ```ts
@@ -854,6 +1327,32 @@ fail with something that has nothing to do with intersection.
 `addedNodes` is a `NodeList`. Do not build one from a `DocumentFragment`: appending **moves** the
 nodes, so the helper silently rips the element out of the fixture it was just asserted on.
 
+### A component's own `providers` win, and the symptom is nowhere near the cause
+
+Worth reading before the rest of this section: it has now come up twice in one migration wave, and
+both times the failure landed in a different file from its cause.
+
+`@Component({ providers: [RemoveProfileService] })` declares the provider on the **element**
+injector, and a module-level `provideAutoSpy(RemoveProfileService)` in `configureTestingModule`
+loses to it — so the component builds the **real** service. Nothing warns. What fails is whatever
+the real service touches first: in the observed case a logger, with
+`TypeError: Cannot read properties of undefined (reading 'pipe')`, which names neither the component
+nor the provider nor the spy.
+
+Two things fix it, and which one depends on whether the double is wanted:
+
+```ts
+// keep a double, but put it where the component will look
+const menu = overrideComponentProvider(SmartVodComponent, MenuBuilderService);
+
+// or take the component's own provider away, so the module-level one is reached again
+TestBed.overrideComponent(ProfileComponent, { remove: { providers: [RemoveProfileService] } });
+```
+
+`overrideComponentProvider` is the one to reach for by default — it also queues the component with
+the TestBed compiler, which `overrideProvider` alone does not do. Reach for the `remove` form when
+the module already provides the spy and the component's declaration is simply in the way.
+
 ### `injectSpy` cannot reach a component-level provider
 
 `injectSpy(X)` reads the **global** `TestBed` injector. A provider declared on the component
@@ -878,11 +1377,15 @@ const menu = overrideComponentProvider(SmartVodComponent, MenuBuilderService); /
 TestBed.configureTestingModule({ … }).overrideProvider(PaymentToolService, overrideAutoSpy(PaymentToolService));
 ```
 
-Two silent failures this avoids. `overrideProvider(X, provideAutoSpy(X))` passes a _provider_ where
-`{ useValue }` is expected — no error, no warning, the test runs on the real service. And
-`overrideProvider` only reaches a component the TestBed compiler knows about, so a standalone
-component instantiated through a parent's template needs to be in `imports` first;
-`overrideComponentProvider` queues it.
+`overrideProvider(X, provideAutoSpy(X))` is **not** broken, contrary to what this section used to
+say: `provideAutoSpy` returns `{ provide, useValue }`, `overrideProvider` reads the `useValue` off
+it and ignores the extra `provide`, and the spy is installed. `overrideAutoSpy` is the right call
+because it says what it does and hands the spy back directly — not because the other form is a
+no-op.
+
+The failure that is real: `overrideProvider` only reaches a component the TestBed compiler knows
+about, so a standalone component instantiated through a parent's template needs to be in `imports`
+first; `overrideComponentProvider` queues it.
 
 Do **not** reach for `TestBed.overrideComponent` here — see the next subsection for why it is worse
 than the problem it solves.
@@ -1042,7 +1545,19 @@ const pinCode = injectSpy(PIN_CODE_SERVICE_TOKEN); // Spy<PinCodeService>
 
 A token typed with an interface has no class to read, so the habit is a `…Mock` class written in the
 spec — after which `Spy<Mock>` and `Spy<Interface>` disagree and somebody casts. Do not write
-`TestBed.inject<any>(TOKEN)`; both of these accept a token.
+`TestBed.inject<any>(TOKEN)`; both of these accept a token. And it is `provideAutoSpyForToken`, not
+`provideAutoSpy`: the latter reads a class prototype, which a token does not have.
+
+**The second argument is not optional as often as it looks.** A spy answers `undefined` until it is
+told otherwise, and that is fatal the moment the code under test *chains* off it — a constructor
+doing `inject(LOGGER).channel('auth').debug('…')` dies on the `.debug` of `undefined` before the
+spec's first line runs, because nothing in production wrote `?.` there. Seed the link:
+
+```ts
+provideAutoSpyForToken(LOGGER, { channel: vi.fn().mockReturnThis() });
+```
+
+For a chain more than one link long, `mockDeep<T>()` is the double that answers every level (§2).
 
 ### A host for a directive under test
 
@@ -1145,17 +1660,100 @@ import autoSpy from 'vitest-auto-spy/eslint-plugin';
 export default [{ files: ['**/*.spec.ts'], ...autoSpy.configs.recommended }];
 ```
 
-| Rule                           | Level   | Flags                                                                    |
-| ------------------------------ | ------- | ------------------------------------------------------------------------ |
-| `no-expect-in-subscribe`       | `error` | `expect()` inside `subscribe()` → `expectEmission`                       |
-| `no-object-define-property`    | `error` | `Object.defineProperty` in a spec → `mockReadonlyProp` / `mockValueProp` |
-| `prefer-provide-auto-spy`      | `warn`  | `{ provide: X, useValue: { a: vi.fn() } }` → `provideAutoSpy(X)`         |
-| `prefer-create-spy-from-class` | `warn`  | an object literal of 2+ `vi.fn()`s → `createSpyFromClass`                |
-| `prefer-inject-spy`            | `warn`  | `vi.spyOn(TestBed.inject(X), 'm')` → `injectSpy(X)`                      |
-| `no-shared-module-level-mock`  | `error` | an **exported** value holding `vi.fn()`s → export a factory instead      |
-| `no-mocked-for-spy`            | `warn`  | `let s: Mocked<T>` → `Spy<T>`                                            |
-| `no-done-callback`             | `error` | `it('x', (done) => …)` → `async` + an awaited assertion                  |
-| `no-floating-assertion`        | `error` | `expect()` in a `.then()` nobody awaits → `expect(await promise)`        |
+| 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`   | `Mocked<T>` in any type position → `Spy<T>`, import and all              |
+| `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` | —         | two providers for one token in one array → the earlier one never runs   |
+| `no-inject-before-override`    | `warn`  | —         | `TestBed.inject()` in a hook, in a suite that still calls `override*`    |
+
+Twelve rules; two fix on their own, three offer suggestions. `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
+helper's parameter, and `as unknown as Mocked<T>`, which in one batch stood next to the declaration
+in all eight reports — fix one and leave the other and the file says both. It declines where it
+cannot prove the rename (a `Mocked` the file declares itself, a `Spy` that is already something
+else, `Mocked<{ a: Mock }>` rather than a named type) and reports without a fix.
+
+`prefer-as-spy` is the same licence from the other end, and the one a migration meets in bulk: a
+`jest-auto-spies` suite writes `TestBed.inject(X) as Spy<X>` once per injected double, and that cast
+fails here with `TS2352` — `Spy<T>` adds `accessorSpies` and the per-method helpers, so neither type
+sufficiently overlaps the other. `asSpy` is a typed identity function, so `--fix` keeps the
+assertion the developer already made, carries the type arguments across (inference answers
+`Spy<Service<any>>` for a generic class), adds the `asSpy` import and removes a `Spy` import the
+rewrite orphans. A cast that hops through `unknown` is left alone — the hop says the value is not a
+`T` — except after `TestBed.inject(X)`, where the container returns `X` by construction and the hop
+was only silencing `TS2352`. Neither rule is for the object under test: a service the spec
+exercises is not a double, and typing it as the class is the repair there.
+
+`no-expect-in-subscribe` reports one shape and **three different edits**, and says which: the
+subscription is the last thing the test does (invert it into `await firstValueFrom`); something
+after it is what makes the stream emit (hold the promise — `const p = expectEmission(src$)`, fire
+the trigger, `await p` — because inverting deadlocks); or the assertion is in the `error` branch
+(`await expect(firstValueFrom(src$)).rejects.toMatchObject(…)`). It also counts assertions the
+callback reaches through a helper it calls, which used to make `subscribe((d) => assertShape(d))`
+invisible. `prefer-provide-auto-spy` reads `useFactory` as well as `useValue`, through the function
+in the first case and not in the second — a factory's body is what DI ends up holding, while a
+function inside a `useValue` is a lazily-built double, i.e. the fix. The other three change behaviour — whether `injectSpy(X)`
+finds a spy is decided by a `provideAutoSpy(X)` usually written in another file, `mockValueProp`
+leaves the property writable and configurable, and `no-expect-in-subscribe` rewrites a whole test
+— so all three are suggestions an editor offers and a human accepts:
+
+```ts
+it('maps the products', () =>                        // ❌ flagged, and a suggestion is offered
+  new Promise<void>((done) => {
+    service.getProducts(id).subscribe((products) => {
+      expect(products).toEqual(expected);
+      done();
+    });
+  }));
+
+it('maps the products', async () => {                // ✅ what accepting it produces
+  const products = await firstValueFrom(service.getProducts(id));
+
+  expect(products).toEqual(expected);
+});
+```
+
+That template was 111 of 133 violations in one migration batch. The suggestion appears only for the
+exact frame above — one `subscribe` statement in the executor, one block-bodied callback, `done()`
+mentioned once and standing last — and the report itself now counts assertions per `subscribe`
+rather than one message per `expect`, which used to double the apparent size of the job.
+
+`prefer-inject-spy` reads both spellings of the same mistake, which is the point of the second one:
+
+```ts
+vi.spyOn(TestBed.inject(DomainEventsService), 'announce');           // flagged, always was
+const domainEvents = TestBed.inject(DomainEventsService);
+const announceSpy = vi.spyOn(domainEvents, 'announce');              // flagged now
+```
+
+The variable is resolved through the scope manager, so it has to be a `const`/`let` initialised
+from `TestBed.inject(...)` and never assigned again — a name bound by an import, a parameter, or a
+`let` that is reassigned is left alone.
+
+`no-inject-before-override` catches the trap this plugin's own advice sets. `TestBed.inject()` in a
+`beforeEach` — the line you write once `provideAutoSpy(X)` has taken away the literal you used to
+configure — instantiates the module, and every `TestBed.override*` afterwards throws, including one
+written above it inside a `createComponent` helper. Configure the double after the overrides
+(`injectSpy(X)` in the test), or keep the access lazy: `const api = () => injectSpy(Api)`. The check
+is order-free by design, since a helper declared above the hook still runs after it.
+
+`no-overridden-provider` is the one that catches a defect rather than a habit. Angular keeps the
+last provider for a token, so `[provideAutoSpy(X), { provide: X, useValue: mockX }]` is not an
+auto-spy with configuration — the auto-spy is dead and the hand-rolled double is what DI hands out.
+Found on eight tokens of one file. It reads both spellings in either order, compares tokens as
+source text, and offers no fix: deleting either line is a valid repair and they mean opposite
+things.
 
 The legacy `.eslintrc` `plugins: []` form cannot work — it resolves names to `eslint-plugin-*`
 packages, which a subpath export can never be.
@@ -1179,6 +1777,7 @@ packages, which a subpath export can never be.
 | `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)               |
@@ -1204,6 +1803,8 @@ packages, which a subpath export can never be.
 | 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                      | the hand-off count depends on the dependency, not on the spec          | `await flushEventLoopUntil(() => r.status() !== 'loading', { label })`                      |
+| `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 |
+| a template error in a `describe` that never patched anything                          | a spec `afterEach` threw and skipped `setupAutoSpy`'s, so a `mock*Prop` patch travelled | upgrade — an `onTestFinished` net restores it and names the cause (§10)                    |
 | `Property 'mockReturnValue' does not exist on type 'never'`                          | a generic method with a conditional return type; the spy collapsed     | upgrade — fixed in the types; the member now keeps its sync helper bundle                   |
 | `Type 'string' is not assignable to type 'never'` on `gettersToSpyOn`                | the list used to reject callable values, i.e. every `Signal<T>`        | upgrade — any string key is nameable; prefer `mockSignalProp` for a signal                  |
 | `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)                   |
@@ -1211,6 +1812,15 @@ packages, which a subpath export can never be.
 | a spy that cannot take a real `signal()` in `mockReadonlyProp`                       | the value was typed against `Spy<T>[K]`, not against `T[K]`            | upgrade — the `mock*Prop` helpers accept a `Spy<T>` and check against `T`                   |
 | `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)             |
+| a stream built with `of(double)` that never emits                                     | the double answered `schedule`, so rxjs ate it as the scheduler        | upgrade — `schedule` / `lift` / `@@observable` / `getReader` are answered `undefined` (§2)   |
+| `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`    |
+| `nextWith` emitting nothing, on a spy an earlier test completed or errored             | `error()`/`complete()` close a Subject for good                        | upgrade — the next configuration starts a new stream                                         |
+| `accessorSpies.setters.X` is `undefined` after `gettersToSpyOn: ['X']`                 | only the named half was spied                                          | upgrade — the declared other half is mirrored (§5)                                            |
+| `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      |
+| a `mock*Prop` patch on a `createAutoMock` double that changes nothing                 | the Proxy had no `defineProperty` trap before 3.5.0                    | upgrade — nothing to change in the spec                                                     |
+| `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)                                                            |
@@ -1230,6 +1840,19 @@ packages, which a subpath export can never be.
 | `vi.spyOn(TestBed.inject(X), 'method')`                              | `injectSpy(X).method`                                         |
 | `Object.defineProperty(service, 'ready', { value: true })`           | `mockReadonlyProp(service, 'ready', true)`                    |
 | `source$.subscribe(v => expect(v).toBe(1))`                          | `await expect(expectEmission(source$)).resolves.toBe(1)`      |
+| `await lastValueFrom(done$, { defaultValue: undefined })`            | `await expectCompletion(done$)`                               |
+| `{ timeout: 0 }` on every helper because timers are faked            | `setEmissionTimeout(100)` once, in the setup file              |
+| `{ provide: AbstractToken, useValue: createAutoMock<T>() }`          | `provideAutoSpy(AbstractToken)`                               |
+| `mockDeep<T>()` for a chain that goes through a **call**             | `mockDeep<T>({}, { selfReturning: true })`                    |
+| `await expect(expectEmission(x$)).rejects.toBe(originalError)`       | `await expect(expectError(x$)).resolves.toBe(originalError)`  |
+| `source$.pipe(skip(1))` / `pipe(filter(p))` in front of the helper   | `expectEmission(source$, { skip: 1 })` / `{ until: p }`       |
+| hold the promise, `vi.runAllTimers()`, then await                    | `expectEmission(source$, { advance: () => vi.runAllTimers() })` |
+| `injectSpy(X)` then a `mockReturnValue` per method in `beforeEach`   | `provideAutoSpy(X, { returns: { … }, overrides: { … } })`      |
+| a local `injectSpy` wrapper with `as never` + `as Spy<T>`            | the library's — it also takes an `InjectionToken`             |
+| a hand-written double for a token with `Observable` members          | `provideAutoSpyForToken(T, undefined, { observablePropsToSpyOn: […] })` |
+| `mockDeep<T>() as unknown as T` to satisfy an API typed against `T`  | `asInstance(mockDeep<T>())`                                   |
+| `from([double])` to stop `of(double)` swallowing the double          | `of(double)` — `schedule` is no longer answered (§2)          |
+| `spy.instanceField.mockReturnValue(…)` on a member Angular moved     | `provideAutoSpy(X, { instanceMethodsToSpyOn: ['…'] })` (§5)   |
 | `expect(component.total).toBeTruthy()` (a signal)                    | `expect(component.total).toHaveSignalValue(3)`                |
 | `fixture.detectChanges()` then assert signal state                   | `await stable(fixture)` then assert                           |
 | `onlyMethodsToSpyOn: [...]` "to add a method"                        | omit it, or use `instanceMethodsToSpyOn`                      |
@@ -1246,7 +1869,7 @@ packages, which a subpath export can never be.
 | ten `await Promise.resolve()` for a dynamic `import()`               | `await settleDynamicImport(() => import('…'))`                |
 | `await fixture.whenRenderingDone()`                                  | `await stable(fixture)`                                       |
 | an exported `const` provider with `vi.fn()` inside                   | an exported **factory** returning it (§10)                    |
-| `.overrideProvider(X, provideAutoSpy(X))` (silent no-op)             | `.overrideProvider(X, overrideAutoSpy(X))`                    |
+| `.overrideProvider(X, provideAutoSpy(X))` (works, but says the wrong thing) | `.overrideProvider(X, overrideAutoSpy(X))`             |
 | `TestBed.overrideComponent` to swap a provider                       | `overrideComponentProvider(Cmp, X)`                           |
 | `{ target, isIntersecting } as unknown as IntersectionObserverEntry` | `intersectionEntry(target, true)`                             |
 | an assertion containing a date, with no clock set                    | `mockSystemTime(iso)` first                                   |
@@ -1254,7 +1877,18 @@ packages, which a subpath export can never be.
 | `vi.mock('@angular/core')` to neutralise `effect()`                  | set the signals, `await stable(fixture)`, assert the result   |
 | a second `vi.spyOn(console, 'error')`                                | `consoleErrorSpy` from `vitest-auto-spy/console`              |
 | `mockReadonlyProp(c, 'items', vi.fn(() => []))`                      | `mockReadonlyProp(c, 'items', signal([]))` — a real signal    |
-
+| `spy.m.mockReturnValue(subject$)` for a `vi.fn(() => subject$)` | `spy.m.mockImplementation(() => subject$)` — the variable is re-read |
+
+
+**The one mechanical rename in a migration that is not equivalent.** `vi.fn(() => x)` reads `x`
+when the double is *called*; `mockReturnValue(x)` freezes the value `x` had when the double was
+*configured*. They are indistinguishable until the test reassigns `x` — and the commonest reason to
+do that is a fresh `Subject` after the previous one has been `error()`ed or completed, which is
+exactly the case a suite is testing when it reassigns. The double then keeps handing out the dead
+one: in one spec the service received a completed subject and silently skipped the modal it was
+meant to show, with the test still green. Carry `vi.fn(() => x)` over as
+`mockImplementation(() => x)`, and keep `mockReturnValue` for a literal. Worth saying out loud to
+anyone writing a codemod, because the rename looks like the safest edit in the file.
 ---
 
 ## 19. Before you report success
@@ -1268,3 +1902,21 @@ npx tsc --noEmit                      # Spy<T> mistakes are compile errors, not
 
 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.
+
+### If you are writing a codemod over specs
+
+Two traps, both found the hard way on rxjs-heavy code.
+
+**`String.prototype.replace` interprets `$` in the replacement.** `$&`, `` $` ``, `$'` and `$n` are
+substitution patterns, and `$'` — "everything after the match" — is one character away from every
+observable name in the codebase. A replacement containing `forceRequeryAndStartPlaybackAt$'`
+inserted the entire remainder of the file into itself and left an unterminated string; the only
+thing that caught it was ESLint's `Parsing error`. Pass a function, which is never interpreted:
+
+```ts
+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`.