vitest-auto-spy 3.14.0 → 3.15.1

package/AGENTS.md

@@ -51,14 +51,14 @@ adapter installed and spies fail at runtime.
 
 Five add-ons, orthogonal to the runner:
 
-| Add-on           | Import                          | Needed for                                                                                                                     |
-| ---------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
-| Observable spies | `import 'vitest-auto-spy/rxjs'` | `nextWith` & friends. **Side-effect import, once.** |
-| observer-spy shim | `vitest-auto-spy/observer-spy` | `subscribeSpyTo` — the `@hirez_io/observer-spy` surface (§20). Its own entry so `/rxjs` does not carry it |
-| Console spies    | `vitest-auto-spy/console`       | silent typed spies over the global `console`                                                                                   |
-| Setup helpers    | `vitest-auto-spy/setup`         | `setupAutoSpy()`, `setupFakeTimers()`                                                                                          |
-| Zone patch       | `import 'vitest-auto-spy/zone'` | `fakeAsync` / `waitForAsync` on Vitest (§14)                                                                                   |
-| jasmine compat   | `vitest-auto-spy/jasmine`       | `.and` / `.calls` / `.withArgs`, the `jasmine` namespace (§20)                                                                 |
+| Add-on            | Import                          | Needed for                                                                                                |
+| ----------------- | ------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| Observable spies  | `import 'vitest-auto-spy/rxjs'` | `nextWith` & friends. **Side-effect import, once.**                                                       |
+| observer-spy shim | `vitest-auto-spy/observer-spy`  | `subscribeSpyTo` — the `@hirez_io/observer-spy` surface (§20). Its own entry so `/rxjs` does not carry it |
+| Console spies     | `vitest-auto-spy/console`       | silent typed spies over the global `console`                                                              |
+| Setup helpers     | `vitest-auto-spy/setup`         | `setupAutoSpy()`, `setupFakeTimers()`                                                                     |
+| Zone patch        | `import 'vitest-auto-spy/zone'` | `fakeAsync` / `waitForAsync` on Vitest (§14)                                                              |
+| jasmine compat    | `vitest-auto-spy/jasmine`       | `.and` / `.calls` / `.withArgs`, the `jasmine` namespace (§20)                                            |
 
 `vitest-auto-spy/jasmine` is Vitest-only, because it registers the Vitest adapter. On `bun test` and
 `node --test` call `enableJasmineCompat()` from `vitest-auto-spy/jasmine-compat` instead.
@@ -349,7 +349,7 @@ Every spied method is a real runner mock, so `mockReturnValue`, `mockImplementat
 
 | Return type     | Helpers added                                                                                                                               |
 | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
-| anything        | `calledWith(...args)` → `.mockReturnValue(v)` / `.returnValue(v)`, `mustBeCalledWith(...args)` → same                                       |
+| anything        | `calledWith(...args)` → `.mockReturnValue(v)` / `.returnValue(v)` / `.failWith(err)`, `mustBeCalledWith(...args)` → same, `failWith(err)`   |
 | `Promise<T>`    | `resolveWith(v)`, `rejectWith(v)`, `resolveWithPerCall([{ value }, …])`                                                                     |
 | `Observable<T>` | `nextWith(v)`, `nextOneTimeWith(v)`, `nextWithValues(configs)`, `nextWithPerCall(configs)`, `throwWith(v)`, `complete()`, `returnSubject()` |
 
@@ -379,8 +379,24 @@ feed.items$.nextWithValues([{ value: a }, { value: b, delay: 100 }, { complete:
 const [first$, second$] = feed.watch$.nextWithPerCall([{ value: 'a' }, { value: 'b', doNotComplete: true }]);
 feed.items$.throwWith('FAKE ERROR');
 const subject = feed.items$.returnSubject(); // ReplaySubject, for anything the helpers miss
+
+// throwing — `failWith`, on a spy of any return type
+cart.checkout.failWith(new HttpErrorResponse({ status: 500 })); // every call throws
+cart.checkout.calledWith(BAD_ID).failWith(new Error('unknown cart')); // only these arguments throw
 ```
 
