vitest-auto-spy 3.6.0 → 3.8.0

package/AGENTS.md

@@ -269,7 +269,7 @@ import { type Spy, injectSpy, mockReadonlyProp, provideAutoSpy } from 'vitest-au
 
 describe('TaskService', () => {
   let projects: Spy<ProjectStore>;
-  let feed: Spy<FeedService>;
+  let feed: Spy<NewsFeedService>;
   let service: TaskService;
 
   beforeEach(() => {
@@ -277,12 +277,12 @@ describe('TaskService', () => {
       providers: [
         provideAutoSpy(NotificationService), // plain service — nothing to configure
         provideAutoSpy(ProjectStore, { instanceMethodsToSpyOn: ['current', 'isEmpty'] }), // signals
-        provideAutoSpy(FeedService, { observablePropsToSpyOn: ['connected$'] }), // Observable props
+        provideAutoSpy(NewsFeedService, { observablePropsToSpyOn: ['connected$'] }), // Observable props
       ],
     });
 
     projects = injectSpy(ProjectStore);
-    feed = injectSpy(FeedService);
+    feed = injectSpy(NewsFeedService);
 
     feed.connected$.nextWith(true); // seed the defaults every test needs, once
     projects.save.mockReturnValue(of(true));
@@ -369,6 +369,27 @@ 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 }`.
 
+When the argument worth asserting on is one the **code under test built** — a callback, a config
+object, an `AbortSignal` — describing its shape is the wrong tool. `expect.any(Function)` says a
+function was passed; `captureArg` hands it to you so the test can call it:
+
+```ts
+import { captureArg } from 'vitest-auto-spy';
+
+const onDone = captureArg<() => void>();
+
+expect(notifier.subscribe).toHaveBeenCalledWith('ready', onDone);
+
+onDone.value(); // and now exercise what was passed
+expect(component.finished()).toBe(true);
+```
+
+`.values` holds every match, oldest first; `.captured` asks without triggering the "nothing was
+captured" throw; `.reset()` lets one captor serve two phases. **Assertions only** — a captor matches
+every value, so putting one in `calledWith` would configure a return for every call, which is
+`mockReturnValue` spelled less clearly, and `calledWith` is typed to the method's own parameters so
+it will not compile anyway.
+
 **The observable helpers are backed by a `ReplaySubject(1)` that belongs to the spy, and it is
 configuration — so it must be reset with the rest of it.** Two failures used to come out of that
 buffer outliving the test that filled it, and both were silent:
@@ -569,8 +590,8 @@ constructor and produces `Service<any>`, and the `any` surfaces much later as a
 it says "type parameter":
 
 ```ts
-const config = asSpy<RemoteConfigService>(TestBed.inject(RemoteConfigService)); // ✅
-const config = injectSpy<RemoteConfigService>(RemoteConfigService);             // ✅
+const config = asSpy<FeatureFlagService>(TestBed.inject(FeatureFlagService)); // ✅
+const config = injectSpy<FeatureFlagService>(FeatureFlagService);             // ✅
 ```
 
 ---
@@ -1067,6 +1088,7 @@ mechanisms, and a test that waits on the wrong one fails with a message that nam
 | effects + `afterNextRender` + CD              | `await stable(fixture)` (`…/angular`)              | `detectChanges()` alone                   |
 | timers, debounces, polling                    | `await advanceTimers(ms)` (`…/setup`)              | `await Promise.resolve()`                 |
 | a dynamic `import()`, native `async` in a dep | `await flushEventLoop()` / `settleDynamicImport()` | `tick()`, `flushMicrotasks()`, microtasks |
+| an `httpResource()` / `resource()` / `rxResource` | `await settleResource(r)` (`…/angular`) | `flushEventLoopUntil` — it never ticks |
 
 ```ts
 import { flushEventLoop, settleDynamicImport } from 'vitest-auto-spy';
@@ -1088,9 +1110,14 @@ Three rules worth stating outright, because each of them cost a day somewhere:
   and a non-zero exit code.
 
 `flushEventLoopUntil(isDone, { turns, label })` is the same thing with a condition and a budget —
-for a `resource()` leaving `loading`, a chunk becoming reachable, an SDK reporting itself ready. Use
-it instead of a hand-tuned turn count: the count depends on the dependency, not on the spec, and a
-condition that never holds fails naming the `label` rather than hanging until the runner's timeout.
+for a chunk becoming reachable, an SDK reporting itself ready, a queue draining. Use it instead of a
+hand-tuned turn count: the count depends on the dependency, not on the spec, and a condition that
+never holds fails naming the `label` rather than hanging until the runner's timeout.
+
+**Not for an Angular `resource()` / `httpResource()`.** Those need a change-detection _tick_, and
+this helper only takes event-loop turns — a resource awaited through it finishes the whole budget
+having issued zero requests. `settleResource(resource, { turns, label })` from
+`vitest-auto-spy/angular` is that wait.
 
 `flushEventLoop(turns?)` takes real event-loop turns even while the timers are faked, without
 touching the clock. It is the honest name for the `await vi.advanceTimersByTimeAsync(0)` trick,
@@ -1160,10 +1187,10 @@ inlined when the mock would be installed, so the real implementation runs and th
 for the wrong reason or fails somewhere unrelated.
 
 ```ts
-import * as engine from '@app/player-engine';
+import * as engine from '@app/pricing-engine';
 
-vi.mock('@app/player-engine');
-beforeEach(() => assertMocked(engine, { specifier: '@app/player-engine', exports: ['createEngine'] }));
+vi.mock('@app/pricing-engine');
+beforeEach(() => assertMocked(engine, { specifier: '@app/pricing-engine', exports: ['createEngine'] }));
 ```
 
 And when a mocked dependency probes itself with `mod.default ?? mod` — every package that ships both
@@ -1209,7 +1236,7 @@ result:
 ```ts
 provideAutoSpy(FavoritesService, {
   returns: { load: of([]) },
-  overrides: { favoritesCacheUpdated$: of(undefined), favoriteVODs: [] },
+  overrides: { favoritesCacheUpdated$: of(undefined), favoriteItems: [] },
 });
 
 provideAutoSpyForToken(PRODUCTS, undefined, { returns: { getProducts: of([]), getById: of(null) } });
@@ -1332,8 +1359,8 @@ nodes, so the helper silently rips the element out of the fixture it was just as
 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`
+`@Component({ providers: [DeleteAccountService] })` declares the provider on the **element**
+injector, and a module-level `provideAutoSpy(DeleteAccountService)` 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
@@ -1343,10 +1370,10 @@ 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);
+const menu = overrideComponentProvider(CatalogPageComponent, NavigationBuilderService);
 
 // or take the component's own provider away, so the module-level one is reached again
-TestBed.overrideComponent(ProfileComponent, { remove: { providers: [RemoveProfileService] } });
+TestBed.overrideComponent(ProfileComponent, { remove: { providers: [DeleteAccountService] } });
 ```
 
 `overrideComponentProvider` is the one to reach for by default — it also queues the component with
@@ -1371,10 +1398,10 @@ do that, because a testing-module provider loses to one the component declares:
 ```ts
 import { overrideAutoSpy, overrideComponentProvider } from 'vitest-auto-spy/angular';
 
-const menu = overrideComponentProvider(SmartVodComponent, MenuBuilderService); // → Spy<MenuBuilderService>
+const menu = overrideComponentProvider(CatalogPageComponent, NavigationBuilderService); // → Spy<NavigationBuilderService>
 
 // or, when the component is already in the testing module:
-TestBed.configureTestingModule({ … }).overrideProvider(PaymentToolService, overrideAutoSpy(PaymentToolService));
+TestBed.configureTestingModule({ … }).overrideProvider(PaymentMethodService, overrideAutoSpy(PaymentMethodService));
 ```
 
 `overrideProvider(X, provideAutoSpy(X))` is **not** broken, contrary to what this section used to
@@ -1474,12 +1501,29 @@ spies.get(PricingService).total.mockReturnValue(100);
 // NOTE: Injector.create() — it does NOT accept EnvironmentProviders (provideHttpClient() etc.)
 
 // zoneless waiting
-await stable(fixture); // flush effects, then await the fixture
+await stable(fixture); // flush effects, then await the fixture; fails at 2000 ms naming the cause
+await stable(fixture, { timeout: 5000, label: 'the products fixture' });
 flushEffects(); // the no-fixture half: services, stores, runInInjectionContext
 
+// resources — one wait for httpResource(), resource() and rxResource()
+flushEffects(); // an httpResource issues NO request until something ticks
+httpTesting.expectOne('/api/products').flush([product]);
+await settleResource(products, { label: 'the product resource' });
+
+// ...or skip the request entirely when it is not what the spec is about
+const products = mockResourceProp(service, 'products', []);
+products.set([product]); // 'resolved'   products.loading()   products.fail('offline')
+expect(products.reload).toHaveBeenCalled(); // reload is spied, and re-issues nothing
+
 // signal assertions
 registerSignalMatchers(); // once, in the setup file
 expect(component.total).toHaveSignalValue(3);
+
+// resource assertions — value AND status, which is the whole point
+registerResourceMatchers(); // once, in the setup file
+expect(component.products).toBeLoading();
+expect(component.products).toHaveResourceValue([product]);
+expect(component.products).toHaveResourceError(/503/);
 ```
 
 Two zoneless traps:
@@ -1489,6 +1533,19 @@ Two zoneless traps:
 - `expect(someSignal).toBeTruthy()` passes for **every** signal ever created — a signal is a
   function. Use `toHaveSignalValue`, which also rejects the missing-parentheses mistake.
 
+And one resource trap, which is the same shape one level up: an `httpResource()` reports `loading`
+with its **default** value until a tick _and_ a microtask after its response is flushed, so a spec
+that asserts too early asserts the default and passes. `settleResource` fails instead of passing
+emptily. Note the order — `flushEffects()` first (the request is issued there, not on creation),
+then the flush, then the wait.
+
+`toHaveResourceValue` is the matcher form of that trap and the reason to prefer it over
+`expect(products.value()).toEqual(...)`: it **fails an unresolved resource even when the default
+value matches**, and names the status it was in. And when the request is not what the spec is about
+at all, do not arrange one — `mockResourceProp(service, 'products', [])` replaces the property with
+a double whose `set` / `fail` / `loading` move it directly, built from real `signal()`s so a
+`computed()` downstream still recomputes. Nothing is in flight, so there is nothing to await.
+
 Per-file timing, to find which specs actually pay for `TestBed`:
 
 ```ts
@@ -1510,8 +1567,10 @@ if (process.env['SPEC_TIMING']) {
 preload = ["vitest-auto-spy/bun-angular"]
 ```
 
-It re-exports everything in this section except `registerSignalMatchers` and the TestBed
-diagnostics, which need the runner's `expect.extend` and suite-level hooks.
+It re-exports everything in this section except `registerSignalMatchers`,
+`registerResourceMatchers`, `mockSignalProp` / `mockResourceProp` and the TestBed diagnostics — the
+matchers and diagnostics need the runner's `expect.extend` and suite-level hooks, and the `mock*Prop`
+family is not re-exported there either.
 
 ---
 
@@ -1539,8 +1598,8 @@ which platform and which providers is not this library's decision.
 ### A dependency behind an `InjectionToken`
 
 ```ts
-providers: [provideAutoSpyForToken(PIN_CODE_SERVICE_TOKEN)];
-const pinCode = injectSpy(PIN_CODE_SERVICE_TOKEN); // Spy<PinCodeService>
+providers: [provideAutoSpyForToken(PASSCODE_SERVICE_TOKEN)];
+const passcode = injectSpy(PASSCODE_SERVICE_TOKEN); // Spy<PasscodeService>
 ```
 
 A token typed with an interface has no class to read, so the habit is a `…Mock` class written in the
@@ -1802,7 +1861,9 @@ packages, which a subpath export can never be.
 | 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                      | the hand-off count depends on the dependency, not on the spec          | `await flushEventLoopUntil(() => r.status() !== 'loading', { label })`                      |
+| 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 |
 | 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                   |
@@ -1898,11 +1959,20 @@ Run what the project actually has — check its `package.json` first.
 ```bash
 npx vitest run path/to/file.spec.ts   # or: bun test path/to/file.test.ts
 npx tsc --noEmit                      # Spy<T> mistakes are compile errors, not runtime ones
+npx vitest-auto-spy doctor            # suite-level defects that never fail a run
 ```
 
 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.
 
+`doctor` is read-only and finds what a green run cannot: a `tsconfig` `include` pattern that
+matches no file (so it type-checks nothing while `tsc --noEmit` still reports success), a
+production module importing a `*.spec.ts`, a spec importing another spec, a `@jest-environment`
+pragma the runner never reads, and configuration left behind for a runner that is gone. It is
+worth one run after any large edit to a test suite — especially after a codemod, which is where
+the eaten glob below came from. Full reference:
+<https://asdalexey.github.io/vitest-auto-spy/utilities/cli>.
+
 ### If you are writing a codemod over specs
 
 Two traps, both found the hard way on rxjs-heavy code.

package/README.md

@@ -16,7 +16,7 @@ identical API, with **RxJS** spies and **Angular / NestJS / React / Vue·Pinia /
 [![npm version](https://img.shields.io/npm/v/vitest-auto-spy?color=brightgreen&logo=npm)](https://www.npmjs.com/package/vitest-auto-spy)
 [![npm downloads](https://img.shields.io/npm/dm/vitest-auto-spy?color=brightgreen&logo=npm)](https://www.npmjs.com/package/vitest-auto-spy)
 [![CI](https://github.com/ASDAlexey/vitest-auto-spy/actions/workflows/ci.yml/badge.svg)](https://github.com/ASDAlexey/vitest-auto-spy/actions/workflows/ci.yml)
-[![minzipped size](https://img.shields.io/badge/minzip-12.5%20kB-brightgreen)](#install)
+[![minzipped size](https://img.shields.io/badge/minzip-13.0%20kB-brightgreen)](#install)
 [![types](https://img.shields.io/npm/types/vitest-auto-spy?logo=typescript&logoColor=white)](https://www.npmjs.com/package/vitest-auto-spy)
 [![coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](https://github.com/ASDAlexey/vitest-auto-spy/actions/workflows/ci.yml)
 [![license](https://img.shields.io/npm/l/vitest-auto-spy?color=blue)](./LICENSE)
@@ -48,20 +48,21 @@ identical API, with **RxJS** spies and **Angular / NestJS / React / Vue·Pinia /
 - 📡 First-class RxJS `Observable` spying (`nextWith`, `nextWithValues`, `throwWith`, …)
 - ⚙️ Getter / setter spies via `accessorSpies`
 - 🧰 DI & mocking utilities — `provideAutoSpy` / `injectSpy` (Angular, NestJS, Vue), `createFunctionSpy`, `mockReadonlyProp` for signals
-- ⚡ Angular speed & zoneless helpers — `renderShallow` (**1.7×** on real component specs), `createWithAutoSpies`, `stable` / `flushEffects`, `toHaveSignalValue`, per-file `TestBed` timings
+- ⚡ Angular speed & zoneless helpers — `renderShallow` (**1.7×** on real component specs), `createWithAutoSpies`, `stable` / `flushEffects`, `settleResource` for `httpResource()`, `toHaveSignalValue`, per-file `TestBed` timings
 - 🧱 The providers a testing module cannot reach — `overrideComponentProvider`, `provideAutoSpyForToken`, `assertNgModuleScopes`, `createDirectiveHost`
 - 📡 Observable assertions that fail on silence — `expectEmission` / `expectEmissions` / `expectNoEmission` / `expectCompletion` / `expectError`, no rxjs required, Angular `output()` included
 - 🏗️ Doubles for what the code builds itself — `mockConstructor` / `stubConstructor` for `new`, plus `stubMediaElement`, `stubAbortController` and the observer stubs
 - ⏳ Waiting that is not a guess — `flushEventLoop`, `settleDynamicImport`, `flushEventLoopUntil`, and a clock that survives fake timers (`mockSystemTime`, `useCountingClock`)
 - 🌀 `fakeAsync` / `waitForAsync` on Vitest — one import of `vitest-auto-spy/zone`; zone.js stays out of every other entry
 - 🧩 Module mocks that prove they applied — `assertMocked`, `moduleNamespace`, for a `vi.mock()` a bundler quietly ignored
-- 🧾 Fixtures without casts — deep-partial `createMock`, `narrow()`, `withOverrides()`, `asInstances()`
+- 🧾 Fixtures without casts — deep-partial `createMock`, `narrow()`, `withOverrides()`, `asInstances()`, `captureArg()`
 - 🚚 A migration you can verify — `compareTestRuns` on the two JSON reports, `diffByField` for the assertion the reporter collapses
 - 📏 Lint rules and one-line test-run hygiene — twelve rules in `vitest-auto-spy/eslint-plugin` (two `--fix`, three suggestions), `setupAutoSpy()`
 - 🩺 [Editor diagnostics](#editor-diagnostics--webstorm--vs-code) — the same anti-patterns underlined while you type: native ESLint inspections in **WebStorm** and the other JetBrains IDEs, the ESLint extension in **VS Code**, no extra plugin either way
+- 🔎 [`npx vitest-auto-spy doctor`](#the-cli--doctor-and-init) — suite-level defects **that never fail a run**: a `tsconfig` `include` matching no file, a production module importing a spec, a `@jest-environment` pragma the runner never reads, config left behind for a runner that is gone. Read-only, no config, exits 1 in CI
 - 🔇 Console spies — `import { consoleInfoSpy } from 'vitest-auto-spy/console'` silences `console` and asserts its calls
 - 🧭 [**Spec patterns**](https://asdalexey.github.io/vitest-auto-spy/recipes) — the shapes a ~370-file Angular suite converged on, and the traps that only surface at scale
-- 🤖 Built for AI agents too — an offline [`AGENTS.md`](#using-this-library-with-an-ai-agent) inside the package, a [per-agent map](#which-file-your-agent-reads) for **Claude Code**, **OpenAI Codex**, **GLM/z.ai**, **Cursor**, **Copilot**, **Gemini CLI** and the rest, `llms.txt` on the docs site, a Claude Code skill, and errors that name their own fix
+- 🤖 Built for AI agents too — one `npx vitest-auto-spy init` writes the pointer into the files your agents actually read and specialises it for this repository, backed by an offline [`AGENTS.md`](#using-this-library-with-an-ai-agent) inside the package, a [per-agent map](#which-file-your-agent-reads) for **Claude Code**, **OpenAI Codex**, **GLM/z.ai**, **Cursor**, **Copilot**, **Gemini CLI** and the rest, `llms.txt` on the docs site, a Claude Code skill, and errors that name their own fix
 - 🟢 100% test coverage, **zero runtime dependencies** (in-tree arg serializer, no `javascript-stringify`)
 
 ## Table of contents
@@ -69,6 +70,9 @@ identical API, with **RxJS** spies and **Angular / NestJS / React / Vue·Pinia /
 - [Install](#install)
   - [Requirements](#requirements)
   - [Peer dependencies](#peer-dependencies)
+- [The CLI — `doctor` and `init`](#the-cli--doctor-and-init)
+  - [`doctor` — defects that never fail](#doctor--defects-that-never-fail)
+  - [`init` — the pointer an agent reads](#init--the-pointer-an-agent-reads)
 - [Using this library with an AI agent](#using-this-library-with-an-ai-agent)
   - [Point your agent at it once](#point-your-agent-at-it-once)
   - [Which file your agent reads](#which-file-your-agent-reads)
@@ -112,6 +116,7 @@ identical API, with **RxJS** spies and **Angular / NestJS / React / Vue·Pinia /
     - [Shallow component rendering](#shallow-component-rendering)
     - [Building a class with auto-spied dependencies](#building-a-class-with-auto-spied-dependencies)
     - [Zoneless waiting](#zoneless-waiting)
+    - [Settling a `resource()` or `httpResource()`](#settling-a-resource-or-httpresource)
     - [Asserting a signal's value](#asserting-a-signals-value)
     - [Where a spec spends its time](#where-a-spec-spends-its-time)
   - [NestJS](#nestjs)
@@ -189,6 +194,65 @@ them only for the matching entry point. The package itself has **zero runtime de
 | `rxjs`          | `vitest-auto-spy/rxjs` observable spies (and `Spy<T>` type-checking) — `>=7`, **no upper bound** (the rxjs 8 line included) | yes       |
 | `@angular/core` | `vitest-auto-spy/angular` helpers                                                                                           | yes       |
 
+## The CLI — `doctor` and `init`
+
+The package ships one executable, with no dependencies and nothing to configure:
+
+```bash
+npx vitest-auto-spy doctor   # read-only. Exits 1 when it finds something
+npx vitest-auto-spy init     # writes the agent instructions pointer
+```
+
+### `doctor` — defects that never fail
+
+Every check shares one property: **nothing consumes the result**. The suite is green,
+`tsc --noEmit` reports zero errors, and the only reader of the stale thing is whoever opens the
+file. That is why they survive for years, and why a per-file linter cannot find most of them — the
+evidence is spread across files.
+
+```
+$ npx vitest-auto-spy doctor
+vitest-auto-spy doctor — /work/app
+1284 files, runner: vitest, entry: vitest-auto-spy/angular
+
+error  tsconfig-glob-matches-nothing libs/users/tsconfig.spec.json
+       The "include" pattern "src*.spec.ts" matches no file.
+       → A pattern that matches nothing type-checks nothing, and `tsc --noEmit` still reports
+         zero errors. Fix the glob or delete the entry.
+
+3 errors, 4 warnings, 1 note
+```
+
+| Check                          | What it finds                                                        |
+| ------------------------------ | -------------------------------------------------------------------- |
+| `tsconfig-glob-matches-nothing` | An `include` pattern that matches no file — so it type-checks nothing |
+| `tsconfig-file-missing`        | A `files` entry naming a file that is gone                            |
+| `spec-imported-by-non-spec`    | A production module importing a `*.spec.ts`                           |
+| `spec-exports-fixture`         | A spec importing another spec, whose hooks then run in a foreign file  |
+| `foreign-runner-pragma`        | `@jest-environment` left in a spec, which Vitest never reads           |
+| `dead-runner-config`           | `jest.config.*` / `karma.conf.*` for a runner that is not installed    |
+| `orphan-runner-file`           | A setup file only that dead config referenced                          |
+| `angular-build-splitting-off`  | `@angular/build` in `[22.1.5, 22.1.7)` — the OOM under `--coverage`    |
+| `no-agent-instructions`        | No instruction file names the package. A note, not an error            |
+
+The check that motivated the tool: a spec showing `Cannot find name 'vi'` in the editor while
+`tsc --noEmit` reported zero errors. A migration codemod editing `include` had eaten a `/**`,
+turning `src/**/*.spec.ts` into `src*.spec.ts` — a valid glob that matches nothing. Nine of 152
+spec tsconfigs still covered their specs.
+
+`doctor` never writes. There is no `--fix`.
+
+### `init` — the pointer an agent reads
+
+No coding agent scans dependencies for instructions, so the `AGENTS.md` and the skill shipped
+inside this package's tarball are never discovered on their own. `init` writes the pointer into
+the files that *are* read — `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, a Claude Code skill stub, and a
+glob-scoped rule file for each tool whose directory already exists — and specialises it for this
+repository's runner, framework and setup file. Everything sits between markers, so a re-run is a
+no-op and `--uninstall` puts the files back.
+
+Full reference, including the flags and the CI form: **[The CLI](https://asdalexey.github.io/vitest-auto-spy/utilities/cli)**.
+
 ## Using this library with an AI agent
 
 Most tests are now written with an assistant in the loop, so this package ships documentation
@@ -244,7 +308,14 @@ already exists.
 
 ### Install it in your agent
 
-Two commands at the repository root cover every tool in that table:
+One command covers every tool in that table, and specialises the text for this repository:
+
+```bash
+npx vitest-auto-spy init          # write it
+npx vitest-auto-spy init --check  # CI: fail when it is missing or out of date
+```
+
+By hand, the same thing is two commands at the repository root:
 
 ```bash
 # 1 — AGENTS.md: Codex, Cursor, Copilot, Cline, Windsurf, Zed, OpenCode, Qwen, Roo, Junie, Aider…
@@ -711,7 +782,7 @@ Node / Bun / React / Vue project pulls **neither rxjs nor Angular into its runti
 | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- | :----: |
 | `vitest-auto-spy`               | `createSpyFromClass`, `createAutoMock`, `createFunctionSpy`, sync + promise + accessor spies, `errorHandler`, types                                           | `vitest`                    |   ✅   |
 | `vitest-auto-spy/rxjs`          | observable spies (`nextWith`, `nextWithValues`, `observablePropsToSpyOn`, …) + `createObservableWithValues`                                                   | `rxjs`                      |   ✅   |
-| `vitest-auto-spy/angular`       | `provideAutoSpy`, `injectSpy`, `renderShallow`, `createWithAutoSpies`, `stable`/`flushEffects`, the `mock*Prop` helpers, signal matchers, TestBed diagnostics | `@angular/core`             |   ✅   |
+| `vitest-auto-spy/angular`       | `provideAutoSpy`, `injectSpy`, `renderShallow`, `createWithAutoSpies`, `stable`/`flushEffects`, `settleResource`, `mockResourceProp`, the `mock*Prop` helpers, signal & resource matchers, TestBed diagnostics | `@angular/core`             |   ✅   |
 | `vitest-auto-spy/bun`           | the same core, driven by Bun's `bun:test` mocks                                                                                                               | `bun:test`                  |   ✅   |
 | `vitest-auto-spy/bun-angular`   | Angular's `TestBed` under `bun test` — DOM, JIT `templateUrl` resolution and a zoneless environment, from one preload                                         | `bun:test`, `@angular/core` |   ✅   |
 | `vitest-auto-spy/node`          | the same core, driven by `node:test`'s `mock.fn()`                                                                                                            | `node:test`                 |   ✅   |
@@ -1255,6 +1326,60 @@ app the state that matters is signal-derived and effects are what move it forwar
 both, in the right order; `flushEffects` prefers `TestBed.tick()` (Angular ≥ 20) and falls back to
 `ApplicationRef.tick()`.
 
+The wait is bounded: `stable` gives the fixture **2000 ms** and then throws the cause, instead of
+letting the runner report a 5 s file-level timeout that names neither the helper nor the fixture.
+Pass `{ timeout, label }` to change either; `{ timeout: 0 }` waits indefinitely. The watchdog runs
+on a timer captured at import, so `vi.useFakeTimers()` cannot freeze it.
+
+#### Settling a `resource()` or `httpResource()`
+
+```ts
+import { flushEffects, settleResource } from 'vitest-auto-spy/angular';
+
+const products = TestBed.runInInjectionContext(() => httpResource<Product[]>(() => '/api/products'));
+
+flushEffects(); // the request is issued here — not when the resource was created
+TestBed.inject(HttpTestingController).expectOne('/api/products').flush([product]);
+await settleResource(products, { label: 'the product resource' });
+
+expect(products.value()).toEqual([product]);
+```
+
+Angular's resource primitives need a **different wait each** — measured on 21.2.17, an
+`httpResource` settles one tick + one microtask after its flush, a plain `resource()` takes two
+rounds of the same, and neither has made a request at all until something ticks. Getting it wrong
+asserts against the resource's _default_ value, which is a green test proving nothing.
+`settleResource` is the loop both converge under, with a turn budget and a failure that names the
+resource and the flush it is missing.
+
+`flushEventLoopUntil` cannot do this: it takes real event-loop turns and never ticks, so a resource
+awaited through it finishes the budget having issued zero requests.
+
+#### Driving a resource with no HTTP at all
+
+```ts
+import { mockResourceProp, registerResourceMatchers } from 'vitest-auto-spy/angular';
+
+const products = mockResourceProp(service, 'products', []);
+
+products.set([product]); // 'resolved'
+products.loading(); // back in flight
+products.fail('offline'); // 'error', error() is Error('offline')
+
+expect(products.reload).toHaveBeenCalled(); // reload is spied and re-issues nothing
+```
+
+Everything above is the answer when the request _is_ the point. Often it is not — the spec is about
+the component's own logic and the value was chosen in advance. `mockResourceProp` replaces the
+property with a double the spec moves directly, so nothing is ever in flight: no tick, no
+`HttpTestingController`, no budget. It is built from real `signal()`s, so a `computed()` reading
+`products.value()` still recomputes and an `effect()` still runs. Undone by `restoreMockedProps()`.
+
+And `registerResourceMatchers()` adds `toBeLoading` / `toHaveResourceValue` / `toHaveResourceError`,
+which read the value **and** the status. `toHaveResourceValue` is the one that earns its place: it
+fails an unresolved resource **even when its default value matches**, which is exactly the assertion
+`expect(products.value()).toEqual([])` lets through.
+
 #### Asserting a signal's value
 
 ```ts
@@ -1468,12 +1593,15 @@ single-purpose utility you can pick up independently — they all ride on the sa
 | `assertMocked(namespace, opts?)`                                                     | core                          | Fail when the `vi.mock()` a spec relies on silently did not apply (a bundled alias, `isolate: false`)                                                 |
 | `moduleNamespace(exports, opts?)`                                                    | core                          | The `vi.mock` factory result an interop probe recognises — `default` + `__esModule` in place                                                          |
 | `diffByField(actual, expected)`                                                      | core                          | Which field of an array of records moved, and in how many elements — the diff the reporter collapses                                                  |
+| `captureArg<T>()`                                                                    | core                          | Take hold of a callback or config the code under test built, instead of describing its shape — assertions only, never `calledWith` |
 | `asInstances(...spies)`                                                              | core                          | `asInstance` for a whole argument list — one edit against one compiler error, not five                                                                |
 | `narrow(value, guard)` / `narrow.byKey` / `narrow.observable`                        | core                          | The branch of a union a test knows it got, failing with the shape the value actually had                                                              |
 | `withOverrides(model, overrides?)`                                                   | core                          | A fixture from a model instance: its getters read once, as data — a spread drops them                                                                 |
 | `compareTestRuns(a, b, root?)`                                                       | core                          | Whether a migration lost a test — the set of `file::name`, which matching counters cannot answer                                                      |
 | `provideAutoSpyForToken(TOKEN, overrides?)`                                          | `/angular`                    | The provider for a dependency behind an `InjectionToken` — no stand-in class to write                                                                 |
 | `createDirectiveHost({ template, scope, props })`                                    | `/angular`                    | A standalone host for a directive under test, with its scope where the compiler reads it                                                              |
+| `mockResourceProp(obj, prop, initial)`                                               | `/angular`                    | Drive a resource with no HTTP — `set` / `fail` / `loading`, plus a spied `reload` |
+| `registerResourceMatchers()`                                                         | `/angular`                    | Adds `toBeLoading` / `toHaveResourceValue` / `toHaveResourceError`; the value matcher fails an unresolved resource |
 | `registerDirectiveMatchers()`                                                        | `/angular`                    | Adds `expect(fixture).toHaveDirectiveApplied(Directive, selector?)`                                                                                   |
 | `installProxyZonePatch(opts?)`                                                       | `/zone`                       | `fakeAsync` / `waitForAsync` on Vitest — the patch `zone.js/testing` does not ship; `scope: 'callback'` per callback                                  |
 | `autoMocked<T>(overrides?)`                                                          | core                          | `createAutoMock` typed as `T & Spy<T>`, for a collaborator passed as an argument rather than injected                                                 |
@@ -1931,7 +2059,8 @@ Both are the same object at runtime; only the view changes.
 | `describeDuplicateCopies()` / `getPackageCopies()`                                                           | The duplicate-install report, and the copies behind it                                                                                              |
 | `renderShallow(Component, opts?)` _(Angular)_                                                                | `TestBed` component, minus its children and (by default) its template                                                                               |
 | `createWithAutoSpies(Class, opts?)` _(Angular)_                                                              | Build a class through Angular DI with every unprovided token auto-spied                                                                             |
-| `stable(fixture)` / `flushEffects()` _(Angular)_                                                             | Zoneless waiting: flush effects, then await the fixture                                                                                             |
+| `stable(fixture, opts?)` / `flushEffects()` _(Angular)_                                                      | Zoneless waiting: flush effects, then await the fixture, with a 2 s budget that names the cause                                                      |
+| `settleResource(resource, opts?)` _(Angular)_                                                                | Tick until an `httpResource()` / `resource()` / `rxResource()` leaves `loading`                                                                      |
 | `registerSignalMatchers()` _(Angular)_                                                                       | Adds `expect(sig).toHaveSignalValue(value)`                                                                                                         |
 | `enableTestBedDiagnostics(opts?)` _(Angular)_                                                                | Per-file report of how much of a spec's time went into `TestBed`                                                                                    |
 | `setupAngularTestEnv(opts)` _(Angular)_                                                                      | Zone and zoneless spec files in one worker, switching platforms per file                                                                            |