vitest-auto-spy 3.7.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);             // ✅
 ```
 
 ---
@@ -1166,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
@@ -1215,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) } });
@@ -1338,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
@@ -1349,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
@@ -1377,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
@@ -1489,9 +1510,20 @@ 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:
@@ -1507,6 +1539,13 @@ that asserts too early asserts the default and passes. `settleResource` fails in
 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
@@ -1528,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.
 
 ---
 
@@ -1557,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
@@ -1918,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.7%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)
@@ -55,13 +55,14 @@ identical API, with **RxJS** spies and **Angular / NestJS / React / Vue·Pinia /
 - ⏳ 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)
@@ -190,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
@@ -245,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…
@@ -712,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`, `settleResource`, 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`                 |   ✅   |
@@ -1285,6 +1355,31 @@ 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
@@ -1498,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                                                 |

package/dist/angular.d.ts

@@ -1,8 +1,8 @@
-export { l as AngularTokenProvider, A as AngularValueProvider, a as AutoSpiedInstance, C as ComponentInputs, b as CreateWithAutoSpiesOptions, R as RenderShallowOptions, c as ResourceStatusLike, S as SettleResourceOptions, d as ShallowRender, e as SpyRegistry, f as StableOptions, g as createWithAutoSpies, h as flushEffects, i as injectSpy, p as provideAutoSpy, m as provideAutoSpyForToken, r as renderShallow, j as runEffect, s as settleResource, k as stable } from './zoneless-DbVZ96iR.js';
+export { l as AngularTokenProvider, A as AngularValueProvider, a as AutoSpiedInstance, C as ComponentInputs, b as CreateWithAutoSpiesOptions, R as RenderShallowOptions, c as ResourceStatusLike, S as SettleResourceOptions, d as ShallowRender, e as SpyRegistry, f as StableOptions, g as createWithAutoSpies, h as flushEffects, i as injectSpy, p as provideAutoSpy, m as provideAutoSpyForToken, r as renderShallow, j as runEffect, s as settleResource, k as stable } from './zoneless-Ch2Ym_6z.js';
 import { Type, Signal, WritableSignal } from '@angular/core';
-import { S as Spy, C as ClassType, a as ClassSpyConfiguration, O as OnlyMethodKeysOf } from './types-dZUFYsox.js';
-export { A as AccessorImplementations, R as RestoreProp, c as countMockedProps, m as mockAccessorsProp, a as mockReadonlyProp, b as mockReadonlyPropGetter, d as mockValueProp, r as restoreMockedProps } from './prop-mock-CKFksCvA.js';
-export { C as CallbackSubscribable, E as EmissionObserver, a as EmissionOptions, b as EmissionSource, S as SubscribableLike, e as expectCompletion, f as expectEmission, g as expectEmissions, h as expectError, i as expectNoEmission, s as setEmissionTimeout } from './expect-emission-RtR1iYgI.js';
+import { S as Spy, C as ClassType, a as ClassSpyConfiguration, O as OnlyMethodKeysOf, j as AddSpyMethodsByReturnTypes } from './types-W3lPrwC7.js';
+export { A as AccessorImplementations, R as RestoreProp, c as countMockedProps, m as mockAccessorsProp, a as mockReadonlyProp, b as mockReadonlyPropGetter, d as mockValueProp, r as restoreMockedProps } from './prop-mock-CeHqAeIG.js';
+export { C as CallbackSubscribable, E as EmissionObserver, a as EmissionOptions, b as EmissionSource, S as SubscribableLike, e as expectCompletion, f as expectEmission, g as expectEmissions, h as expectError, i as expectNoEmission, s as setEmissionTimeout } from './expect-emission-Cpj2GGcD.js';
 import '@angular/core/testing';
 import 'rxjs';
 import 'vitest';
@@ -39,9 +39,9 @@ interface AutoSpyOverride<T> {
  * An auto-spy wrapped as a `TestBed.overrideProvider` value.
  *
  * ```ts
- * const payments = overrideAutoSpy(PaymentToolService);
+ * const payments = overrideAutoSpy(PaymentMethodService);
  *
- * TestBed.configureTestingModule({ imports: [CheckoutComponent] }).overrideProvider(PaymentToolService, payments);
+ * TestBed.configureTestingModule({ imports: [CheckoutComponent] }).overrideProvider(PaymentMethodService, payments);
  * payments.useValue.charge.resolveWith({ ok: true });
  * ```
  *
@@ -58,7 +58,7 @@ declare function overrideAutoSpy<T>(ObjectClass: ClassType<T>, methodsToSpyOnOrC
  * a component the testing module never mentions is never compiled by it.
  *
  * ```ts