+`failWith` is the sync counterpart of `rejectWith`, and it is **not** called `throwWith` — that name
+belongs to the observable helper above, which errors the stream. At runtime every spy carries every
+bundle; only the return type in `Spy<T>` tells them apart, so one name for both would mean whichever
+is attached last silently wins.
+
+On Vitest, `mockThrow` / `mockThrowOnce` (4.1) do the spy-level half of this too. `failWith` exists
+because Bun and `node:test` ship neither, and because **no** runtime can make one `calledWith` chain
+throw while its siblings answer normally — `mockImplementation` replaces the whole dispatch, which is
+the opposite of configuring one set of arguments. A `failWith` supersedes a `resolveWith` /
+`nextWith` / per-call batch configured before it, and is superseded by one configured after, so the
+outcome never depends on the order the spec happens to be written in.
+
 An exact argument list is matched before the asymmetric configs, and those are tried in
 registration order — a narrow config written first keeps its calls. Two matchers count as the same
 argument when they accept the same values (same matcher class, sample and inversion), which is what
@@ -922,7 +938,21 @@ setupAutoSpy({ strayTimers: true }); // wrap the schedulers, sweep the survivors
 The pieces are exported too — `trackStrayTimers()` (idempotent, returns the undo),
 `cancelStrayTimers()` (returns how many it cancelled) and `countStrayTimers()`, all from
 `vitest-auto-spy/setup`. Use `expect(countStrayTimers()).toBe(0)` in an `afterEach` to make a leak
-fail rather than be tidied away.
+fail rather than be tidied away, or take the per-file count from the sweep itself:
+
+```ts
+setupAutoSpy({ strayTimers: true, onStrayTimers: ({ cancelled }) => expect(cancelled).toBe(0) });
+```
+
+**With Vitest 4.1's `--detect-async-leaks`, run one or the other — not both silently.** The two
+arrive at the same timer from opposite ends and the quiet one wins: the sweep cancels in `afterAll`,
+Vitest collects its leaks afterwards, and a cancelled timeout is no longer referenced, so the run
+reports **no leaks** for a file that leaks. Cancelling is still the right default — a callback firing
+during a later file is the more expensive failure — so when both are on and no `onStrayTimers` is
+given, the sweep prints one line to stderr saying how many it took away. To see _where_ each one was
+scheduled, re-run that file with `strayTimers` off and read Vitest's report; the code frame points
+at the `setTimeout` in the spec, because the library's own scheduler wrappers go through
+`vi.defineHelper` and are dropped from the stack.
 
 **The one that keeps a suite green while it is wrong:** zone.js replaces the global `Promise`, and a
 rejection nobody handled is drained into `console.error` and no further — it never reaches