- * const menu = overrideComponentProvider(SmartVodComponent, MenuBuilderService);
+ * const menu = overrideComponentProvider(CatalogPageComponent, NavigationBuilderService);
  *
  * menu.build.mockReturnValue([]);                 // the component's own provider is now the spy
  * const fixture = TestBed.createComponent(HostComponent);
@@ -212,6 +212,112 @@ declare module 'vitest' {
  */
 declare function registerDirectiveMatchers(): void;
 
+/**
+ * Driving an Angular resource from a spec, without any HTTP at all.
+ *
+ * `httpResource()` and `resource()` are the primitives a modern Angular service exposes, and a spec
+ * that wants to assert "the component shows the empty state while products are loading" has, until
+ * now, had to produce that state the long way: configure `provideHttpClientTesting`, tick so the
+ * request is issued, find it on the `HttpTestingController`, flush it, then settle. Six steps and a
+ * real request, to arrive at a value the spec picked in advance.
+ *
+ * {@link settleResource} is the answer when the request is the point. This is the answer when it is
+ * not — the shallow one, for a suite that tests business logic and never wanted a request in the
+ * first place. The property is replaced by a hand-built double whose statuses the spec sets
+ * directly, so nothing is ever in flight and there is nothing to wait for: no tick, no flush, no
+ * budget, and no way for the test to pass against a resource's default value by accident.
+ *
+ * Reactivity is genuine, exactly as in {@link mockSignalProp}: the double is built out of real
+ * `signal()`s from `@angular/core`, so a `computed()` reading `products.value()` recomputes and an
+ * `effect()` watching `products.status()` runs. A plain object with the same keys would satisfy
+ * every read and notify nothing.
+ *
+ * `@angular/core` stays an optional peer the same way the rest of this surface does: `ResourceRef`
+ * is only ever a *type* here, and the value handed to the property is assembled from `signal()`.
+ */
+
+/**
+ * The resource statuses Angular defines, as a string union.
+ *
+ * Declared here rather than imported so this module keeps `@angular/core` to a type-only
+ * dependency in spirit as well as in fact — Angular moved this from an enum to a union in v20, and
+ * a local union works against both without a version guard.
+ */
+type ResourceDoubleStatus = 'error' | 'idle' | 'loading' | 'local' | 'reloading' | 'resolved';
+/**
+ * The double installed on the property — the slice of `ResourceRef` a component actually reads.
+ *
+ * Structural on purpose: a component typed against `ResourceRef<T>` reads `value`, `status`,
+ * `error`, `isLoading`, `hasValue` and `reload`, and this provides all six with the same shapes.
+ * The members `ResourceRef` has that a *consumer* never calls — `asReadonly`, `destroy`, `update` —
+ * are deliberately absent, because a double that answers a call nobody should be making is how a
+ * typo survives a test run.
+ */
+interface ResourceDouble<TValue> {
+    /** The current value. Writable through the returned handle, readonly to the code under test. */
+    value: Signal<TValue>;
+    /** `'resolved'` unless the spec moved it — see {@link MockedResource.loading} / `fail`. */
+    status: Signal<ResourceDoubleStatus>;
+    /** The error behind an `'error'` status, `undefined` otherwise. */
+    error: Signal<Error | undefined>;
+    /** `true` while the status is `'loading'` or `'reloading'`, matching Angular's own derivation. */
+    isLoading: Signal<boolean>;
+    /** `true` when the status is `'resolved'` or `'local'` — that is, when `value()` means anything. */
+    hasValue(): boolean;
+    /** Spied, and inert: a double has no request to re-issue, so the spec asserts the call instead. */
+    reload: AddSpyMethodsByReturnTypes<() => boolean>;
+}
+/** The spec's handle on a resource installed by {@link mockResourceProp}. */
+interface MockedResource<TValue> {
+    /** Resolve the resource with a value — status `'resolved'`, error cleared. */
+    set(value: TValue): void;
+    /** Fail the resource — status `'error'`, `error()` set, `hasValue()` false. */
+    fail(error: Error | string): void;
+    /** Put the resource back in flight — status `'loading'`, `hasValue()` false. */
+    loading(): void;
+    /** The spied `reload()`; `expect(products.reload).toHaveBeenCalled()`. */
+    reload: AddSpyMethodsByReturnTypes<() => boolean>;
+    /** The double now behind the property, for asserting on it directly. */
+    resource: ResourceDouble<TValue>;
+}
+/**
+ * Replace a resource-valued property with a double the spec drives directly.
+ *
+ * ```ts
+ * const service = injectSpy(ProductService);
+ * const products = mockResourceProp(service, 'products', []);
+ *
+ * expect(component.emptyState()).toBe(true);
+ *
+ * products.set([product]);
+ * await stable(fixture);
+ *
+ * expect(component.emptyState()).toBe(false);
+ *
+ * products.fail('offline');
+ * expect(component.errorMessage()).toBe('offline');
+ * ```
+ *
+ * The resource starts `'resolved'` at `initialValue`, because that is the state a spec asserts
+ * against most and the one it would otherwise have to arrange. `loading()` and `fail()` are how the
+ * other two states are reached, and each is a single synchronous call — the point of this helper is
+ * that there is no asynchrony to get wrong. When a spec *does* want the real request path, that is
+ * `settleResource` over a real `httpResource`, not this.
+ *
+ * Undone by `restoreMockedProps()` like every other property patch, so a suite running
+ * `setupAutoSpy()` needs no teardown of its own.
+ *
+ * @param object The spy (or real instance) whose property to replace.
+ * @param property The resource-valued property.
+ * @param initialValue The value the resource starts resolved at.
+ * @returns The handle driving that resource — `set` / `fail` / `loading`, plus the spied `reload`.
+ */
+declare function mockResourceProp<T, K extends keyof T>(object: T, property: K, initialValue: T[K] extends {
+    value: Signal<infer TValue>;
+} ? TValue : never): MockedResource<T[K] extends {
+    value: Signal<infer TValue>;
+} ? TValue : never>;
+
 /**
  * Driving a service's signal from a spec.
  *
@@ -264,6 +370,42 @@ declare function registerDirectiveMatchers(): void;
  */
 declare function mockSignalProp<T, K extends keyof T>(object: T, property: K, initialValue: T[K] extends Signal<infer TValue> ? TValue : never): WritableSignal<T[K] extends Signal<infer TValue> ? TValue : never>;
 
+/** The slice of a resource these matchers read. `error` is absent on some hand-built doubles. */
+interface ResourceLike<TValue = unknown> {
+    status(): string;
+    value(): TValue;
+    error?(): Error | undefined;
+}
+declare module 'vitest' {
+    interface Matchers<T = any> {
+        /** The resource is still in flight — `status()` is `'loading'` or `'reloading'`. */
+        toBeLoading(): T;
+        /** The resource has resolved *and* its value deep-equals the expected one. */
+        toHaveResourceValue(expected: unknown): T;
+        /** The resource has failed; with an argument, its error message matches too. */
+        toHaveResourceError(expected?: RegExp | string): T;
+    }
+}
+/**
+ * Register the resource matchers with the runner. Call once, from your setup file.
+ *
+ * @example
+ * ```ts
+ * registerResourceMatchers(); // once, in the setup file
+ *
+ * expect(component.products).toBeLoading();
+ *
+ * httpTesting.expectOne('/api/products').flush([product]);
+ * await settleResource(component.products);
+ *
+ * expect(component.products).toHaveResourceValue([product]);
+ * ```
+ *
+ * `toHaveResourceValue` deliberately fails a resource that is still loading even when its default
+ * value happens to match, because that is the assertion this whole family exists to stop passing.
+ */
+declare function registerResourceMatchers(): void;
+
 /** Anything readable like a signal: `signal()`, `computed()`, `input()`, or a plain getter. */
 type SignalLike<T> = () => T;
 declare module 'vitest' {
@@ -378,4 +520,4 @@ declare function reportSpecTiming(timing: SpecTiming): void;
  */
 declare function enableTestBedDiagnostics(options?: TestBedDiagnosticsOptions): void;
 
-export { type AngularTestEnvMode, type AngularTestEnvOptions, type AutoSpyOverride, type DirectiveHostOptions, type SignalLike, type SpecTiming, type TestBedDiagnosticsOptions, assertNgModuleScopes, createDirectiveHost, disableTestBedDiagnostics, enableTestBedDiagnostics, formatSpecTiming, getTestBedTiming, instrumentTestBed, mockSignalProp, overrideAutoSpy, overrideComponentProvider, registerDirectiveMatchers, registerSignalMatchers, reportSpecTiming, setupAngularTestEnv };
+export { type AngularTestEnvMode, type AngularTestEnvOptions, type AutoSpyOverride, type DirectiveHostOptions, type MockedResource, type ResourceDouble, type ResourceDoubleStatus, type ResourceLike, type SignalLike, type SpecTiming, type TestBedDiagnosticsOptions, assertNgModuleScopes, createDirectiveHost, disableTestBedDiagnostics, enableTestBedDiagnostics, formatSpecTiming, getTestBedTiming, instrumentTestBed, mockResourceProp, mockSignalProp, overrideAutoSpy, overrideComponentProvider, registerDirectiveMatchers, registerResourceMatchers, registerSignalMatchers, reportSpecTiming, setupAngularTestEnv };