@@ -944,6 +974,12 @@ undo), `flushStrayRejections()` (takes what was captured and starts again from e
 `countStrayRejections()`. The `no-floating-assertion` lint rule catches the commonest shape before
 it ever runs (§16).
 
+**`onUnhandledError` is not this.** Vitest 4.0 added a config callback for errors the _runner_ hears
+about, and under zone.js the runner never hears about these at all — zone.js drains the rejection
+into `console.error` before `process.on('unhandledRejection')` would fire, so there is nothing for
+that callback to filter. Use `onUnhandledError` to triage the native failures Vitest already reports;
+use `strayRejections` to find the ones it never sees.
+
 A rejection the runner has **already** blamed the finished test for is not reported again. An
 `async` test that fails an assertion leaves its own `AssertionError` in both places, so a red run
 used to print two messages per failure and the second one sent the reader hunting for a defect that
@@ -1354,6 +1390,44 @@ const myService = injectSpy(MyService); // Spy<MyService>
 `{ lazySpies: false }` to opt out. The spies never touch `NgZone`, so they work zoneless and with
 zone.js alike.
 
+### The same thing as fixtures — `extendWithAutoSpies` (Vitest 4.1+)
+
+The block above, written once instead of once per dependency, with the types inferred rather than
+declared:
+
+```ts
+import { test as base } from 'vitest';
+import { extendWithAutoSpies } from 'vitest-auto-spy/angular';
+
+const test = extendWithAutoSpies(base, {
+  cart: CartService,
+  api: [ApiService, { returns: { get: of([]) } }],
+  passcode: PASSCODE_TOKEN,
+});
+
+test('checks out', async ({ cart }) => {
+  cart.checkout.resolveWith(true);
+
+  await expect(cart.checkout(1)).resolves.toBe(true);
+});
+```
+
+No `let cart: Spy<CartService>` that is `undefined` between tests, and a test that never destructures
+`api` never builds it. Entries are a class, `[Class, config]` with whatever `provideAutoSpy` takes,
+or an `InjectionToken` (built from the token's own type, like `provideAutoSpyForToken`). Extra
+providers — the component under test, a real service, `provideHttpClient()` — go in the third
+argument and are registered in the same call, ahead of the generated ones, so a token named there
+wins.
+
+**It takes the whole map at once, and that is a `TestBed` constraint rather than a typing one.** The
+composing form — `base.extend('cart', …).extend('api', …)` — cannot work: fixtures resolve
+independently, so `cart` would configure the testing module _and_ inject, which instantiates it, and
+`api` would then reach `configureTestingModule` after instantiation and fail with Angular's own
+"Cannot configure the test module when the test module has already been instantiated". A `beforeEach`
+that configures the module further still composes, because it runs before any fixture resolves and
+repeated `configureTestingModule` calls merge right up until the first injection. A `beforeEach` that
+**injects** does not, and nothing can repair that from here.
+
 The token may be an **abstract class** — `abstract class LocalStorage extends AbstractStorage {}`,
 the shape production provides with `useClass`. Its members are erased before they reach a prototype,
 so there is nothing to discover; the factory notices and returns the `createAutoMock` proxy, which
@@ -1958,6 +2032,7 @@ export default [{ files: ['**/*.spec.ts'], ...autoSpy.configs.recommended }];
 | `prefer-as-spy`                   | `warn`  | `--fix`           | `TestBed.inject(X) as Spy<X>` → `asSpy<X>(TestBed.inject(X))`, import and all                                                             |
 | `no-done-callback`                | `error` | —                 | `it('x', (done) => …)` → `async` + an awaited assertion, and `done.fail(…)` at the call site                                              |
 | `no-floating-assertion`           | `error` | —                 | `expect()` in a `.then()` nobody awaits → `expect(await promise)`                                                                         |
+| `no-bare-called-with`             | `error` | —                 | `spy.m.calledWith(1);` as a statement — a stub nobody continued, asserting nothing; chai's `expect(fn).to.have.been.calledWith()` exempt  |
 | `no-overridden-provider`          | `error` | suggest           | two providers for one token in one array → the earlier one never runs; the exact duplicate can be deleted                                 |
 | `no-inject-before-override`       | `warn`  | —                 | `TestBed.inject()` in a hook, in a suite that still calls `override*`                                                                     |
 | `no-import-time-spread`           | `error` | suggest           | `export const x = [...Imported]` at module scope → a `TypeError` while the bundle loads                                                   |
@@ -1967,10 +2042,10 @@ export default [{ files: ['**/*.spec.ts'], ...autoSpy.configs.recommended }];
 | `no-save-arguments-by-value`      | `error` | —                 | `spy.calls.saveArgumentsByValue()` — a no-op here, so the spec silently asserts on post-mutation state                                    |
 | `prefer-native-spy-api`           | `off`   | `--fix` / suggest | `.and` / `.calls` where the spy's own API says the same thing — turn it on for the last mile off the jasmine shim                         |
 
-Eighteen rules; three fix on their own, seven offer suggestions. The last four are for a suite
+Nineteen rules; three fix on their own, seven offer suggestions. The last four are for a suite
 mid-migration off `jasmine-auto-spies` (§20); `prefer-native-spy-api` is **off** in the recommended
 config because it reports working code — the compatibility layer is what a suite runs on while it is
-being migrated. `no-mocked-for-spy` only ever touches a `no-mocked-for-spy` only ever touches a
+being migrated. `no-mocked-for-spy` only ever touches a
 **type position**, where a wrong rewrite is a compile error rather than a test that quietly changed
 meaning — so `--fix` renames the type, adds `import type { Spy } from 'vitest-auto-spy'` and drops
 the orphaned `Mocked` import. Every type position, not only a `let`: a factory's return type, a
@@ -2096,6 +2171,7 @@ packages, which a subpath export can never be.
 | a `.withContext('…')` message that never appears in the failure output                       | Vitest's chai layer has an `@internal` `withContext(flags)`; handed a string it walks the character indices, sets nonsense flags and returns `this`  | `expect(actual, 'message').toBe(expected)` — the second argument of `expect` is the label. Nothing throws, so nothing warns (§20) |
 | `requested method(s) not found on the class prototype`                                       | typo, or an instance-field callable                                                                                                                  | fix the name, or move it to `instanceMethodsToSpyOn`                                                                              |
 | `was configured with 'mustBeCalledWith'`                                                     | the code called the spy with other arguments                                                                                                         | that is the assertion firing — fix the code, or relax to `calledWith`                                                             |
+| `extendWithAutoSpies needs Vitest 4.1 or newer`                                              | the `test` handed in has only the object-form `extend` (Vitest ≤ 4.0); the builder form the helper is written against arrived in 4.1                 | upgrade Vitest, or keep `provideAutoSpy` + `injectSpy` in a `beforeEach` until then                                               |
 | `advanceTimers() requires fake timers`                                                       | no fake timers installed                                                                                                                             | `setupFakeTimers()` or `vi.useFakeTimers()` first                                                                                 |
 | `Nothing configured X.method, and strict mode is on`                                         | a strict double was asked for a method no line configured                                                                                            | configure it (`mockReturnValue` / `resolveWith` / `nextWith` / `calledWith`), or `{ strict: false }` on that double (§5)          |
 | `Cannot redefine property: …` from a library accessor spy                                    | the target is an ES module namespace a bundler inlined                                                                                               | no spy library can win this — give the code a real seam (inject it, pass it in) and spy on that                                   |
@@ -2159,6 +2235,8 @@ packages, which a subpath export can never be.
 | two runs with the same totals, one of them missing a suite                                   | a lost `describe` and a fixed flake cancel out in the counters                                                                                       | `compareTestRuns(before, after)` — compare the set of names, not the numbers                                                      |
 | a 30 s timeout, in a different file each run                                                 | module-level `vi.fn()` in a fixture shared by files                                                                                                  | make the fixture a factory (§10)                                                                                                  |
 | a component's `afterNextRender` state is empty                                               | `detectChanges()` does not run the after-render phase                                                                                                | `await stable(fixture)` (§11)                                                                                                     |
+| a green test whose only line about a call is `spy.m.calledWith(1);`                          | that is a **stub**, not an assertion — chai's `expect(fn).to.have.been.calledWith(x)` is the one that checks                                         | continue the chain, or `expect(spy.m).toHaveBeenCalledWith(1)` — `no-bare-called-with` (§16)                                      |
+| `--detect-async-leaks` reporting no leaks in a suite that visibly leaks timers               | `setupAutoSpy({ strayTimers: true })` cancelled them before Vitest collected                                                                         | re-run that file with `strayTimers` off; the warning on stderr says how many were taken (§10)                                     |
 
 **Seven of these are library defects, not spec ones.** On anything below 3.8.0, upgrade and change
 nothing in the spec: `of(double)` never emitting; `accessorSpies.setters.X` still `undefined` after
@@ -2242,6 +2320,14 @@ npx tsc --noEmit                      # Spy<T> mistakes are compile errors, not
 npx vitest-auto-spy doctor            # suite-level defects that never fail a run
 ```
 
+**If you are an agent, add `--reporter=agent`** (Vitest 4.1). It is Vitest's own reporter, added for
+exactly this: the same failures, without the passing-test roll call and the repeated banners that
+make a run's output expensive to read and expensive to carry.
+
+```bash
+npx vitest run --reporter=agent path/to/file.spec.ts
+```
+
 Type errors matter here more than usual: most of this library's guarantees are type-level, so a
 suite that runs green but does not type-check is not done.
 

package/README.md

@@ -19,7 +19,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-14.9%20kB-brightgreen)](#install)
+[![minzipped size](https://img.shields.io/badge/minzip-15.1%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)
@@ -63,7 +63,7 @@ identical API, with **RxJS** spies and **Angular / NestJS / React / Vue·Pinia /
 - 🧩 Module mocks that prove they applied — `assertMocked`, `moduleNamespace`, for a `vi.mock()` a bundler quietly ignored
 - 🧾 Fixtures without casts — deep-partial `createMock`, `createFixture` / `createFixtureFactory`, `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 — eighteen rules in `vitest-auto-spy/eslint-plugin` (three `--fix`, seven suggestions, four of them for a suite mid-migration off jasmine), `setupAutoSpy()`
+- 📏 Lint rules and one-line test-run hygiene — nineteen rules in `vitest-auto-spy/eslint-plugin` (three `--fix`, seven suggestions, four of them for a suite mid-migration off jasmine), `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-codemod-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
 - 🚚 [`npx vitest-auto-spy codemod`](#codemod--migrating-a-suite-off-jest-auto-spies) — thirteen transforms that move a suite off `jest-auto-spies` and Jest, or off `jasmine-auto-spies` and jasmine (`--from jasmine`), dry-run by default, with a `--verify` pass that also checks a file somebody edited by hand
@@ -604,6 +604,23 @@ cart.total.mockReturnValue(42);
 `CartService` and the spy has it. A hand-written `{ provide: CartService, useValue: { total:
 vi.fn() } }` silently keeps mocking yesterday's class.
 
+On **Vitest 4.1+**, the same thing as fixtures — one statement, types inferred, and a test that
+never names a dependency never builds it:
+
+```ts
+import { test as base } from 'vitest';
+import { extendWithAutoSpies } from 'vitest-auto-spy/angular';
+
+const test = extendWithAutoSpies(base, { cart: CartService, api: [ApiService, { returns: { get: of([]) } }] });
+
+test('checks out', ({ cart }) => cart.total.mockReturnValue(42));
+```
+
+It takes the whole map at once because every provider has to be known before the first injection —
+[why, in full](https://asdalexey.github.io/vitest-auto-spy/adapters/angular#fixtures-instead-of-let-beforeeach-extendwithautospies).
+On an older Vitest it throws `needs Vitest 4.1 or newer` up front, instead of letting the object-form
+`extend` register nonsense and every test die on `undefined`.
+
 ### How to mock: a service without DI
 
 ```ts
@@ -668,6 +685,18 @@ Not `source$.subscribe(value => expect(value).toEqual(…))`: if the stream neve
 never runs, nothing is asserted, and the test is green and empty. `expectEmission` **is** the
 assertion — a silent stream fails it, with the stream's name and the timeout in the message.
 
+### How to mock: a call that has to throw
+
+```ts
+cart.checkout.failWith(new HttpErrorResponse({ status: 500 })); // every call throws
+cart.checkout.calledWith(BAD_ID).failWith(new Error('unknown cart')); // only these arguments
+```
+
+`failWith` works on a spy of any return type. Vitest 4.1's `mockThrow` covers the first line; Bun
+and `node:test` have no equivalent, and **no** runtime has one for the second — `mockImplementation`
+replaces the whole dispatch, which is the opposite of configuring one set of arguments. It is not
+called `throwWith` because that name already means _error the stream_ on an observable spy.
+
 ### How to mock: a promise a test forgets to await
 
 ```ts
@@ -2235,20 +2264,21 @@ expensive to diagnose when it is missing. The first three are on by default:
     timer in sight: a request matching no Express route is ended by `finalhandler` on `setImmediate`,
     so the 404 is never written and a routing mistake is reported as a slow test.
 
-| Option                | Default   | Notes                                                                           |
-| --------------------- | --------- | ------------------------------------------------------------------------------- |
-| `duplicateCopies`     | `'throw'` | `'warn'` to report without failing, `'off'` to skip the check                   |
-| `restoreProps`        | `true`    | `restoreMockedProps()` in a global `afterEach`                                  |
-| `restoreMocks`        | `false`   | `vi.restoreAllMocks()` in a global `afterEach` — turn on for `isolate: false`   |
-| `strayTimers`         | `false`   | Cancel timeouts, intervals and frames that outlive their file                   |
-| `strayRejections`     | `false`   | Fail the test a rejection zone.js swallowed surfaced in — needs zone.js         |
-| `blockNetwork`        | `false`   | Close every network channel the environment has — `true`, or a narrowing object |
-| `guardGlobals`        | `'off'`   | Report a test that redefines a global property as non-configurable              |
-| `globalFakeTimers`    | `false`   | Fake timers for every test **and between them** — Jest's `enableGlobally`       |
-| `restoreTimerGlobals` | `true`    | Put back timer globals that uninstalling the fakes deleted                      |
-| `pruneMockRegistry`   | `false`   | Keep @vitest/spy's ever-growing mock registry to the mocks that outlive a file  |
-| `hookTimeoutHint`     | `true`    | Explain a hook that ran out of `hookTimeout` while `testTimeout` is larger      |
-| `frozenClockHint`     | `true`    | Explain a timeout that happened because nothing advanced the fake clock         |
+| Option                | Default   | Notes                                                                                 |
+| --------------------- | --------- | ------------------------------------------------------------------------------------- |
+| `duplicateCopies`     | `'throw'` | `'warn'` to report without failing, `'off'` to skip the check                         |
+| `restoreProps`        | `true`    | `restoreMockedProps()` in a global `afterEach`                                        |
+| `restoreMocks`        | `false`   | `vi.restoreAllMocks()` in a global `afterEach` — turn on for `isolate: false`         |
+| `strayTimers`         | `false`   | Cancel timeouts, intervals and frames that outlive their file                         |
+| `onStrayTimers`       | —         | Takes the per-file count the sweep cancelled — see the note on `--detect-async-leaks` |
+| `strayRejections`     | `false`   | Fail the test a rejection zone.js swallowed surfaced in — needs zone.js               |
+| `blockNetwork`        | `false`   | Close every network channel the environment has — `true`, or a narrowing object       |
+| `guardGlobals`        | `'off'`   | Report a test that redefines a global property as non-configurable                    |
+| `globalFakeTimers`    | `false`   | Fake timers for every test **and between them** — Jest's `enableGlobally`             |
+| `restoreTimerGlobals` | `true`    | Put back timer globals that uninstalling the fakes deleted                            |
+| `pruneMockRegistry`   | `false`   | Keep @vitest/spy's ever-growing mock registry to the mocks that outlive a file        |
+| `hookTimeoutHint`     | `true`    | Explain a hook that ran out of `hookTimeout` while `testTimeout` is larger            |
+| `frozenClockHint`     | `true`    | Explain a timeout that happened because nothing advanced the fake clock               |
 
 `restoreMocks` is off by default because it also drops `vi.spyOn` stubs a suite installed in
 `beforeAll`; it is the knob to reach for when the run shares one environment across files.
@@ -2395,6 +2425,7 @@ export can never be.
 | `prefer-as-spy`                   |   `warn`    | `--fix`           | `TestBed.inject(X) as Spy<X>` → `asSpy<X>(TestBed.inject(X))`, import and all                                                              |
 | `no-done-callback`                |   `error`   | —                 | `it('x', (done) => …)` → `async` + an awaited assertion, and `done.fail(…)` at the call site                                               |
 | `no-floating-assertion`           |   `error`   | —                 | `expect()` in a `.then()` nobody awaits → `expect(await promise)`                                                                          |
+| `no-bare-called-with`             |   `error`   | —                 | `spy.m.calledWith(1);` as a statement of its own — a stub nobody continued, asserting nothing                                              |
 | `no-overridden-provider`          |   `error`   | suggest           | two providers for one token in one array → the earlier one never runs; the exact duplicate can be deleted                                  |
 | `no-inject-before-override`       |   `warn`    | —                 | `TestBed.inject()` in a hook, in a suite that still calls `override*`                                                                      |
 | `no-import-time-spread`           |   `error`   | suggest           | `export const x = [...Imported]` at module scope → a `TypeError` while the bundle loads                                                    |
@@ -2408,7 +2439,7 @@ Every message ends with a link to the matching [recipe](#how-to-mock): a rule th
 "don't" moves the problem rather than solving it. Rules travel with the API they recommend, so they
 are versioned together and stop being re-written in every project that installs the package.
 
-**Three of the eighteen fix on their own, seven offer suggestions**, and the split is not about how hard
+**Three of the nineteen fix on their own, seven offer suggestions**, and the split is not about how hard
 the rewrite is. `no-mocked-for-spy` touches a _declaration_: get it wrong and the file stops
 compiling, which is the loudest, cheapest failure there is — so `--fix` rewrites the type, adds
 `import type { Spy } from 'vitest-auto-spy'` and drops the `Mocked` import once nothing else uses
@@ -2510,7 +2541,7 @@ package's own — it needs its ESLint integration switched on.
 ### WebStorm and the other JetBrains IDEs
 
 No plugin to install: WebStorm, IntelliJ IDEA Ultimate, PhpStorm, PyCharm Professional and RubyMine
-all run ESLint natively, so the eighteen rules appear inline, in the **Problems** tool window, and
+all run ESLint natively, so the nineteen rules appear inline, in the **Problems** tool window, and
 under **Code → Inspect Code** for the whole project.
 
 ```js
@@ -2527,7 +2558,7 @@ has supported flat config since 2023.3); scope the block to spec files yourself;
 the fixes and suggestions live.
 
 A native JetBrains plugin is **not** planned — it would duplicate an integration the IDE already has
-and then keep a second copy of eighteen rules, in Kotlin, in step with the TypeScript ones.
+and then keep a second copy of nineteen rules, in Kotlin, in step with the TypeScript ones.
 
 ### VS Code, Cursor, Windsurf, VSCodium
 

package/dist/angular.d.ts

@@ -1,12 +1,101 @@
-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-CEhs7o9p.js';
-import { Type, Signal, WritableSignal } from '@angular/core';
-import { S as Spy, C as ClassType, a as ClassSpyConfiguration, O as OnlyMethodKeysOf, j as AddSpyMethodsByReturnTypes } from './types-Br-Usge9.js';
-export { I as InjectionLog, T as TrackInjectionsOptions, a as TrackedProvider, t as trackInjections } from './track-injections-BQndbppn.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-DyjtZVoA.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-DMx5uXie.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-DzUXGIYb.js';
+import { InjectionToken, Provider, Type, Signal, WritableSignal } from '@angular/core';
+import { TestAPI } from 'vitest';
+import { C as ClassType, S as Spy, a as ClassSpyConfiguration, O as OnlyMethodKeysOf, j as AddSpyMethodsByReturnTypes } from './types-W5kEgzND.js';
+export { I as InjectionLog, T as TrackInjectionsOptions, a as TrackedProvider, t as trackInjections } from './track-injections-BU-WSjji.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-CEBKBA7k.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-COcg6YzT.js';
 import '@angular/core/testing';
 import 'rxjs';
-import 'vitest';
+
+/**
+ * `extendWithAutoSpies` — the `TestBed` half of a spec, moved into Vitest fixtures.
+ *
+ * The shape it replaces is in every Angular suite ever migrated:
+ *
+ * ```ts
+ * let cart: Spy<CartService>;
+ * let api: Spy<ApiService>;
+ *
+ * beforeEach(() => {
+ *   TestBed.configureTestingModule({ providers: [provideAutoSpy(CartService), provideAutoSpy(ApiService)] });
+ *   cart = injectSpy(CartService);
+ *   api = injectSpy(ApiService);
+ * });
+ * ```
+ *
+ * Five lines of ceremony per dependency, a `let` that is `undefined` between tests and a
+ * declaration whose type has to be repeated by hand. Vitest 4.1's builder form of `test.extend`
+ * infers the type from the factory, so the whole block becomes one statement — and a test that does
+ * not destructure `api` never builds it.
+ *
+ * **Why one call rather than a chain of `.extend`s.** The obvious composing form —
+ * `base.extend('cart', autoSpy(CartService)).extend('api', autoSpy(ApiService))` — cannot work, and
+ * the reason is `TestBed`, not typing. Fixtures resolve lazily and independently, so `cart` would
+ * configure the testing module and inject, which *instantiates* it; `api` would then reach
+ * `configureTestingModule` after instantiation and fail with Angular's own
+ * "Cannot configure the test module when the test module has already been instantiated". Every
+ * provider has to be known before the first injection, so the helper has to see them all at once.
+ *
+ * A `beforeEach` that configures the module further still composes, because it runs before any
+ * fixture resolves and `configureTestingModule` may be called repeatedly right up until the first
+ * injection. A `beforeEach` that *injects* does not — and that is the one case this cannot paper
+ * over, since by then Angular has already made the decision.
+ */
+
+/**
+ * One entry of the map: a class, a class with the configuration {@link provideAutoSpy} takes, or an
+ * `InjectionToken` whose type argument is what the double is built from.
+ */
+type AutoSpyFixture = ClassType<any> | InjectionToken<unknown> | readonly [ClassType<any>, ...unknown[]];
+/** What each entry of the map becomes in the test's context. */
+type SpiedFixtures<Spec> = {
+    [Name in keyof Spec]: Spec[Name] extends InjectionToken<infer T> ? Spy<T> : Spec[Name] extends readonly [ClassType<infer T>, ...unknown[]] ? Spy<T> : Spec[Name] extends ClassType<infer T> ? Spy<T> : never;
+};
+/** Options for {@link extendWithAutoSpies}. */
+interface ExtendWithAutoSpiesOptions {
+    /**
+     * Providers registered alongside the spies, in the same `configureTestingModule` call — the
+     * component under test, a real service the spec deliberately keeps, `provideHttpClient()`.
+     *
+     * They go in *before* the generated ones, so a provider named here wins over the auto-spy that
+     * would otherwise be made for the same token.
+     */
+    providers?: Provider[];
+}
+/**
+ * Turn a map of dependencies into typed `TestBed` fixtures.
+ *
+ * ```ts
+ * import { test as base } from 'vitest';
+ * import { extendWithAutoSpies } from 'vitest-auto-spy/angular';
+ *
+ * const test = extendWithAutoSpies(base, {
+ *   cart: CartService,
+ *   api: [ApiService, { methodsToSpyOn: ['get'] }],
+ *   passcode: PASSCODE_TOKEN,
+ * });
+ *
+ * test('checks out', async ({ cart }) => {
+ *   cart.checkout.resolveWith(true);
+ *
+ *   await expect(cart.checkout(1)).resolves.toBe(true);
+ * });
+ * ```
+ *
+ * The testing module is configured **once per test**, the first time any of the fixtures is
+ * touched, and the flag that remembers it is released on cleanup — a fixture object outlives the
+ * test that used it, and a module configured for the previous one is the shape that makes an
+ * Angular suite fail depending on order.
+ *
+ * Needs **Vitest 4.1 or newer**: the builder form of `test.extend` it is written against is what
+ * infers a fixture's type from its factory, and older versions have only the object form.
+ *
+ * @param base The `test` to extend — Vitest's own, or one already carrying fixtures of yours.
+ * @param spec Fixture name to dependency. A bare class, `[Class, config]` with what
+ *   {@link provideAutoSpy} accepts, or an `InjectionToken`.
+ */
+declare function extendWithAutoSpies<Context, const Spec extends Record<string, AutoSpyFixture>>(base: TestAPI<Context>, spec: Spec, { providers }?: ExtendWithAutoSpiesOptions): TestAPI<Context & SpiedFixtures<Spec>>;
 
 /**
  * Overriding what a *component* provides, and the diagnostic for the bundle that makes it necessary.
@@ -615,4 +704,4 @@ declare function reportSpecTiming(timing: SpecTiming): void;
  */
 declare function enableTestBedDiagnostics(options?: TestBedDiagnosticsOptions): void;
 
-export { type AngularDiagnosticsOptions, type AngularTestEnvMode, type AngularTestEnvOptions, type AutoSpyOverride, type DirectiveHostOptions, type MockedResource, type ResourceDouble, type ResourceDoubleStatus, type ResourceLike, type SignalLike, type SpecTiming, type TestBedDiagnosticsOptions, assertComponentDefIntact, assertNgModuleScopes, assertNoPendingRequests, createDirectiveHost, disableAngularDiagnostics, disableTestBedDiagnostics, enableAngularDiagnostics, enableTestBedDiagnostics, formatSpecTiming, getTestBedTiming, instrumentTestBed, mockResourceProp, mockSignalProp, overrideAutoSpy, overrideComponentProvider, registerDirectiveMatchers, registerResourceMatchers, registerSignalMatchers, reportSpecTiming, setupAngularTestEnv };
+export { type AngularDiagnosticsOptions, type AngularTestEnvMode, type AngularTestEnvOptions, type AutoSpyFixture, type AutoSpyOverride, type DirectiveHostOptions, type ExtendWithAutoSpiesOptions, type MockedResource, type ResourceDouble, type ResourceDoubleStatus, type ResourceLike, type SignalLike, type SpecTiming, type SpiedFixtures, type TestBedDiagnosticsOptions, assertComponentDefIntact, assertNgModuleScopes, assertNoPendingRequests, createDirectiveHost, disableAngularDiagnostics, disableTestBedDiagnostics, enableAngularDiagnostics, enableTestBedDiagnostics, extendWithAutoSpies, formatSpecTiming, getTestBedTiming, instrumentTestBed, mockResourceProp, mockSignalProp, overrideAutoSpy, overrideComponentProvider, registerDirectiveMatchers, registerResourceMatchers, registerSignalMatchers, reportSpecTiming, setupAngularTestEnv };