# vitest-auto-spy

> Auto-generate fully-typed test spies from a class, a type or nothing at all — one API across
> Vitest, `bun test` and `node:test`, plus Angular/NestJS/React/Vue/Svelte adapters. A drop-in
> successor to `jest-auto-spies`. Zero runtime dependencies.

- Install: `npm i -D vitest-auto-spy`
- Repository: https://github.com/ASDAlexey/vitest-auto-spy
- Documentation: https://asdalexey.github.io/vitest-auto-spy/
- Offline agent cheat sheet, shipped inside the package: `node_modules/vitest-auto-spy/AGENTS.md`
- Everything below inlined as one file: https://asdalexey.github.io/vitest-auto-spy/llms-full.txt

The one-line orientation: `createSpyFromClass(Class)` when a class exists, `createAutoMock<T>()`
when only a type does, `createMock<T>(partial)` when the double is read rather than called. Each
spied method earns helpers from its return type — `calledWith`/`mustBeCalledWith` always,
`resolveWith`/`rejectWith` for a `Promise`, `nextWith`/`throwWith` for an `Observable`.

---


# Overview

A drop-in, fully-typed jest-auto-spies successor — one API across Vitest, Bun and node:test, and the only way to run Angular's TestBed under bun test.

- **Fully typed spies** — Every method becomes a typed mock with return-type-aware helpers — resolveWith for Promises, nextWith for Observables, calledWith / mustBeCalledWith for argument matching. Overloaded methods included — a generated API client no longer forces the last signature, the one nobody calls. — https://asdalexey.github.io/vitest-auto-spy/core/create-spy-from-class
- **Class, type, or neither** — createSpyFromClass reads a real class and spies every method. No class? createAutoMock<T>() and recursive mockDeep<T>() mock straight from a type — and createMock<T>() builds the spy-free data shape a test only reads, from a deep partial that is still checked at every level. — https://asdalexey.github.io/vitest-auto-spy/core/auto-mock-by-type
- **One API, three runtimes** — The core talks to your runner through a MockAdapter seam, so the same spies run on Vitest, Bun (bun:test) and node:test. Only native mock methods stay the runner's own. — https://asdalexey.github.io/vitest-auto-spy/runtimes/vitest
- **Angular TestBed on Bun** — Bun ships no DOM and cannot resolve templateUrl, so Angular specs simply do not run there. One preload installs a DOM, inlines external templates and styles through a Bun.plugin hook, and boots a zoneless TestBed. — https://asdalexey.github.io/vitest-auto-spy/runtimes/bun-angular
- **Signals a spec can drive** — mockSignalProp replaces a signal-valued property with a real WritableSignal and hands back the writable half, so a computed downstream recomputes and an effect runs. runEffect() runs one effect body on demand when its trigger is now static. — https://asdalexey.github.io/vitest-auto-spy/adapters/angular
- **Resources that settle, or say why not** — Angular's httpResource() and resource() need a different wait each — measured on 21.2.17, an httpResource settles one tick plus one microtask after its response is flushed, a plain resource() takes two rounds, and neither has issued a request at all until something ticks. Get it wrong and nothing fails — the spec asserts the resource's default value and passes. settleResource() is the one wait both converge under, with a budget and a failure that names the resource and the flush it is missing. When the request is not the point at all, mockResourceProp drives a resource with no HTTP at all — set, fail and loading move it directly, so nothing is ever in flight. And toHaveResourceValue refuses to compare an unresolved resource even when its default happens to match — the assertion the whole family exists to stop passing. No library in the Angular world had an answer. — https://asdalexey.github.io/vitest-auto-spy/adapters/angular#resources-httpresource-and-resource
- **Faster Angular specs** — renderShallow collapses the shallow-TestBed copy-paste into one call (1.7× on real component specs), createWithAutoSpies builds a class through DI with every unprovided token spied, and per-file diagnostics say which specs are worth converting. — https://asdalexey.github.io/vitest-auto-spy/adapters/angular
- **The providers a testing module cannot reach** — overrideComponentProvider replaces a dependency a component declares in its own providers, and queues the component with the TestBed compiler so the override reaches it. assertNgModuleScopes names the module an AOT bundle stripped, createDirectiveHost compiles a host that is correct for both the compiler and the TestBed, and provideAutoSpyForToken covers a dependency behind an InjectionToken. — https://asdalexey.github.io/vitest-auto-spy/adapters/angular
- **Observables that fail on silence** — expectEmission / expectEmissions / expectNoEmission replace the expect() inside a subscribe callback that never runs — the assertion is the await. Duck-typed, so no rxjs is pulled in. — https://asdalexey.github.io/vitest-auto-spy/core/observable-assertions
- **When a green suite is lying** — zone.js replaces the global Promise, and a rejection nobody handled is drained into console.error and no further — it never reaches the channel Vitest listens on, so the runner is never told and the file still exits 0. An expect() inside a .then(), an async helper called without await, a TypeError thrown inside an import() in production code — every one of them is a passing test with a line of stderr behind it. The strayRejections option fails the test the rejection surfaced in, and the no-floating-assertion lint rule catches the commonest shape before it ever runs. One migrated suite of 11 587 tests, green, was hiding six real defects of that shape — two of them assertions that were simply false. — https://asdalexey.github.io/vitest-auto-spy/utilities/setup#_8-failing-on-a-rejection-zone-js-swallowed
- **Doubles for what the code builds itself** — Vitest only forwards new to a constructible implementation, so the Jest idiom vi.fn(() => instance) records the call, skips the body and returns an empty object. mockConstructor / stubConstructor stay full runner mocks, collect instances, and refuse to be called without new. — https://asdalexey.github.io/vitest-auto-spy/utilities/constructor-doubles
- **Waiting and the clock** — flushEventLoop and settleDynamicImport give a real event-loop turn while the timers stay faked, flushEventLoopUntil replaces a tuned sleep with a budgeted condition, and mockSystemTime / useCountingClock survive fake timers being re-installed around every test. Every wait here is bounded and names its own cause — including stable(fixture), which used to hand a stuck fixture to the runner's file-level timeout. — https://asdalexey.github.io/vitest-auto-spy/utilities/event-loop
- **Fake timers that settle** — setupFakeTimers() pairs install with restore, and advanceTimers() drains the microtasks a bare advanceTimersByTime leaves pending — the gap that makes a timer assertion read like a race. betweenTests keeps the clock fake between the tests as well, which is what Jest fakeTimers.enableGlobally did and what a nested beforeAll needs. — https://asdalexey.github.io/vitest-auto-spy/utilities/fake-timers
- **fakeAsync on Vitest** — zone.js/testing installs its ProxyZone through Jasmine and Jest hooks only, so fakeAsync and waitForAsync throw on Vitest. One import of vitest-auto-spy/zone patches them in — behind its own specifier, so a zoneless project never sees zone.js. One proxy zone serves the whole run, as Angular own jasmine patch does, so a component built in beforeEach and a tick() in the test share their timers. — https://asdalexey.github.io/vitest-auto-spy/utilities/zone
- **Module mocks that prove they applied** — Under a bundler a vi.mock() with an unmatched specifier does nothing at all, and the spec asserts on the real module. assertMocked fails loudly instead, and moduleNamespace gives a factory the shape an interop probe recognises — no more "No default export is defined on the mock". — https://asdalexey.github.io/vitest-auto-spy/utilities/module-mocks
- **Fixtures without casts** — narrow() says which branch of a union a test got, and prints the shape it actually had when it is wrong. withOverrides() builds a fixture from a model whose getters a spread would drop. asInstances() bridges a whole argument list at once, instead of one asInstance per tsc run. captureArg() takes hold of a callback or config the code under test built — expect.any tells you the kind, a captor hands you the value, which is the difference between "a callback was passed" and "call the callback that was passed". — https://asdalexey.github.io/vitest-auto-spy/utilities/fixtures
- **The DOM the runner does not ship** — stubIntersectionObserver / stubResizeObserver / stubMutationObserver replace the global the code under test constructs and hand the spec the instance. stubMediaElement makes a <video> play and report a duration, stubAbortController fixes addEventListener(…, { signal }) — and restoreMockedProps takes all of it off again. — https://asdalexey.github.io/vitest-auto-spy/utilities/observer-stubs
- **Lint rules that steer a suite** — Twelve ESLint rules point a suite at these helpers, each message linking to its recipe. Five of them catch a test being wrong rather than verbose — an expect() inside subscribe(), an expect() in a .then() nobody awaits, an Object.defineProperty nothing restores, a module-level mock shared across files, and a done callback that makes a test pass having run almost none of its body. — https://asdalexey.github.io/vitest-auto-spy/utilities/eslint-plugin
- **Hygiene for a shared environment** — One setupAutoSpy() call covers what isolate false breaks — property restore, duplicate-install detection, timers and animation frames that outlive their file, fetch that keeps a green run exiting 1, promise rejections zone.js prints and then swallows, and timer globals the fakes delete instead of restoring. installPerTest re-installs a stub for every test, and guardGlobals names the file that sealed a global. The one thing to know — those hooks belong to the spec file whose collection imported the setup module, so a runner that caches it across files leaves every file but the first without them. — https://asdalexey.github.io/vitest-auto-spy/utilities/setup
- **A migration you can verify** — Counters cannot answer whether a port lost a test — a file can lose a whole suite while a flake elsewhere starts passing, and the totals match. compareTestRuns diffs the two sets of names from the JSON report both runners write, and diffByField turns a collapsed "…(8) to deeply equal" into the field that actually differs. — https://asdalexey.github.io/vitest-auto-spy/migrating
- **The anti-patterns, underlined as you type** — A spy declared as the class, an expect() inside subscribe(), a done callback Vitest never calls — every one of them passes, so finding them in CI is an hour too late. The twelve rules ship with the package and need no editor plugin of their own — WebStorm and the other JetBrains IDEs run them natively, VS Code, Cursor and Windsurf through the ESLint extension. — https://asdalexey.github.io/vitest-auto-spy/utilities/editor-diagnostics
- **Defects a green suite cannot show** — npx vitest-auto-spy doctor reports what nothing consumes — 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, which under a shared environment is a cycle that costs the spec its own suite; a spec importing another spec; a @jest-environment pragma the runner never reads; configuration left behind for a runner that is gone, together with the setup files only it referenced. The check that motivated it found nine of 152 spec tsconfigs still covering their specs, after a codemod ate a /** and left a valid glob matching nothing. Read-only, zero config, exit 1 in CI. — https://asdalexey.github.io/vitest-auto-spy/utilities/cli
- **Readable by your agent, not just by you** — One npx vitest-auto-spy init writes the pointer into the files the agents in your repository actually read — AGENTS.md, CLAUDE.md, GEMINI.md, a Claude Code skill stub, and a glob-scoped rule file for each tool already set up here — specialised for this runner, this framework and this setup file, between markers it regenerates on the next run. Behind it sits an AGENTS.md inside the tarball for offline reading, llms.txt and llms-full.txt at the docs root, and every error message ending with a link to the page that explains it. — https://asdalexey.github.io/vitest-auto-spy/agents
- **Zero runtime deps** — An in-tree arg serializer and opt-in subpaths keep rxjs, zone.js and Angular out of your runtime bundle. 100% test coverage, verified on Node 22/24/26 and Bun 1.4. — https://asdalexey.github.io/vitest-auto-spy/core/installation

---

Source: https://asdalexey.github.io/vitest-auto-spy/core/introduction

# Introduction

`vitest-auto-spy` reads a class and generates a typed spy for **every** method, powered by your
test runner's mock primitive (`vi.fn()` on Vitest, and the equivalents on Bun and `node:test`).
It is a drop-in successor to [`jest-auto-spies`](https://www.npmjs.com/package/jest-auto-spies):
the same API, but spying on Vitest-compatible runners instead of Jest.

Manually mocking a service is tedious and brittle — one `vi.fn()` line per method, kept in sync
by hand. Instead:

```ts
import { createSpyFromClass, type Spy } from 'vitest-auto-spy';

let userService: Spy<UserService>;

beforeEach(() => {
  userService = createSpyFromClass(UserService);
});
```

`Spy<UserService>` exposes each method as a mock **plus** the right helpers based on the method's
return type: `resolveWith` / `rejectWith` for `Promise`s, `nextWith` / `throwWith` for RxJS
`Observable`s, and `calledWith` / `mustBeCalledWith` for argument matching.

No class to hand? Mock straight from a **type or interface** with `createAutoMock<T>()`, or build a
recursive, self-seeding mock with `mockDeep<T>()`. For a double the code under test only **reads** —
a DTO, a route snapshot, a config object — `createMock<T>(partial?)` returns a plain, spy-free `T`
instead. See [Auto-mock by type](https://asdalexey.github.io/vitest-auto-spy/core/auto-mock-by-type).

## Where it runs

The core never imports your test runner directly: `vi.fn()` and its equivalents sit behind a
`MockAdapter` that each entry point registers on import. Pick the one that matches your runner and
the rest of the API is identical.

```ts
import { createSpyFromClass } from 'vitest-auto-spy'; // Vitest (default, zero-config)
import { createSpyFromClass } from 'vitest-auto-spy/bun'; // Bun — bun:test
import { createSpyFromClass } from 'vitest-auto-spy/node'; // node:test
```

Angular's `TestBed` runs on Bun too, which nothing else offers — see
[Angular on Bun](https://asdalexey.github.io/vitest-auto-spy/runtimes/bun-angular).

Next: [Installation](https://asdalexey.github.io/vitest-auto-spy/core/installation) for the wiring, or
[`createSpyFromClass`](https://asdalexey.github.io/vitest-auto-spy/core/create-spy-from-class) for the full configuration surface.

---

Source: https://asdalexey.github.io/vitest-auto-spy/core/installation

# Installation

```bash
npm i -D vitest-auto-spy
```

**The plural name is an alias**
[`vitest-auto-spies`](https://www.npmjs.com/package/vitest-auto-spies) is a thin alias package that
re-exports this one, entry point for entry point — a typo installs the same code. Prefer the
singular name; the alias is generated from it and only ever follows it.

Peer dependencies are all **provided by your project**; `rxjs` and `@angular/core` are **optional**
— install them only for the matching entry point. The package itself has **zero runtime
dependencies**.

| Peer            | Needed for                                                                  | Optional? |
| --------------- | --------------------------------------------------------------------------- | --------- |
| `vitest`        | the default runner                                                          | no        |
| `rxjs`          | `vitest-auto-spy/rxjs` observable spies — `>=7`, no upper bound (rxjs 8 too) | yes       |
| `@angular/core` | `vitest-auto-spy/angular` and `vitest-auto-spy/bun-angular` helpers          | yes       |

| Tool       | Minimum                                                          |
| ---------- | ---------------------------------------------------------------- |
| Node.js    | ≥ 18 for the library — in practice, whatever your runner needs   |
| Vitest     | ≥ 2.1                                                            |
| Bun        | ≥ 1.4 for `vitest-auto-spy/bun-angular`; any recent Bun for `/bun` |
| TypeScript | ≥ 4.7 for the typed helpers (plain JS works too, just untyped)   |

Vitest **≥ 2.1** because the typed `spy.method.mock.settledResults` surface is Vitest's own `Mock`
type, and `@vitest/spy` only grew `settledResults` in 2.0 — 2.1 is where the 2.x line actually sits.
The runtime helpers themselves still run on older Vitest (the library polyfills `settledResults` for
`bun:test` and `node:test` regardless), but the types no longer line up there, so the range stops
claiming it.

Node **≥ 18** is the library's own floor and it holds: the published output is ES2022 and every
entry runs on 18. What moves the real minimum is the runner. **Vitest 4 cannot start on Node 18 at
all** — it pulls Vite 7, which calls `crypto.hash` (added in Node 20.12), and the run dies with
`TypeError: crypto.hash is not a function` before a single spec loads. Vitest 4 declares
`^20.0.0 || ^22.0.0 || >=24.0.0`; Vite 7 is stricter at `^20.19.0 || >=22.12.0`. On an older Vitest
(≤ 3, Vite 5/6) Node 18 is fine. Which version to actually run — and what it costs — is measured in
[Performance → Which Node version](https://asdalexey.github.io/vitest-auto-spy/core/performance#which-node-version).

Ships **ESM with bundled `.d.ts` types**. Two subpaths additionally ship a CommonJS build —
`vitest-auto-spy/node` (a `node --test` suite written in CJS) and `vitest-auto-spy/eslint-plugin`
(loaded by a CommonJS `eslint.config.cjs`). Everything else is ESM-only, because a `require()` of it
could never have worked: Vitest itself refuses to be required (`Vitest cannot be imported in a
CommonJS module using require()`), so every Vitest-backed entry threw on the first line of its own
`.cjs`. Test runners load ESM natively, so nothing is lost — and dropping the unreachable output cut
the published package roughly in half.

## Entry points

The library ships a framework-agnostic core plus runtime and framework layers, so a plain
Node / Bun / React / Vue project pulls **neither rxjs nor Angular into its runtime bundle**:

| Import                          | Provides                                                                                                                                                                                                        | Pulls in                    |
| ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------- |
| `vitest-auto-spy`               | `createSpyFromClass`, `createAutoMock`, `mockDeep`, `createMock`, `createFunctionSpy`, the `mock*Prop` helpers, the [observable assertions](https://asdalexey.github.io/vitest-auto-spy/core/observable-assertions), the [type bridges](https://asdalexey.github.io/vitest-auto-spy/core/spy-typing), `errorHandler`, types | `vitest`                    |
| `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, plus the core and the Angular helpers                                                     | `bun:test`, `@angular/core` |
| `vitest-auto-spy/node`          | the same core, driven by `node:test`'s `mock.fn()`                                                                                                                                                              | `node:test`                 |
| `vitest-auto-spy/rxjs`          | observable spies (`nextWith`, `nextWithValues`, `observablePropsToSpyOn`, …) + `createObservableWithValues`                                                                                                     | `rxjs`                      |
| `vitest-auto-spy/angular`       | `provideAutoSpy`, `injectSpy`, `renderShallow`, `createWithAutoSpies`, `stable`/`flushEffects`, signal matchers, TestBed diagnostics, the `mock*Prop` helpers                                                   | `@angular/core`             |
| `vitest-auto-spy/nestjs`        | `provideAutoSpy`, `injectSpy` for `Test.createTestingModule`                                                                                                                                                    | — (your `@nestjs/*`)        |
| `vitest-auto-spy/react`         | the core, with a natural import for React Testing Library suites                                                                                                                                                | — (your `react`)            |
| `vitest-auto-spy/vue`           | `provideAutoSpy` for `global.provide` + Pinia store spying                                                                                                                                                      | — (your `vue`/`pinia`)      |
| `vitest-auto-spy/svelte`        | the core, with a natural import for Svelte suites                                                                                                                                                               | — (your `svelte`)           |
| `vitest-auto-spy/console`       | [console spies](https://asdalexey.github.io/vitest-auto-spy/utilities/console) — silent typed spies over the global `console`                                                                                                                            | `vitest`                    |
| `vitest-auto-spy/setup`         | [`setupAutoSpy()`](https://asdalexey.github.io/vitest-auto-spy/utilities/setup) and [`setupFakeTimers()`](https://asdalexey.github.io/vitest-auto-spy/utilities/fake-timers)                                                                                                                      | `vitest`                    |
| `vitest-auto-spy/eslint-plugin` | [the lint rules](https://asdalexey.github.io/vitest-auto-spy/utilities/eslint-plugin) that steer a suite onto these helpers                                                                                                                              | — (your `eslint`)           |

Each entry registers its mock adapter **on import**, so import the one matching your test runner —
mixing `vitest-auto-spy` into a `bun test` run leaves the wrong adapter installed.

## Wiring it up

### Vitest

Zero-config: `import { createSpyFromClass } from 'vitest-auto-spy'` in a spec is enough. A setup
file is only needed for things that are global by nature — the rxjs layer and run hygiene:

```ts
// vitest.setup.ts
import 'vitest-auto-spy/rxjs'; // once — enables observable spies everywhere
import { setupAutoSpy } from 'vitest-auto-spy/setup';

setupAutoSpy();
```

```ts
// vitest.config.ts
export default defineConfig({
  test: {
    setupFiles: ['./vitest.setup.ts'],
  },
});
```

`setupAutoSpy()` matters most when the suite shares one environment (`isolate: false`), where an
un-restored property patch outlives the file that made it. See
[Test-run hygiene](https://asdalexey.github.io/vitest-auto-spy/utilities/setup).

### Bun

```ts
// user.test.ts
import { describe, expect, it } from 'bun:test';
import { createSpyFromClass } from 'vitest-auto-spy/bun';
```

```bash
bun test
```

For the equivalent of a Vitest setup file, use a preload:

```toml
# bunfig.toml
[test]
preload = ["./bun-setup.ts"]
```

Angular under `bun test` has its own entry and its own preload — see
[Angular on Bun](https://asdalexey.github.io/vitest-auto-spy/runtimes/bun-angular). Bun 1.4's `--isolate`, `--parallel`, `--shard`,
`--changed` and `--timings` all work unchanged; [Bun](https://asdalexey.github.io/vitest-auto-spy/runtimes/bun) covers what each one means for
your spies.

### node:test

```ts
// user.test.ts
import { describe, it } from 'node:test';
import { createSpyFromClass } from 'vitest-auto-spy/node';
```

```bash
node --test
```

`node:test` has no `expect`; pair it with `node:assert` (or any assertion library) — the spy surface
is the same either way.

## TypeScript

The typed helpers need nothing beyond a normal setup, with one thing worth knowing: **the `Spy<T>`
type surface references rxjs types even when you never import the rxjs layer.** Keep `rxjs`
installed for type-checking — it is normally already a devDependency — and none of it reaches your
runtime bundle.

```jsonc
{
  "compilerOptions": {
    // "bundler" or "node16"/"nodenext" — anything that understands `exports` subpaths
    "moduleResolution": "bundler",
  },
}
```

`Spy<T>` is a **mapped type**: it drops `#private` and `private` members, so it is not assignable
to `T`. Declare the variable as `Spy<T>` rather than as `T`, or bridge the two with
[`asInstance` / `asSpy`](https://asdalexey.github.io/vitest-auto-spy/core/spy-typing).

---

Source: https://asdalexey.github.io/vitest-auto-spy/core/how-it-works

# How it works

Everything in this library comes down to two ideas. One runs at runtime, the other exists only in
the type system. The rest of the repository is the work that keeps those two honest in real
codebases.

## Why it exists

You are testing a component that calls `UserService`. The real service can't come along — it would
hit the network. So you write a fake, by hand:

```ts
const userService = {
  getUser: vi.fn(),
  saveUser: vi.fn(),
  deleteUser: vi.fn(),
  refresh: vi.fn(),
  // …one line per method, forever
};
```

Three problems, all of them silent:

- add a method to the service and you have to remember to add it here;
- rename one and the test keeps "passing" — it just stops observing the call;
- there are no types: `getUser: vi.fn()` knows nothing about the real signature.

The same fake, assembled for you:

```ts
const userService = createSpyFromClass(UserService);
```

## Idea one — ask the class for its methods

**In one sentence:** a class can be asked which methods it has, and that list is enough to build an
object where every name is a mock.

Class methods don't live on instances, they live on the prototype:

```ts
class UserService {
  getUser(id: number) {
    /* … */
  }
  saveUser(user: User) {
    /* … */
  }
}

Object.getOwnPropertyNames(UserService.prototype);
// → ['constructor', 'getUser', 'saveUser']
```

Drop `constructor`, spread a mock across the remaining names, and you have the engine:

```ts
function createSpyFromClass(SomeClass) {
  const spy = {};

  for (const name of Object.getOwnPropertyNames(SomeClass.prototype)) {
    if (name === 'constructor') continue;

    spy[name] = vi.fn();
  }

  return spy;
}
```

```ts
const service = createSpyFromClass(UserService);
service.getUser; // vi.fn()
service.saveUser; // vi.fn()
```

That's the whole idea. No code generation, no compiler plugin — ask for the method names, build an
object from them.

### What the real implementation adds

The idea is small; the work is in the edges. Each of these is a case where the naive loop above
returns a spy that looks right and behaves wrong.

**Inheritance.** `getOwnPropertyNames` only sees one level: for `class Admin extends UserService`,
none of `UserService`'s methods appear. So the real version walks up the prototype chain, stopping
at the last prototype that still has a parent:

```ts
let current = SomeClass.prototype;

while (Object.getPrototypeOf(current)) {
  // ← Object.prototype has no parent; that's the stop
  collectNamesFrom(current);
  current = Object.getPrototypeOf(current);
}
```

The stop condition is what keeps `toString`, `hasOwnProperty` and the rest of `Object.prototype`
out of your spy.

**Getters.** If the class declares `get isReady()`, reading the property would execute the getter —
on a class that was never constructed, that usually throws. So names are collected from property
*descriptors* rather than by reading:

```ts
const descriptors = Object.getOwnPropertyDescriptors(current);

// a descriptor with `.get` is an accessor, and takes a different path
Object.keys(descriptors).filter((name) => !descriptors[name]?.get);
```

Accessors get their own treatment — see
[accessor spies](https://asdalexey.github.io/vitest-auto-spy/core/create-spy-from-class#accessor-spies-—-accessorspies).

**The mock itself.** In the real version the value is not a bare `vi.fn()` but
`createFunctionSpy(name)`, which attaches `calledWith`, `resolveWith`, `nextWith` and the rest of
the [control helpers](https://asdalexey.github.io/vitest-auto-spy/core/control-helpers). The assembly step is unchanged.

**Cost.** The method list of a class is fixed for the run, but the same class is typically spied
once per `beforeEach`. The walk result is cached in a `WeakMap` keyed by prototype, so it happens
once per class and holds no strong reference to it.

### The consequence: your class never runs

The library only looks at the class from the outside. No instance is created, no constructor is
called. A service that needs five dependencies and a live connection to be constructed is faked
without mocking any of them.

The flip side: anything that lives **on the instance** rather than on the prototype is invisible to
a prototype walk — arrow-function fields (`handle = () => {}`), Angular `signal()` properties, the
methods of an ngrx `signalStore()`. For those there is `instanceMethodsToSpyOn` (names given
explicitly), and when there is no class at all — only an interface —
[`createAutoMock<T>()`](https://asdalexey.github.io/vitest-auto-spy/core/auto-mock-by-type), a `Proxy` that mints a spy the first time a key is
touched.

## Idea two — types read the return type

**In one sentence:** TypeScript looks at what a method returns and offers the helpers that fit it.

```ts
userService.getUser.resolveWith(user); // returns a Promise    → resolveWith
userService.items$.nextWith([1, 2]); // returns an Observable → nextWith
userService.getName.calledWith(1).mockReturnValue('Ann'); // plain → mockReturnValue
```

There is no runtime here at all — only types. The tool is a conditional type:

```ts
type ChooseHelpers<Method> =
  Method extends (...args: any[]) => Promise<infer P> // returns Promise<P>?
    ? { resolveWith(value: P): void; rejectWith(err: unknown): void }
    : Method extends (...args: any[]) => Observable<infer O> // Observable<O>?
      ? { nextWith(value: O): void; complete(): void }
      : { mockReturnValue(value: ReturnType<Method>): void }; // plain method
```

It reads like `if / else if / else`: *if the method returns a Promise give it these helpers, else if
an Observable these, otherwise those.* `infer P` means "remember what the Promise was parameterized
with", so `resolveWith` accepts the right type instead of `any`.

The second half maps that over every key of the class:

```ts
type Spy<T> = {
  [K in keyof T]: T[K] extends Func
    ? T[K] & ChooseHelpers<T[K]> // method: itself, plus its helpers
    : T[K]; // not a method: left alone
};
```

`T[K] & ChooseHelpers<T[K]>` is an intersection: the spy is still callable exactly like the original
method **and** carries the control helpers.

```ts
const service: Spy<UserService> = createSpyFromClass(UserService);

service.getUser.resolveWith(user); // ✅ getUser returns Promise<User>
service.getUser.nextWith(user); // ❌ no such helper — autocomplete won't offer it
```

## Where the two meet

One line, at the end of `createSpyFromClass`:

```ts
return autoSpy as Spy<T>;
```

At runtime an ordinary object of mocks was assembled. TypeScript took no part in assembling it — it
is handed a promise that what came back has the shape of `Spy<T>`.

This is the only assertion in the core, and it is irreducible: the object is built from names known
only at runtime, while `Spy<T>` is computed by the compiler from the class type. Neither can verify
the other. Correctness rests on the fact that the prototype walk and the mapped type look at **the
same class**, and therefore produce the same set of keys.

## What the rest of the repository is

Everything else is scaffolding around those two ideas:

| Layer                                        | What it does                                                                                                                          |
| -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `createFunctionSpy`                          | implements at runtime what the types promise: `calledWith`, `resolveWith`, `nextWith`, `mustBeCalledWith`                              |
| `ArgsMap`                                    | argument matching: `calledWith(1, 'a')` resolves in O(1) through a prototype-less map, with a predicate path for `expect.any(…)` and friends |
| `MockAdapter`                                | the core never imports a test runner directly — it sits behind an interface, which is why the same library runs on Vitest, Bun and `node:test` |
| `/rxjs`                                      | Observable helpers are a separate entry point; don't import it and not a byte of rxjs enters your bundle                               |
| `resetAutoSpy`                               | resets every spy on an object in one call (`calledWith` configs live in closures, where `mockClear` can't reach)                       |
| `/angular`, `/nestjs`, `/react`, `/vue`, `/svelte` | thin per-framework wrappers — `provideAutoSpy` for the Angular TestBed, and so on                                                  |

## One compatibility note

The API is a drop-in replacement for `jest-auto-spies` — migration is a change of import, and that
includes `methodsToSpyOn`, which is additive here exactly as it is there. Restricting to a list is a
separate option, `onlyMethodsToSpyOn`, so the compatible name cannot quietly mean the opposite of
what a migrated spec expects. See [Migrating](https://asdalexey.github.io/vitest-auto-spy/migrating).

## Next

- [`createSpyFromClass`](https://asdalexey.github.io/vitest-auto-spy/core/create-spy-from-class) — the full configuration surface
- [Control helpers](https://asdalexey.github.io/vitest-auto-spy/core/control-helpers) — what the return-type-aware helpers actually do
- [Bridging `Spy<T>` and `T`](https://asdalexey.github.io/vitest-auto-spy/core/spy-typing) — why `Spy<T>` is not assignable to `T`
- [Auto-mock by type](https://asdalexey.github.io/vitest-auto-spy/core/auto-mock-by-type) — when there is no class to walk

---

Source: https://asdalexey.github.io/vitest-auto-spy/core/create-spy-from-class

# createSpyFromClass

`createSpyFromClass(Class, methodsOrConfig?)` builds a fully-typed `Spy<T>` from a class, turning
every method into a mock with return-type-aware helpers.

## Configuration

```ts
// 1. all methods (default)
createSpyFromClass(MyService);

// 2. the discovered methods PLUS these names
createSpyFromClass(MyService, ['reload', 'count']);

// 3. only these methods, discovery skipped
createSpyFromClass(MyService, { onlyMethodsToSpyOn: ['getName', 'getAge'] });

// 4. full config object
createSpyFromClass(MyService, {
  methodsToSpyOn: ['reload'],
  observablePropsToSpyOn: ['products$'], // Observable *properties*
  gettersToSpyOn: ['userName'],
  settersToSpyOn: ['userName'],
  autoSpyAccessors: true, // auto-discover every getter/setter on the prototype chain
  lazySpies: true, // build each method spy on first access (see below)
});
```

Passing an array **adds** the listed names to the auto-discovered set, matching `jest-auto-spies`.
Discovery already finds every prototype method, so the only names worth passing are the ones it
cannot see. To spy on *nothing but* a list, use `onlyMethodsToSpyOn`, which skips discovery.

The `ClassSpyConfiguration` keys are `methodsToSpyOn`, `onlyMethodsToSpyOn`,
`instanceMethodsToSpyOn`, `observablePropsToSpyOn`, `gettersToSpyOn`, `settersToSpyOn`,
`autoSpyAccessors`, `fillMissing`, `lazySpies`, `returns` and `overrides`.

### `instanceMethodsToSpyOn` — callables that are not on the prototype

Method discovery walks the **prototype chain**, which is where `class` methods live. A callable
assigned to an *instance field* is invisible to it — an arrow-function property, an Angular
`signal()` / `computed()` field, a method of an ngrx `signalStore()`. Name those explicitly:

```ts
class TaskStore {
  readonly count = signal(0); // instance field, not on the prototype
  readonly reload = (): void => {}; // arrow property, same story
  load(): void {} // ordinary method — auto-discovered
}

createSpyFromClass(TaskStore, {
  instanceMethodsToSpyOn: ['count', 'reload'],
});
```

This list and `methodsToSpyOn` behave identically — both **add** to whatever discovery produced —
and differ only in what their names tell a reader. Prefer this one in new code; keep
`methodsToSpyOn` in specs carried over from `jest-auto-spies`. Neither warns about a name the
prototype does not have: being absent from the prototype is the point.

Angular's own classes are in this list too. `Router.currentNavigation` became
`currentNavigation = this.navigationTransitions.currentNavigation.asReadonly()` in Angular 20, so
`provideAutoSpy(Router)` alone does not produce it:

```ts
provideAutoSpy(Router, { instanceMethodsToSpyOn: ['currentNavigation'] });
```

#### The error you actually see

```
TypeError: Cannot read properties of undefined (reading 'mockReturnValue')
```

The member is simply not on the spy, so the next line reads `undefined` and configuring it throws.
There is no better message to be had at runtime, and the reason is worth knowing rather than looking
like an oversight: instance fields do not exist until a constructor has run, and this factory never
constructs the class — which is exactly what makes it safe to build a spy from a service whose
constructor opens a socket. The only alternative would be to answer an unknown member with
*something*, and that something would be truthy, so `if (service.optionalThing)` in the code under
test would take the wrong branch — silently, in a different file. That is the failure mode the
[protocol deny-list](https://asdalexey.github.io/vitest-auto-spy/core/auto-mock-by-type) exists to remove, and a loud `TypeError` on the spec's
own line is the better of the two.

### `fillMissing` — a partially abstract class

A **fully** abstract class needs nothing: its prototype names nothing at all, so the factory hands
back the [type-driven proxy](https://asdalexey.github.io/vitest-auto-spy/core/auto-mock-by-type) and every method answers. One concrete member
is enough to leave that path — and that is the ordinary Angular DI-token shape:

```ts
abstract class LocalStorage {
  abstract read(key: string): string | null;
  clear(): void {} // one concrete member, and discovery is no longer empty
}

const storage = createSpyFromClass(LocalStorage);

storage.clear; // a spy
storage.read; // undefined — `abstract read()` never reached a prototype
```

`Spy<T>` types `read` as present, the read yields `undefined`, and the failure surfaces as
`storage.read is not a function` **inside production code**, with nothing pointing at the spec.
`fillMissing` answers a name the prototype never carried with a spy:

```ts
createSpyFromClass(LocalStorage, { fillMissing: true });
// or: providers: [provideAutoSpy(LocalStorage, { fillMissing: true })]
```

It is opt-in, and it has to be. TypeScript erases `abstract` entirely, so at runtime a partially
abstract class and a concrete one are the same object — filling every unknown key by default would
silence a genuine typo on every class in the suite, which is the property that separates this
library from the mock-everything proxies. Naming the members in `instanceMethodsToSpyOn` stays the
alternative when the list is short and worth stating.

Two things it does not change. A member the record already has is still read from the record, so a
lazy placeholder materialises exactly as it would without the wrapper. And the protocol keys the
surrounding machinery probes to decide *what kind of object this is* — `then`, `constructor`,
`toJSON`, `asymmetricMatch`, `$$typeof`, `nodeType`, and every symbol — are never filled: a spy on
`asymmetricMatch` turns every `toEqual` against the double into a matcher invocation, and one on
`toJSON` rewrites every snapshot of it.

## Lazy spies — `lazySpies`

**What it is.** By default `createSpyFromClass` builds a spy for **every** method up front (eager).
With `lazySpies: true`, each method spy is instead created on **first access** (`spy.method`) and
then cached, so methods a test never touches never pay the spy-construction cost.

**Why it matters.** Building a spy is not free: each method gets a host-runner mock plus the
`calledWith` / `resolveWith` / `nextWith` helper surface. On a wide service where a test calls only
a couple of methods, eagerly building all of them is mostly wasted work.

```ts
const spy = createSpyFromClass(WideService, { lazySpies: true });
spy.getName.mockReturnValue('Ada'); // getName is built here, on first access
// the other 18 methods are never built — nothing to construct, nothing to reset
```

**When to use it.** Reach for `lazySpies` when spying **wide services** (many methods) where each
test exercises only a few — the typical unit-test shape. For small classes the difference is
negligible, so the eager default is fine.

**Angular defaults to this**
The `vitest-auto-spy/angular` `provideAutoSpy` helper already sets `lazySpies: true` by default —
Angular tests overwhelmingly match this pattern. Pass `{ lazySpies: false }` there to opt back into
eager spies. See [Adapters → Angular](https://asdalexey.github.io/vitest-auto-spy/adapters/angular#lazy-spies-by-default).

**Behaviour is identical either way.** `Object.keys`, `vi.isMockFunction`, `calledWith`,
`resetAutoSpy` / `clearAutoSpy` and enumeration all work the same; lazy only changes *when* each spy
is constructed, not what it does. The one nuance: a lazy method is an accessor until first touched,
so a never-accessed spy has no recorded calls (which is exactly why `resetAutoSpy` can skip it).

## The `Spy<T>` shape

`Spy<T>` is a **mapped type** over `T`:

- every **method** becomes the mock intersected with the helpers its return type earns —
  `calledWith` / `mustBeCalledWith` always, plus `resolveWith` / `rejectWith` for a `Promise` and
  `nextWith` / `throwWith` / … for an `Observable`;
- every **`Observable` property** gains the observable helpers while keeping its own type;
- everything else keeps its declared type;
- an `accessorSpies` bag is added on top.

Because it is a mapped type, `Spy<T>` **drops `#private` and `private` members** and is therefore
not assignable to `T`. Declare the variable as `Spy<T>`, or cross the gap explicitly with
[`asInstance` / `asSpy`](https://asdalexey.github.io/vitest-auto-spy/core/spy-typing):

```ts
let users: Spy<UserService>; // ✅
let users: UserService = createSpyFromClass(UserService); // ❌ private members missing
```

## Accessor spies — `accessorSpies`

Getters and setters are not methods, so they get their own bag. List them, or turn on
`autoSpyAccessors` to discover every accessor on the prototype chain:

```ts
const settings = createSpyFromClass(SettingsService, {
  gettersToSpyOn: ['theme'],
  settersToSpyOn: ['theme'],
});

settings.accessorSpies.getters.theme.mockReturnValue('dark');
expect(settings.theme).toBe('dark');

settings.theme = 'light';
expect(settings.accessorSpies.setters.theme).toHaveBeenCalledWith('light');
```

The property itself reads and writes normally — `accessorSpies` is where the mock lives, so
`settings.theme` stays typed as `string`, not as a mock.

### Naming one half gets the pair

`gettersToSpyOn: ['theme']` on a class that declares **both** halves installs both spies, and the
same is true the other way round. Mirroring reads the prototype descriptor, so it only ever adds
what the class already has: a read-only member stays read-only.

Before 3.5.0 only the named half was spied, and the double came out poorer than the original exactly
where the code under test expects symmetry. The assignment `service.manualSwitchKidMode = false`
landed on the no-op setter the spy scaffolding installs, so the write vanished *and* there was
nothing to assert on — `accessorSpies.setters.manualSwitchKidMode` was `undefined`, and the failure
read `Cannot read properties of undefined` several steps from the configuration that caused it.

## A single function — `createFunctionSpy`

When there is no class at all, `createFunctionSpy<Fn>(name)` builds one spy with the same
return-type-aware helper surface. The `name` is what shows up in failure messages.

```ts
import { createFunctionSpy } from 'vitest-auto-spy';

const load = createFunctionSpy<(id: number) => Promise<string>>('load');

load.calledWith(1).resolveWith('value');

await expect(load(1)).resolves.toBe('value');
```

## Edge cases

**Inherited methods are spied.** Discovery walks the whole prototype chain, so a method declared on
a base class is spied exactly like one declared on the subclass. `Object.prototype` is not included.

**Abstract classes work at runtime**, because an abstract class is still a constructor function with
a prototype — only TypeScript refuses to type it as `ClassType<T>`. Pass the concrete subclass to
`createSpyFromClass` and keep the abstract class as the DI token:

```ts
providers: [{ provide: PaymentGateway, useValue: createSpyFromClass(StripeGateway) }];
```

`injectSpy` already accepts an abstract constructor as its token, so reading it back needs nothing
special.

**Constructor bodies never run.** The spy is assembled from the prototype; the class is never
instantiated, so a constructor that opens a socket or reads config is not a problem.

**Only a restricting list warns.** A name in `onlyMethodsToSpyOn` that the prototype does not have
logs a warning, because there a misspelling leaves the real method unspied and the code under test
calls something that is not there. The additive lists stay silent — naming a callable the prototype
lacks is exactly what they are for.

**No class, no problem.** [`createAutoMock<T>()`](https://asdalexey.github.io/vitest-auto-spy/core/auto-mock-by-type) builds the same surface from a
type alone, `mockDeep<T>()` does it recursively, and `createMock<T>()` returns a plain, spy-free `T`
for a data shape the code only reads.

## `returns` — the value, where the spy is built

```ts
providers: [provideAutoSpy(ProductsService, { returns: { getProducts: of([]) } })];
```

The alternative is a second statement in every `beforeEach` (`injectSpy(X).m.mockReturnValue(…)`),
and the shortcut people take instead is an exported `const` provider carrying the values — which,
under `isolate: false`, is one set of spies shared by every file that imports it.

It installs an implementation, exactly as `mockReturnValue` does, so a `calledWith(…)` chain
configured **afterwards** on the same method no longer decides the value. Use one or the other per
method.

## `gettersToSpyOn` accepts a signal-valued getter

```ts
createSpyFromClass(LayoutStateService, { gettersToSpyOn: ['isCompactMode', 'sectionsLoaded'] });
```

Whether a member is a getter is a fact about its **descriptor**, not about the type of the value it
returns — and a getter returning `Signal<T>` is callable, so a list filtered by "not callable"
rejected exactly the shape Angular's signal-based services are made of. For a service whose readonly
state is all signals that left no nameable getter at all, and the failure read
`Type 'string' is not assignable to type 'never'`, with nothing in it about signals.

Any string key may now be named. What is checked instead is the case that is unambiguously a mistake:
naming a **method** installs a spied accessor over it, so the method is no longer callable on the
spy, and that is reported at runtime.

For a signal, prefer `mockSignalProp` (`/angular`) over a spied getter — see
[Angular](https://asdalexey.github.io/vitest-auto-spy/adapters/angular#patching-a-property-of-a-spy).

## A method whose return type is `never`

A generic method with a conditional return type — `get<K extends keyof T>(k: K): T[K] extends
Stringified<infer R> ? R : never`, the shape of every typed configuration service — used to turn the
**whole** spy member into `never`, reported as `Property 'mockReturnValue' does not exist on type
'never'` with nothing connecting it to the method it came from. Fixed in the type: the helper bundle
falls back to the synchronous one instead of annihilating the member, and every return-type
comparison is non-distributive.

---

Source: https://asdalexey.github.io/vitest-auto-spy/core/control-helpers

# Control helpers

Each spied method gets helpers chosen by its return type. `calledWith` / `mustBeCalledWith`
dispatch by argument, and the type-specific helpers configure the result.

**Key order does not matter**
Arguments are matched by a serialized key, and object keys are sorted before it is built — so
`calledWith({ id: 1, name: 'a' })` matches a call made with `{ name: 'a', id: 1 }`. The two are
the same argument, and the order a literal happened to be written in is not something a test
should depend on.

## Synchronous methods

```ts
// standard vi.fn() API works as-is
myService.getName.mockReturnValue('Fake Name');

// return a value only for specific arguments
myService.getName.calledWith(1).mockReturnValue('Fake Name');
expect(myService.getName(1)).toBe('Fake Name');
expect(myService.getName(2)).toBeUndefined();

// throw if called with the "wrong" arguments
myService.getName.mustBeCalledWith(1).mockReturnValue('Fake Name');
expect(() => myService.getName(2)).toThrow();
```

### Asymmetric matchers in `calledWith`

`calledWith` / `mustBeCalledWith` accept the same asymmetric matchers as `expect`
(`expect.any`, `expect.objectContaining`, `expect.stringMatching`, …). A config that
contains at least one matcher is stored as a predicate and matched against the actual
arguments at call time, instead of by exact serialization.

```ts
myService.getName.calledWith(expect.any(Number)).mockReturnValue('Fake Name');
expect(myService.getName(1)).toBe('Fake Name');
expect(myService.getName(2)).toBe('Fake Name');

myService.save.calledWith(expect.objectContaining({ id: 1 })).mockReturnValue(true);
expect(myService.save({ id: 1, name: 'x' })).toBe(true);
```

## Promise-returning methods — `resolveWith`

```ts
myService.getProducts.resolveWith([{ name: 'Product 1' }]);
await expect(myService.getProducts()).resolves.toEqual([{ name: 'Product 1' }]);

myService.getProducts.rejectWith('FAKE ERROR');

// per-call values, and conditional-by-args
myService.getProducts.resolveWithPerCall([{ value: ['a'] }, { value: ['b'] }]);
myService.getProducts.calledWith(1).resolveWith(['one']);
```

### Inspecting promise outcomes — `mock.settledResults`

Every spied method exposes `mock.settledResults`: one index-aligned entry per call,
recording how that call's returned promise eventually settled. Vitest tracks this
natively; on Bun (`bun:test`) and `node:test` it is provided by a built-in polyfill,
so the surface is identical across all three runtimes.

```ts
myService.getProducts.resolveWith([{ name: 'Product 1' }]);
await myService.getProducts();
expect(myService.getProducts.mock.settledResults).toEqual([{ type: 'fulfilled', value: [{ name: 'Product 1' }] }]);

myService.getProducts.rejectWith('FAKE ERROR');
await myService.getProducts().catch(() => undefined);
expect(myService.getProducts.mock.settledResults).toContainEqual({ type: 'rejected', value: 'FAKE ERROR' });
```

Each entry is `{ type: 'fulfilled' | 'incomplete' | 'rejected', value }`. A call whose
promise is still pending is recorded as `incomplete` until it settles.

## Resetting spies — `clearAutoSpy` / `resetAutoSpy`

Reset every spy inside an assembled spy with one call, instead of reaching for
`mockClear` / `mockReset` on each method by hand. Both work on `createSpyFromClass`
spies and `createAutoMock` proxies, and cover method spies **and** accessor spies.

```ts
import { clearAutoSpy, resetAutoSpy } from 'vitest-auto-spy';

// clears recorded calls only — configured returns are kept
clearAutoSpy(myService);

// clears calls AND reverts configuration to pristine
resetAutoSpy(myService);
```

`resetAutoSpy` reverts both the library config (`calledWith` / `resolveWith` / `nextWith` / …) **and**
a bare return value set directly on a spy (`myService.getName.mockReturnValue('x')`) — after a reset
the method returns `undefined` again until reconfigured.

## Observable methods & properties — `nextWith`

Enabled by importing the rxjs layer once (`import 'vitest-auto-spy/rxjs';`). See
[Runtimes → RxJS](https://asdalexey.github.io/vitest-auto-spy/runtimes/rxjs).

```ts
myService.getProducts$.nextWith([{ name: 'Product 1' }]); // emit, stream stays open
myService.getProducts$.nextOneTimeWith([{ name: 'X' }]);  // emit once, then complete
myService.getProducts$.throwWith('FAKE ERROR');           // error the stream
myService.getProducts$.complete();                        // complete the stream
```

### A precise sequence — `nextWithValues`

`nextWithValues(configs)` emits the entries **in order**, and stops at the first `{ complete: true }`.
Anything pushed onto the backing subject afterwards is merged in until that completion arrives.

```ts
myService.getProducts$.nextWithValues([
  { value: [{ name: 'Product 1' }] },
  { value: [{ name: 'Product 2' }], delay: 100 },
  { complete: true },
]);
```

#### `ValueConfig`

| Shape                       | Effect                                                  |
| --------------------------- | ------------------------------------------------------- |
| `{ value, delay? }`         | emit `value` (after `delay` ms, if given)               |
| `{ errorValue, delay? }`    | error the stream with `errorValue` (after `delay` ms)   |
| `{ complete?, delay? }`     | complete the stream — `complete: false` emits nothing   |

`delay` is milliseconds and is applied with RxJS's own `delay()` / `timer()`, so under fake timers
you have to advance the clock: [`advanceTimers(ms)`](https://asdalexey.github.io/vitest-auto-spy/utilities/fake-timers) does that **and**
drains the microtasks the emission queues.

### A fresh stream per call — `nextWithPerCall`

`nextWithPerCall(configs)` hands the **n-th call** the n-th entry, and returns one `ReplaySubject`
per entry so a test can push more values into a specific call later.

```ts
const [first$, second$] = myService.watch$.nextWithPerCall([
  { value: 'a' },
  { value: 'b', doNotComplete: true },
]);

expect(await firstValueFrom(myService.watch$())).toBe('a');

// the second call's stream stays open, so it can be driven further
second$.next('b2');
```

Each per-call stream **completes after its first value** unless the entry sets
`doNotComplete: true`. `ValueConfigPerCall` is `{ value, delay?, doNotComplete? }`.

### Manual control — `returnSubject`

`returnSubject()` hands back the `ReplaySubject` behind the spy, for the cases the helpers do not
cover:

```ts
const subject = myService.getProducts$.returnSubject();

subject.next([{ name: 'Product 1' }]);
subject.error(new Error('boom'));
```

It is a `ReplaySubject`, so a subscriber that arrives late still sees the values already pushed.

Full reference, plus the standalone `createObservableWithValues` builder:
[Runtimes → RxJS](https://asdalexey.github.io/vitest-auto-spy/runtimes/rxjs).

---

Source: https://asdalexey.github.io/vitest-auto-spy/core/auto-mock-by-type

# Auto-mock by type

`vitest-auto-spy` picks each method's helper surface from its **return type**: sync methods get
`mockReturnValue` / `calledWith` / `mustBeCalledWith`, `Promise`-returning methods get
`resolveWith` / `rejectWith` / `resolveWithPerCall`, and `Observable`-returning methods/properties
get `nextWith` and friends.

## From a type — `createAutoMock`

`createAutoMock<T>(overrides?)` builds a `Spy<T>` from a **type or interface** alone —
no runtime class needed. Each accessed method becomes a spy with the full helper surface;
seed concrete values through `overrides`.

```ts
import { createAutoMock } from 'vitest-auto-spy';

interface UserService {
  getName(id: number): string;
  load(id: number): Promise<User>;
}

const users = createAutoMock<UserService>();
users.getName.calledWith(1).mockReturnValue('Ada');
users.load.resolveWith({ id: 1 });
```

## From a type, without spies — `createMock`

`createAutoMock` is built for a collaborator the code under test **calls**: every un-seeded member
comes back as a spy. For a double it only **reads** — a DTO, a route snapshot, a config object —
that is the wrong trade. `createMock<T>(partial?)` returns a plain `T` assembled from the fields you
seed, with no spies anywhere.

```ts
import { createMock } from 'vitest-auto-spy';

const route = createMock<ActivatedRouteSnapshot>({ data: { title: 'Report' } });
const config = createMock<ServerConfig>({ baseUrl: 'https://example.test' });
```

|                   | `createMock<T>()`                          | `createAutoMock<T>()`                   |
| ----------------- | ------------------------------------------ | --------------------------------------- |
| Returns           | `T`                                        | `Spy<T>`                                |
| Un-seeded members | `undefined`                                | a lazily created, decorated spy         |
| Reach for it when | the double is **read** — data shapes       | the double is **called** — collaborators |

`partial` is a `Partial<T>`, so the seeded fields stay type-checked: an unknown key, or a known key
with the wrong type, is still a compile error. It is also the single place the `as` lives, so a
suite under a `no-type-assertion` lint rule stops sprinkling `eslint-disable` over its fixtures.

## Recursive deep mocks — `mockDeep`

`mockDeep<T>(overrides?)` is the recursive counterpart of `createAutoMock`. Nested object
access auto-creates chainable spies, so a deep call like `mock.repo.user.find()` works with
no manual seeding — every hop is itself a callable spy carrying `calledWith` / `mockReturnValue`
/ `resolveWith`.

```ts
import { mockDeep } from 'vitest-auto-spy';

interface Api {
  repo: { user: { find(id: number): Promise<User> } };
}

const api = mockDeep<Api>();
api.repo.user.find.calledWith(1).resolveWith({ id: 1 });
await expect(api.repo.user.find(1)).resolves.toEqual({ id: 1 });

// seed concrete values on the root via overrides, or by assignment
const seeded = mockDeep<Api>({ repo: { user: { find: () => Promise.resolve({ id: 9 }) } } });
```

Seeded values (via `overrides` or `mock.x = …`) shadow the auto-generated child for that key.
Nodes are intentionally **not** thenable, so awaiting a node never treats it as a promise.

### What a Proxy-backed double cannot do

Both `createAutoMock` and `mockDeep` build a Proxy, and a Proxy answers only the operations its
handler traps. Three of them were missing, and each gave a **silent** wrong answer rather than an
error — a checking test quietly becoming a non-checking one, visible only by reading the proxy's
source. Two are fixed in 3.5.0; the third cannot be.

| Operation                          | Before                                             | Now                                                      |
| ---------------------------------- | -------------------------------------------------- | -------------------------------------------------------- |
| `mockValueProp` and its three siblings | patch landed on the Proxy target; the double ignored it | works, and `restoreMockedProps()` undoes it          |
| `delete mock.optionalMethod`       | deleted nothing — the next read remade the spy      | the member is absent until something writes to it again  |
| `Object.assign(realInstance, mock)` | copies only the keys already **read**              | unchanged — see below                                    |
| `of(mock)` / `from(mock)`          | the double was taken for a scheduler or a stream    | four protocol keys answer `undefined` — see below        |

The first was the worst of the three, because it broke the composition of two things the library
recommends at once: the `no-object-define-property` rule sends people to `mock*Prop`, and the
factory decision tree sends them to `createAutoMock`, and together they produced a double that
ignored the patch. Specs that hit it ended up building the double by hand — real getters plus a
`createFunctionSpy` per method.

`ownKeys` cannot be completed: a type has no key list at runtime, which is the premise of these two
factories in the first place. A spec that installs a double by **copying it onto a real instance**
therefore gets whichever members happened to be read first, and every other call reaches the real
implementation without a word. Use `createSpyFromClass` there — it returns an ordinary object whose
method keys are enumerable, so the copy is complete.

### It answers everything, so it must not answer *these*

The same premise cuts the other way. A library handed an object that has to decide **what kind of
thing it is** asks by probing a key, and a double that answers every property answers the probe too
— at which point it stops being a double of `T` and becomes whatever was being looked for. Four
names are answered with `undefined` unless the spec seeds them, alongside `then` and every symbol,
which always were:

| Key            | Probed by                                      | The double became  |
| -------------- | ---------------------------------------------- | ------------------ |
| `schedule`     | `popScheduler` in `of` / `from` / `merge` / …  | a scheduler        |
| `lift`         | `isObservable`, together with `subscribe`      | an Observable      |
| `@@observable` | `isInteropObservable` in `innerFrom`           | an interop stream  |
| `getReader`    | `isReadableStreamLike` in `innerFrom`          | a ReadableStream   |

The one that cost an afternoon reads like nothing at all:

```ts
of(autoMocked<AnimationItem>()); // an Observable that never emits
```

`of(...)` takes its **last argument** for a scheduler when `typeof x.schedule === 'function'`, so
the whole double was eaten as one, `of()` was left with an empty argument list, and the emission was
scheduled onto a spy that does nothing. The component under test kept its `null`, and the assertion
that failed was about an unrelated `emit()` three concerns away — nothing in the failure mentions
`of`. The workaround people arrive at is `from([double])`, and it is no longer needed.

`subscribe` is deliberately **not** on the list: it is an ordinary method name (a store, an Angular
`OutputEmitterRef`, an event bus) and `expect(store.subscribe).toHaveBeenCalledWith(cb)` is a real
assertion. Denying `lift` and `@@observable` already breaks the impersonation, so `subscribe` alone
fools nothing — `from(double)` fails with rxjs's own *"You provided an invalid object where a stream
was expected"*.

If your type genuinely has one of the four, seed it once and it comes back; the list is consulted
after the store.

```ts
createAutoMock<TaskScheduler>({ schedule: vi.fn() });
```

That is the trade: without a seed the member is absent and the failure is an immediate `TypeError:
… is not a function` at the call site, instead of a silent one in another file. A key joins the list
only with an observed mechanic behind it, never because the name sounds protocol-ish — each entry
costs somebody the ability to mock a member of that name without seeding it.

### `undefined` in `overrides` is a seed, not an omission

`createAutoMock` reads its seed with `Reflect.ownKeys`, so a key written out with an explicit
`undefined` **is** in the store and reads back as `undefined`. Leave it out and the same read
materialises a function spy — which is *truthy*, and sends a guarded call site down the branch the
spec was trying to close:

```ts
createAutoMock<NavigationService>({ currentFocus: undefined, navRoot: undefined, selectors: 'button, a' });
//                                  ^ "this member is data, and there is none"
```

Write it even when it looks redundant. It is the way to say "the member exists and is empty", and
on this double it is not the same as saying nothing.

### Depth comes from property access, not from calls

This is the one thing to know before reaching for `mockDeep`, and it is invisible in the types.
`api.repo.user.find()` chains because every hop but the last is a property **read**. A node that is
**called** returns whatever it was configured to return, and by default that is `undefined` — so a
fluent API breaks at the second call while `DeepMockProxy<T>` types it perfectly:

```ts
const logger = mockDeep<AppLogger>();

logger.channel('app').info('started'); // TypeError: Cannot read properties of undefined
```

Pass `{ selfReturning: true }` for that shape. A called node then hands itself back, so the chain
continues down the same path the reads would have taken:

```ts
const logger = mockDeep<AppLogger>({}, { selfReturning: true });

logger.channel('app').info('started');
expect(logger.channel('app').info).toHaveBeenCalledWith('started');
```

It never takes configuration away: `mockReturnValue`, `calledWith(...).mockReturnValue(...)` and
`resolveWith` all still win, and only an *unconfigured* call — the one that returned `undefined` —
returns the node. The exact cost is a node deliberately configured to return `undefined`; assert on
its calls rather than on its return value there, which is why this is opt-in.

Two bridges, one per direction. What a **call** hands back is typed as the declared return type, not
as a spy, so `asSpy<T>(…)` when the helpers are needed. The **whole mock** is a `DeepMockProxy<T>`,
not assignable to `T` for the same reason `Spy<T>` is not — a mapped type cannot see private
members — so `asInstance(…)` when it has to go to an API typed against the real thing:

```ts
asSpy<QueryBuilder>(query.where('id')).limit.mockReturnValue(query);
boot(asInstance(mockDeep<AppLogger>({}, { selfReturning: true })));
```

`asInstance` did not accept a deep mock before 3.5.0, which left one with nowhere to go: the factory
tree recommends `mockDeep` when the calls chain, and the result then fitted nothing expecting `T`.

When only one method chains, `createAutoMock<T>()` with `channel.mockReturnThis()` is the smaller
answer.

---

Source: https://asdalexey.github.io/vitest-auto-spy/core/observable-assertions

# Observable assertions

`expect(...)` inside a `subscribe()` callback is the most common way to write a test that passes
while asserting nothing: if the stream never emits, the callback never runs, no expectation is
evaluated and the test is green and empty. These helpers invert that — **the assertion is the
`await`**.

```ts
import { expectCompletion, expectEmission, expectEmissions, expectError, expectNoEmission } from 'vitest-auto-spy';

await expect(expectEmission(component.visible$)).resolves.toBe(true); // the first VALUE, not a list
await expect(expectEmission(tasks$)).resolves.toEqual({ id: 1 }); // the task itself, not `[task]`
await expect(expectEmissions(source$, 3)).resolves.toEqual([1, 2, 3]); // the list is this one
await expectNoEmission(source$, { timeout: 50 }); // asserts silence
await expectCompletion(service.purgeCache()); // asserts termination
```

| Helper                                   | Resolves with                        | Rejects when                                                                |
| ---------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------- |
| `expectEmission(source$, opts?)`         | the first value                      | nothing arrives in time, the stream errors, or it completes empty           |
| `expectEmissions(source$, count, opts?)` | the first `count` values as an array | fewer than `count` arrive in time, the stream errors, or it completes short |
| `expectNoEmission(source$, opts?)`       | `void`                               | anything is emitted while it should stay silent                             |
| `expectCompletion(source$, opts?)`       | `void`                               | the stream is still running when the timeout expires, or it errors          |
| `expectError(source$, opts?)`            | the error, unwrapped                 | the stream completes or stays quiet instead of failing                      |

## The emitted type is inferred

`expectEmission(of(1))` is a `Promise<number>`, and `expectEmissions(of(1), 2)` a `Promise<number[]>`
— including through Angular's `toObservable()` and through a `Subject` a spec pushes into. Up to
3.4.0 both came back as `Promise<unknown>`: the helper's parameter type matched rxjs's overloaded
`subscribe` in a way that inferred nothing, the call compiled, `resolves.toBe(1)` passed, and the
loss only showed up when somebody read a field off the awaited value. Nothing needs a manual type
argument any more.

## Which sources work

The source is duck-typed, so nothing here depends on rxjs at runtime. Two subscription contracts are
accepted, and both are needed in an Angular codebase:

| Source                                                            | `subscribe` takes  |
| ----------------------------------------------------------------- | ------------------ |
| rxjs `Observable` / `Subject`, Angular `toObservable()`, `EventEmitter` | an observer object |
| Angular `output()` — `OutputEmitterRef` — and other callback APIs  | a bare callback    |

The second one used to hang. `OutputEmitterRef.subscribe(callback)` stores whatever it is handed and
calls it on `emit()` inside a `try/catch` that routes failures to Angular's `ErrorHandler`, so
passing it an observer object produced no visible error at all — just
`await expectEmission(component.selectionChange)` waiting for the watchdog.

## `expectCompletion` — when the value is not the point

A save, a purge, an `Observable<void>`, a `Subject` a teardown closes. `firstValueFrom` rejects such
a stream with rxjs's `EmptyError`, and the workaround people arrive at,
`lastValueFrom(source$, { defaultValue: undefined })`, reads as though the default were the
interesting part when the whole assertion is "it finished".

```ts
await expectCompletion(service.purgeCache());
await expectCompletion(closed$, { label: 'closed$', timeout: 2_000 });
```

Emissions do not fail it — it asserts termination and nothing about what came before. Use
`expectNoEmission` when silence is what matters.

## `expectError` — when the failure is the subject

The other helpers wrap a stream failure in a **new** `Error` whose message names the stream. That is
right for reporting a failure nobody expected, and useless when the failure is the thing under test:
`rejects.toBe(originalError)`, `rejects.toBeInstanceOf(UdmsStatusError)` and an exact
`expect(err.message).toBe('websso fail')` all fail against the wrapper.

`expectError` resolves **with** the error, exactly as it was thrown, so each of those is an ordinary
assertion:

```ts
await expect(expectError(service.load())).resolves.toBe(originalError);
expect(await expectError(process$)).toBeInstanceOf(UdmsStatusError);
```

It waits for the error however late it arrives — a stream that emits first and then fails still
settles here on the failure — and fails, naming the stream, if the stream completes or stays quiet
instead. The wrapped failures of the other helpers now also carry the original on `cause`, so
`rejects.toMatchObject({ cause: original })` works; prefer `expectError`, which needs no unwrapping.
`firstValueFrom(source$).rejects` remains fine too.

## Choosing which emission counts

`skip` and `until` put the interesting condition in the assertion instead of in the source.

```ts
await expect(expectEmission(isXl$, { skip: 1 })).resolves.toBe(true); // a shareReplay / BehaviorSubject
await expect(expectEmission(params$, { until: (p) => p.channelId === expected })).resolves.toEqual(…);
await expect(expectEmissions(ids$, 2, { until: (id) => id > 5 })).resolves.toEqual([6, 7]);
```

`source$.pipe(skip(1))` and `pipe(filter(…))` say the same thing and cost an rxjs import in a spec
whose whole point was that it needed none — but the real difference is the failure. Emissions that
do not match are still **counted**, so a timeout reads `4 emission(s) received` rather than `0`, and
"the wrong thing fired" stays distinguishable from "nothing fired". A `filter` in front of the helper
throws that away.

## `advance` — the window between subscribing and awaiting

A stream driven by a `debounceTime`, a retry or a poll needs the clock moved *after* something is
listening, and `await` gives control away before the next statement runs:

```ts
await expect(expectEmission(purchased$, { advance: () => vi.runAllTimers() })).resolves.toBe(false);
```

That replaces the shape specs arrive at otherwise — hold the promise in a variable, advance the
clock, then await it — which is correct and breaks silently the moment somebody adds an `await` one
line above it. It is a callback rather than an `advanceTimers: true` flag because these helpers live
in the **core** entry, which contains no test runner: `vi`, `bun:test` and `node:test` drive their
clocks differently, and only the spec knows which one it is on.

## Options

| Option    | Default                             | Notes                                                                                                               |
| --------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `timeout` | `1000` (`0` for `expectNoEmission`) | Milliseconds to wait for a value — or, in `expectNoEmission`, how long silence must hold. `0` disables the watchdog |
| `label`   | —                                   | Name used in the failure message instead of the generic "the observable"                                            |
| `skip`    | `0`                                 | Ignore the first `N` emissions — the stale first value of a `shareReplay` / `BehaviorSubject`                       |
| `until`   | —                                   | Wait for the first emission satisfying the predicate; the others are still counted in the failure                   |
| `advance` | —                                   | Run once, after the subscription exists and before the promise is handed back                                       |

### The watchdog runs on real time — even under fake timers

That is deliberate, and there are two reasons. The helper *is* the assertion, so its clock must be
the one thing a spec cannot stop; and a virtual watchdog would race the timers the spec advances —
`expectEmission(source$, { timeout: 200 })` followed by `vi.advanceTimersByTime(5_000)` would fire at
200 virtual ms and reject the stream the spec was about to advance into.

The cost is that in a suite running under global fake timers a *failing* assertion spends a real
second before it reports. Do not answer that with `{ timeout: 0 }` at every call site: that disables
the watchdog, and the next silent stream hangs until the runner's own timeout with no message worth
reading. Lower the default once instead:

```ts
// vitest.setup.ts
import { setEmissionTimeout } from 'vitest-auto-spy';
import { setupAutoSpy } from 'vitest-auto-spy/setup';

setupAutoSpy({ globalFakeTimers: true });
setEmissionTimeout(100); // the clock is frozen; a real second buys nothing
```

`setEmissionTimeout` is process-wide and does not touch `expectNoEmission`, whose wait is a quiet
window rather than a watchdog.

## Failure messages

A stream that stays quiet fails with the label and the timeout, one that errors fails with the
error, and one that completes empty says so:

```
saved$ did not emit within 1000 ms (0 emission(s) received). Either the stream never fired — check
the trigger and any provider spy feeding it — or it is slower than the timeout; raise it with
`{ timeout: … }`. This wait is real time even under fake timers, on purpose: a virtual watchdog would
race the timers your spec advances. Lower it with `setEmissionTimeout(100)` in the setup file rather
than disabling it with `{ timeout: 0 }`, which leaves the next silent stream with no message at all.
```

```
saved$ completed after 0 emission(s), expected 1. A completed-but-empty stream is the usual sign
that the value was produced before the subscription.
```

## Measured: four forms against four streams

The claim above — that `expect()` inside `subscribe()` is the most common way to write a test that
asserts nothing — is checkable, so here it is checked. One spec file, the same assertion written four
ways, run against four streams: one that emits the wrong value, one that errors, one that completes
without emitting, and one that never does anything.

```ts
const scenarios = {
  wrongValue: () => of(1),
  errors: () => throwError(() => new Error('boom')),
  completesEmpty: () => EMPTY,
  neverEmits: () => NEVER,
};

for (const [name, make] of Object.entries(scenarios)) {
  describe(name, () => {
    it('1. bare subscribe', () => {
      make().subscribe((v) => expect(v).toBe(999));
    });

    it('2. new Promise(done) + subscribe', () =>
      new Promise<void>((done) => {
        make().subscribe((v) => {
          expect(v).toBe(999);
          done();
        });
      }), 1200);

    it('3. await firstValueFrom', async () => {
      expect(await firstValueFrom(make())).toBe(999);
    }, 1200);

    it('4. await expectEmission', async () => {
      expect(await expectEmission(make(), { label: 'source

The source is duck-typed — anything with a `subscribe` method — so these live in the **core** entry
and pull in no rxjs at runtime. They work with rxjs `Observable`s and `Subject`s, Angular
`toObservable()` results, and hand-rolled subscribables alike.

The watchdog uses the timer functions captured at import time, so `vi.useFakeTimers()` cannot
silence it: the failure stays "the stream did not emit", not "the test timed out". A synchronous
source (`of(…)`, a `BehaviorSubject`) settles and unsubscribes without ever arming the timer.

**Lint it**
The [`no-expect-in-subscribe`](https://asdalexey.github.io/vitest-auto-spy/utilities/eslint-plugin) rule flags `expect()` inside a
`subscribe()` callback and points here.

, timeout: 300 })).toBe(999);
    }, 1200);
  });
}
```

Sixteen tests, every one of them asserting something that is false. Twelve fail:

```text
 Test Files  1 failed (1)
      Tests  12 failed | 4 passed (16)
     Errors  4 errors
```

The four that pass are the four `bare subscribe` rows — all of them, in every scenario.

| | `of(1)` — wrong value | `throwError(boom)` | `EMPTY` | `NEVER` |
| --- | --- | --- | --- | --- |
| 1. bare `subscribe` | **green** ⁽¹⁾ | **green** ⁽¹⁾ | **green** | **green** |
| 2. `new Promise(done)` | `Test timed out in 1200ms` | `Test timed out in 1200ms` | `Test timed out in 1200ms` | `Test timed out in 1200ms` |
| 3. `await firstValueFrom` | `expected 1 to be 999` + diff | `Error: boom` | `EmptyError: no elements in sequence` | `Test timed out in 1200ms` |
| 4. `await expectEmission` | `expected 1 to be 999` + diff | `source$ errored instead of emitting: Error: boom` | `source$ completed after 0 emission(s), expected 1…` | `source$ did not emit within 300 ms…` |

Read the table by column and the ranking is the same in each: form 1 says nothing, form 2 says only
that time ran out, form 3 says what happened, form 4 says what happened **and to which stream**.

⁽¹⁾ Those two are green, not silent. `of(1)` is synchronous, so the assertion does run and does
throw — into a `subscribe` callback, from which rxjs re-throws it out of band. It arrives after the
summary, attributed to whichever test the runner happened to be on:

```text
⎯⎯⎯⎯ Unhandled Errors ⎯⎯⎯⎯
Vitest caught 4 unhandled errors during the test run.
AssertionError: expected 1 to be 999
The latest test that might've caused the error is "2. new Promise(done) + subscribe".
```

Exit code 1, no failing test named, and the name it does print belongs to a different test. Then note
what makes the other two columns worse than that: as soon as the source is **asynchronous** — a
`timer()` under fake timers, an `httpResource`, anything behind a scheduler — the callback never runs
at all, nothing is thrown, and the file is entirely, quietly green. The synchronous case is the loud
one.

### How to write it

```ts
// ❌ green whatever the stream does
service.collect().subscribe((result) => {
  expect(result).toEqual(expected);
});

// ❌ Jest's `done` callback, transliterated for Vitest — buys a hang instead of a diff
it('collects', () =>
  new Promise<void>((done) => {
    service.collect().subscribe((result) => {
      expect(result).toEqual(expected);
      done();
    });
  }));

// ✅ plain rxjs, when the source is synchronous or certain to emit
expect(await firstValueFrom(service.collect())).toEqual(expected);

// ✅ when it might not emit — the failure then names the stream and costs the timeout, not the test's
expect(await expectEmission(service.collect(), { label: 'collect()' })).toEqual(expected);
```

The last two are both correct, and `firstValueFrom` is one rxjs import against a library helper — take
it whenever the stream is known to fire. What it cannot do is the `NEVER` column: it hands the runner
a bare timeout, the same failure a subscribe-based test gives, with no observable named and the
default 5 000 ms spent before it arrives. `EmptyError: no elements in sequence` has the same problem
one step down — true, and no help finding which of the four streams in the file was empty.

Both `❌` forms are lintable: [`no-expect-in-subscribe`](https://asdalexey.github.io/vitest-auto-spy/utilities/eslint-plugin) catches the first
and [`no-done-callback`](https://asdalexey.github.io/vitest-auto-spy/utilities/eslint-plugin) the second.

## No rxjs required

The source is duck-typed — anything with a `subscribe` method — so these live in the **core** entry
and pull in no rxjs at runtime. They work with rxjs `Observable`s and `Subject`s, Angular
`toObservable()` results, and hand-rolled subscribables alike.

The watchdog uses the timer functions captured at import time, so `vi.useFakeTimers()` cannot
silence it: the failure stays "the stream did not emit", not "the test timed out". A synchronous
source (`of(…)`, a `BehaviorSubject`) settles and unsubscribes without ever arming the timer.

**Lint it**
The [`no-expect-in-subscribe`](https://asdalexey.github.io/vitest-auto-spy/utilities/eslint-plugin) rule flags `expect()` inside a
`subscribe()` callback and points here.

---

Source: https://asdalexey.github.io/vitest-auto-spy/core/spy-typing

# Bridging `Spy<T>` and `T`

`Spy<T>` is a mapped type. It drops `#private` / `private` members, so it is **not** assignable to
`T` — which is correct (a spy is not the class) and a constant nuisance when an API asks for `T`.
The fix is a named, documented view instead of an `as any` scattered through a suite:

```ts
import { asInstance, asSpy } from 'vitest-auto-spy';

asInstance(cartSpy); // Spy<CartService> → CartService, for APIs typed against the class
asSpy(TestBed.inject(CartService)); // CartService → Spy<CartService>, for the helpers
```

Both are the same object at runtime; only the view changes.

```ts
const store = createSpyFromClass(CartStore);

renderShallow(CartComponent, {
  providers: [{ provide: CartStore, useValue: asInstance(store) }],
});
```

Declare the variable as `Spy<T>` (which is what `injectSpy(X)` returns) rather than as `T`, and the
bridges stay at the boundaries where an external API forces the other view.

## A spy you can call with `new`

A runner mock (`vi.fn()`) rejects `new` as soon as it carries a `mockReturnValue`, so code under
test that does `new Foo()` — a `Worker`, an `IntersectionObserver`, a hand-rolled client — cannot
be served by one. `createSpyClass` returns a real constructor function whose instances are full
auto-spies:

```ts
import { createSpyClass } from 'vitest-auto-spy';
import { mockValueProp } from 'vitest-auto-spy';

const WorkerSpy = createSpyClass(BackgroundWorker);
mockValueProp(globalThis, 'BackgroundWorker', WorkerSpy);

service.start();

expect(WorkerSpy.calls[0]).toEqual(['./task.js']);
WorkerSpy.instances[0].postMessage.mockReturnValue(undefined);
```

| Member      | What it holds                                           |
| ----------- | ------------------------------------------------------- |
| `calls`     | The arguments of every `new` (and plain call), in order |
| `instances` | The `Spy<T>` produced by each construction, in order    |

It takes the same optional second argument as
[`createSpyFromClass`](https://asdalexey.github.io/vitest-auto-spy/core/create-spy-from-class), so each instance can be configured the usual way.

## Which error means which direction

The compiler reports the `Spy<T>` / `T` mismatch in four different ways, and none of them contains
both the words "spy" and "instance" — which is why the fix is hard to find from the message alone,
and why the usual repair is a double assertion that also hides real mismatches.

| Message                                                                              | Direction | Fix                               |
| ------------------------------------------------------------------------------------ | --------- | --------------------------------- |
| `TS2352: … 'accessorSpies' is missing in type 'Router'`                              | `T` → spy | `asSpy(TestBed.inject(Router))`   |
| `TS2739` / `TS2740: Type 'Spy<X>' is missing the following properties from type 'X'` | spy → `T` | `asInstance(spy)`                 |
| `TS2345: Argument of type 'Spy<X>' is not assignable to parameter of type 'X'`       | spy → `T` | `asInstance(spy)`                 |
| `is missing the following properties: _modalOpened, body, …` (private names)         | —         | declare `Spy<T>`, not `Mocked<T>` |

`TS2352` is the one a migrated suite hits everywhere at once: `TestBed.inject(X) as Spy<X>` is the
`jest-auto-spies` idiom and is in every guide, and it only starts failing once the specs are
compiled by the same toolchain as production code — a `ts-jest` setup with isolated-module semantics
never type-checked it.

The last row is its own trap. Vitest's own `Mocked<T>` keeps `T`'s **private** members, so the error
lists private field names and reads as "the double is incomplete". It is not; the declaration is
wrong. `Spy<T>` covers the public surface on purpose.

## A generic class needs its type argument

`TestBed.inject` infers from the constructor, so `FeatureFlagService<T = FeatureFlagDefaults>`
comes back as `FeatureFlagService<any>`. The `any` then spreads through `Spy<>` and surfaces as a
mismatch between `AddPromiseSpyMethods<unknown>` and `WithMockReturnValue<…>`, eight levels deep,
with nothing in the message about a missing type parameter.

```ts
const config = asSpy<FeatureFlagService>(TestBed.inject(FeatureFlagService));
const config = injectSpy<FeatureFlagService>(FeatureFlagService); // same, in Angular
```

## `asInstances(...)` — a whole argument list at once

```ts
factory = webSsoAuthCheckFactory(...asInstances(account, authCheck, domainEvents, storage), document);
```

One wrapper per argument is not merely longer, it is *discovered* one argument at a time: TypeScript
stops checking a call at the first argument that does not fit, so a factory taking five spies reports
one `TS2345`, and the next only after the previous is fixed and `tsc` is run again. A non-spy in the
list passes through unchanged, so a call that mixes spies with real values does not have to be split.

## Overloads: `Parameters` reads the **last** signature

```ts
const cinemas = asSpy<VenuesService, { overload: 'first' }>(TestBed.inject(VenuesService));
const client = createSpyFromClass<VenuesService, { overload: 'first' }>(VenuesService);
```

`Parameters<F>` and `ReturnType<F>` — and therefore the helpers a spy attaches — read the last
overload of a method. On a generated API client (`ng-openapi-gen`, `openapi-generator`) that is
`observe: 'events'`, the signature nobody calls: `nextWith(body)` then stops compiling, demanding an
`HttpEvent<T>`, with nothing in the message about overload order.

`{ overload: 'first' }` types the spy against the first signature instead. For a single method there
is also `Overload<Client['get'], 0>`, which is what to put in a `MockInstance<…>` or a `vi.fn<…>()`.

## `Spy<T>`, not `Mocked<T>`

```ts
let modal: Spy<KdsModalService>; // ✅
let modal: Mocked<KdsModalService>; // ❌
```

`Mocked<T>` is Vitest's own type and it intersects with `T` *completely*, private members included.
Assigning a spy to it fails with `Type 'Spy<…>' is missing the following properties: _modalOpened,
body, rendererFactory, …` — a list of private field names, from which it is impossible to guess that
the **declaration** is what is wrong rather than the spy. The
[`no-mocked-for-spy`](https://asdalexey.github.io/vitest-auto-spy/utilities/eslint-plugin) rule catches it mechanically.

---

Source: https://asdalexey.github.io/vitest-auto-spy/core/performance

# Performance

Short version: **use `provideAutoSpy` on Angular and `createSpyFromClass` everywhere else, call it in
`beforeEach`, and stop thinking about it.** The numbers below exist so that claim is checkable, and
so the two settings that *do* cost something are named.

## Measured

`npm run bench` (Vitest bench, one machine — treat the ratios as the result, not the absolute
times). The figures are the **`p75`** column: these cases allocate spy objects by the hundred
thousand, so `hz` swings several-fold between runs as GC pauses land in different samples, while
`p75` reproduces to the fourth decimal.

| Operation | per call (p75) |
| --- | ---: |
| spy a 10-method class, call 2 methods — lazy (the default) | **5.4 µs** |
| the same, eager (`lazySpies: false`) | 17.5 µs |
| spy a 40-method class, call 3 methods — lazy | **10.3 µs** |
| the same, eager | 68.6 µs |
| `createAutoMock<Service>()` + 4 accesses | 7.8 µs |
| `calledWith` dispatch, 3 configured calls | 0.5 µs |

Lazy widens as the class does, and gives it back only when a single test really calls every method
(10 methods, all 10: 20.7 µs lazy against 19.2 µs eager — a rounding error against the order of
magnitude it wins everywhere else). That asymmetry is why it is the default rather than an option.

Put that against a suite: five providers across two thousand tests is ten thousand calls — under a
tenth of a second for the entire run. Spy construction is not where a slow suite spends its time.
`TestBed` is, which is what [`enableTestBedDiagnostics()`](https://asdalexey.github.io/vitest-auto-spy/adapters/angular#where-a-spec-spends-its-time)
measures and [`renderShallow`](https://asdalexey.github.io/vitest-auto-spy/adapters/angular#shallow-component-rendering) usually fixes.

## Why it is fast

`lazySpies` is on by default for every factory: a spy is built on first access rather than for every
method up front, so a twenty-method service a test touches twice builds two spies. `provideAutoSpy`
was the only entry with that default until v2; now the core has it too, and the two are the same
speed.

The other half is a cache: prototype discovery (`getAllMethodNames`) is memoised per prototype in a
`WeakMap`, so calling the factory once per test does not re-walk the chain. A class spied in 300
tests walks its prototype once.

## Memory, not just time

The same benchmark shape, but holding the spies (2000 of them, a 40-method class, two methods
touched per spy — a large spec file's worth):

| | time | heap |
| --- | ---: | ---: |
| lazy (the default) | **22 ms** | **35.4 MB** |
| eager (`lazySpies: false`) | 203 ms | 372.7 MB |

Nine times the speed and a tenth of the memory, because 38 of the 40 spies are never built. Each
one that is skipped is a function, its argument map, and the promise/observable helper bundles
attached to it.

The worst case for lazy is a test that really does call every method:

| | time | heap |
| --- | ---: | ---: |
| lazy | 228 ms | 372.9 MB |
| eager | 216 ms | 372.4 MB |

### What a single spy costs

A materialised spy is mostly the host runner's own mock — under Vitest that is the larger part of
its ~4.7 kB, and nothing this library does can shrink it. What the library adds on top used to
include two `calledWith` chains built with every spy, each an object plus an argument map, whether
or not the spec ever called `calledWith`. They are now built on first use, which is nearly always
never:

| 2000 spies × 40 methods, all materialised | heap |
| --- | ---: |
| chains built eagerly (before) | 417.3 MB |
| chains built on first use | **372.7 MB** |

That is ~560 B off every materialised spy, ~11% of the total, and it costs nothing when a spec does
use `calledWith` — the chain is then built exactly as before. `resetAutoSpy()` drops the chains
rather than replacing them with empty maps, so a reset spy is back to a fresh spy's footprint.

Five percent slower, one percent more memory — the price of the accessor indirection when nothing is
saved. That asymmetry is why lazy is the default rather than an option: the common case wins an
order of magnitude, the rare case loses a rounding error.

Memory matters more than the time here. Under `isolate: false` a worker keeps everything its files
allocated until the run ends, and it is the heap — not the clock — that ends up killing a CI job in
a container.

## Bundle size

The badge says 6.2 kB min+gzip, and that is the whole core entry bundled together. What a consumer
actually pays is less, because the package is side-effect-free per entry and every bundler shakes it:

| Imported | min+gzip |
| --- | ---: |
| the whole core entry (what the badge measures) | 6.2 kB |
| `createSpyFromClass` alone | **3.6 kB** |
| `createSpyFromClass` + `createMock` | 3.6 kB |
| the observer stubs alone | 1.4 kB |

The framework adapters, rxjs layer, console spies and setup helpers live behind their own subpaths,
so a project that never imports them never pays for them — and none of this reaches a production
bundle in the first place, since the package is a devDependency.

The download is smaller than it was, for a reason worth stating plainly: the package used to ship a
CommonJS build of every entry point, and most of it could never be loaded. Vitest refuses to be
required (`Vitest cannot be imported in a CommonJS module using require()`), so eight of the twelve
`.cjs` files threw on their own first line; and because esbuild cannot code-split CommonJS, each
surviving one carried its own copy of the `MockAdapter` / `ObservableSupport` registries, so even
`require('vitest-auto-spy/rxjs')` next to `require('vitest-auto-spy/node')` failed with "Observable
spies require rxjs" — two bundles, two disconnected registries. CommonJS now ships only where a
`require()` actually works and needs no second entry: `vitest-auto-spy/node` and
`vitest-auto-spy/eslint-plugin`. Folding `bun-angular` into the same ESM pass as everything else
removed a second inlined copy of the core on top of that.

| | Before | After |
| --- | ---: | ---: |
| `dist/` | 625 kB | **241 kB** |
| published tarball | 187 kB | **108 kB** |
| files in the package | 74 | **54** |

## Which Node version

The library's own code runs unchanged from Node 18 up, so this is a question about the runtime
underneath it, not about compatibility. Measured on one machine across six versions, three ways: the
**core in isolation** (`src/lib/**` bundled and driven by a minimal mock adapter — 13 reps, the
`p75` of ns/op, no runner inside the measurement), the repo's own 39-file suite through
`vitest run` (best of three), and a cold `import('vitest-auto-spy/node')`.

| Core operation (p75, ns/op) | 18 | 20 | 22 | 24 | 25 | 26 |
| --- | ---: | ---: | ---: | ---: | ---: | ---: |
| `createSpyFromClass`, 10 methods | 1410 | 1433 | 1264 | 1323 | 1416 | **1285** |
| lazy, 10 methods / 2 called | 3056 | 3578 | 3096 | 2869 | 2934 | **2852** |
| eager, 10 methods / 2 called | 5180 | 4703 | 4222 | **3954** | 4073 | 4096 |
| eager, 40 methods / 3 called | 20026 | 18145 | 17206 | **15635** | 16373 | 15945 |
| lazy, 40 methods / all 40 called | 42028 | 43630 | 40384 | 34933 | 35748 | **34325** |
| `createAutoMock<T>()` + 4 accesses | 2237 | 2489 | 2074 | **1756** | 1821 | 1782 |

The break is between 22 and 24 — V8 12.4 to 13.6 — and it is 9–15% on every case that allocates
spies. 24, 25 and 26 are the same speed within noise; 20 is not an improvement on 18.

| | 20 | 22 | 24 | 25 | 26 |
| --- | ---: | ---: | ---: | ---: | ---: |
| the 39-file suite, `vitest run` | 3.75 s | 3.31 s | 2.67 s | 2.69 s | **2.54 s** |
| cold `import('vitest-auto-spy/node')` | 10.2 ms | 11.8 ms | 4.9 ms | **4.3 ms** | 4.5 ms |
| process startup | 9.9 ms | 10.8 ms | 7.9 ms | **7.4 ms** | 7.7 ms |
| peak RSS of the suite | 2647 MB | **2565 MB** | 3599 MB | 3432 MB | 3019 MB |
| RSS after the import | **40 MB** | 51 MB | 51 MB | 54 MB | 57 MB |

Import cost more than halves at 24, which is per worker rather than per run — it is the one number
that scales with how many files a suite spreads across.

**What a spy costs does not change with the version.** Held heap per spy is identical to the byte on
all six — 13584 B eager (10 methods), 5513 B lazy with two methods touched, 2473 B lazy untouched.
The RSS rows above move because newer V8 starts with a larger heap and lets more garbage accumulate
before collecting, not because the library allocates differently.

So: **run 24 (or 26)**. The only argument for staying on 22 is a memory-capped CI container — a
gigabyte of peak RSS separates them — and on 24 that is what `--max-old-space-size` is for, rather
than a slower runtime. Node 18 and 20 are both past end-of-life, and Node 18 additionally cannot run
Vitest 4 at all (see [Installation](https://asdalexey.github.io/vitest-auto-spy/core/installation)).

::: details Why `npm run bench` is not the source for this table
The cross-version numbers here come from a standalone harness, not from the repo's Vitest bench.
Vitest bench was tried first and rejected: consecutive runs of the same case on the same version
returned 0.0090 ms and 5.06 ms — GC pauses landed in different samples and swamped a 10% difference
between runtimes. That particular swing has since been traced and fixed at the source: `@vitest/spy`
keeps every mock it ever creates in a module-level strong `Set`, so nothing a bench case allocated
was collectable and each case ran into the heap the previous one had left. `bench/auto-spy.bench.ts`
now calls this package's own `pruneMockRegistry()` at the end of every case, and the table above
reproduces within 1.0–1.2× across consecutive runs. `npm run bench` still cannot compare two
runtimes — a separate process per version, with the runner outside the measurement, is the only
honest way to do that — but it is no longer the GC it was measuring.

## What to reach for

| Situation | Use | Why |
| --- | --- | --- |
| Angular dependency | `provideAutoSpy(Service)` | the DI provider, written for you |
| A class, no Angular | `createSpyFromClass(Service)` | same factory, same lazy default |
| No class at runtime — an interface, a type | `createAutoMock<T>()` | Proxy; materialises on access |
| An ngrx `signalStore()` | `createAutoMock<T>()` | its members live on the instance, so there is no prototype to read |
| A data shape the code only reads | `createMock<T>(partial)` | no spies at all — it is one checked assertion |
| Nested object graph | `mockDeep<T>()` | auto-creates chainable spies down the tree |

## The two settings that cost

**`{ lazySpies: false }`** gives up the win above, and costs an order of magnitude in both time and
memory on a wide class. It is worth it only when a spec inspects the spy object itself through
property descriptors — enumeration (`Object.keys`, spread, a snapshot) already works, because the
placeholders are enumerable accessors.

**`autoSpyAccessors: true`** walks the prototype chain for getters and setters. That walk is
memoised per prototype in a `WeakMap`, exactly like the method walk, so a class spied in 300 tests
pays for it once — this page said otherwise until v3.6.0 and was simply out of date. What the option
still costs per spy is the accessor indirection itself, measured above at five percent; reach for an
explicit `gettersToSpyOn` / `settersToSpyOn` list when you want a smaller surface, not for speed.

Everything else — `methodsToSpyOn`, `observablePropsToSpyOn`, `calledWith`, the return-type helpers
— is either a constant or, in `calledWith`'s case, a sub-microsecond map lookup on a serialized key.

The one `calledWith` shape that is not sub-microsecond is a config holding an **asymmetric matcher**
(`expect.any`, `expect.objectContaining`). Those cannot be a static key, so they are kept as
predicates and evaluated against the actual args after the exact map misses — which means a deep
walk of whatever else is in that config. The config args are serialized once when the config is
registered rather than on every call, which halves it: an asymmetric config whose other argument is
a 200-key object went from **27.3 µs to 14.3 µs** per invocation. Reach for an exact `calledWith`
when you have one; the exact map is flat at 186–237 ns from 1 to 100 configs.

## What actually makes a suite slow

Spy construction is measured above and is not it. The two things that are, both measured on the same
machine as the rest of this page, against a generated Angular suite where every file configures a
`TestBed`, provides `provideAutoSpy(Service)` and renders a component with children — i.e. the shape
of a real component-heavy spec.

### 1. One environment instead of one per file

The default run gives each file its own environment. A shared one — `isolate: false` plus
`fileParallelism: false` — pays for jsdom and the zoneless `TestBed` once for the whole run:

| Suite | Default run | Shared environment | Change |
| --- | ---: | ---: | ---: |
| 100 files | 1.78 s | **1.12 s** | −37% |
| 400 files | 4.90 s | **2.54 s** | −48% |

Three runs per cell, spread under ±0.03 s. The saving is per file, so it grows with the suite: the
400-file run saves twice what the 100-file run saves.

Two things that measurement corrects, both worth knowing before you copy a config:

- **`fileParallelism: false` is the lever, not `isolate: false`.** Flipping `isolate` alone, with the
  default pool, measured 1.76 s against the default's 1.78 s — inside the noise. What collapses the
  per-file cost is landing every file in one worker (`fileParallelism: false` forces `maxWorkers` to
  1). `isolate: false` is what makes running that way *safe to leave on*, which is the whole reason
  [`setupAutoSpy()`](https://asdalexey.github.io/vitest-auto-spy/utilities/setup) exists — it is not itself the speed-up.
- **`poolOptions: { threads: { singleThread: true } }` does nothing on Vitest 4.** `test.poolOptions`
  was removed; Vitest logs `was removed in Vitest 4` and ignores it. The top-level
  `fileParallelism: false` replaces it.

On a suite small enough that Vitest's own startup dominates, none of this shows up in the clock —
this library's own 39-file suite runs in ~1.03 s either way. The work still collapses, and that is
what scales: aggregate setup 6.3 s → 0.23 s, environment 5.2 s → 0.19 s, transform 3.1 s → 0.32 s.

### 2. Rendering the child subtree

[`renderShallow`](https://asdalexey.github.io/vitest-auto-spy/adapters/angular#shallow-component-rendering) brings the component up through
the real `TestBed` without its children and without its template. Per render, on a component holding
two `@for` tables whose row count is varied:

| Child instances | `TestBed.createComponent` | `renderShallow` | Ratio |
| ---: | ---: | ---: | ---: |
| 0 | 0.65 ms | 0.55 ms | 1.2× |
| 10 | 1.00 ms | 0.55 ms | 1.8× |
| 100 | 2.72 ms | **0.48 ms** | 5.7× |
| 400 | 8.52 ms | **0.53 ms** | 16.2× |

The shape is the point: `renderShallow` is flat at ~0.5 ms because it never builds the subtree, while
`createComponent` scales linearly with it. So the win is not a fixed percentage — it is however much
markup the component under test happens to own. On a leaf component with no children there is nothing
to save (1.2×); on a table or a dashboard it is an order of magnitude.

This is only worth taking because [templates are not what a spec asserts on](https://asdalexey.github.io/vitest-auto-spy/recipes). A test that
reads component state pays for the subtree and gets nothing back for it.

### 3. Worker count

With a shared environment more workers stop helping early: each one re-imports the whole module graph
and has nobody to share that work with. Measure before raising it — on the suites above, one worker
beat the default pool outright at both sizes.

---

Source: https://asdalexey.github.io/vitest-auto-spy/recipes

# Spec patterns

The API reference says what each helper does. This page says which ones you will actually reach for,
in what order, and what breaks at scale — measured against a private Angular 22 zoneless suite of
roughly 370 spec files that has been on this library since early versions.

The distribution is lopsided, and worth knowing before you learn the whole surface:

| Helper                                             | Spec files using it |
| -------------------------------------------------- | ------------------: |
| [`provideAutoSpy`](https://asdalexey.github.io/vitest-auto-spy/adapters/angular)               |                 371 |
| [`injectSpy`](https://asdalexey.github.io/vitest-auto-spy/adapters/angular)                    |                 308 |
| [`mockReadonlyProp`](https://asdalexey.github.io/vitest-auto-spy/adapters/angular#signal-readonly-property-mocking) |           127 |
| [`mockValueProp`](https://asdalexey.github.io/vitest-auto-spy/adapters/angular#signal-readonly-property-mocking)    |           104 |
| `instanceMethodsToSpyOn`                            |                 103 |
| `observablePropsToSpyOn`                            |                  79 |
| [console spies](https://asdalexey.github.io/vitest-auto-spy/utilities/console)                 |                  68 |
| [`createSpyFromClass`](https://asdalexey.github.io/vitest-auto-spy/core/create-spy-from-class) |                  41 |

Two things follow. **`createSpyFromClass` is the exception, not the rule** — in an Angular app the
spy almost always arrives through DI. And **`instanceMethodsToSpyOn` is not an edge case**: in a
signals codebase it appears in more than a quarter of all spec files, because `signal()` and
`computed()` fields are exactly the callables prototype discovery cannot see.

## The canonical service spec

```ts
import { signal } from '@angular/core';
import { TestBed } from '@angular/core/testing';
import { of } from 'rxjs';
import { injectSpy, provideAutoSpy, type Spy } from 'vitest-auto-spy/angular';

describe('TaskService', () => {
  let projects: Spy<ProjectStore>;
  let feed: Spy<NewsFeedService>;
  let service: TaskService;

  beforeEach(() => {
    TestBed.configureTestingModule({
      providers: [
        // plain service — every prototype method is spied, nothing to configure
        provideAutoSpy(NotificationService),
        // signals and computed live on the INSTANCE, so they are named explicitly
        provideAutoSpy(ProjectStore, { instanceMethodsToSpyOn: ['current', 'isEmpty'] }),
        // Observable *properties* are named too — methods returning one are not
        provideAutoSpy(NewsFeedService, { observablePropsToSpyOn: ['connected$'] }),
      ],
    });

    projects = injectSpy(ProjectStore);
    feed = injectSpy(NewsFeedService);

    // seed the defaults every test needs, once
    feed.connected$.nextWith(true);
    projects.save.mockReturnValue(of(true));

    service = TestBed.inject(TaskService);
  });

  it('saves through the store', () => {
    service.save(task);

    expect(projects.save).toHaveBeenCalledWith(task);
  });
});
```

Four conventions carry most of the value:

1. **One `configureTestingModule` per `describe`.** Reconfiguring per `it()` pays for module
   compilation on every test; it is the single largest avoidable cost in an Angular suite.
2. **Declare each spy as `Spy<T>`, resolve it with `injectSpy`.** Never as `T` — `Spy<T>` is a mapped
   type and drops private members ([why](https://asdalexey.github.io/vitest-auto-spy/core/spy-typing)).
3. **Seed defaults in `beforeEach`, override in the test.** A method that returns an `Observable` and
   is never configured returns `undefined`, and the failure surfaces far from its cause.
4. **`provideAutoSpy` is lazy by default**, so listing a wide service costs nothing for the methods a
   test never touches.

## Signals

A signal is a callable field on the instance, which puts it in two places at once. Which helper you
need depends on whether you are mocking a **dependency** or the **class under test**.

```ts
// a DEPENDENCY's signal — name it, and the spy is a mock you configure like any other
provideAutoSpy(ProjectStore, { instanceMethodsToSpyOn: ['current', 'isEmpty'] });
injectSpy(ProjectStore).current.mockReturnValue({ id: 1 });

// the CLASS UNDER TEST's own signal / computed / input — replace the field with a real signal
mockReadonlyProp(component, 'selected', signal(true));
mockReadonlyProp(component, 'items', signal([]));
mockReadonlyProp(component, 'host', signal({ nativeElement: element }));
```

`mockReadonlyProp(target, key, signal(value))` is the workhorse — a real signal, so anything
`computed()` downstream of it recomputes correctly, which a `vi.fn()` returning a value would not do.
For a value that has to change during the test, `mockSignalProp` is that pair in one call and hands
back the writable half:

```ts
const selected = mockSignalProp(component, 'selected', false);

selected.set(true); // every computed reading it updates
```

It also removes the temptation to reach for `component.selected` and call `.set` on it — `Signal<T>`
has no `set`, so that only type-checks behind an assertion.

Use `mockReadonlyPropGetter` when the value must be recomputed on each read rather than replaced, and
`mockValueProp` for an ordinary writable field.

**`vi.restoreAllMocks()` does not undo these**
They redefine property descriptors, which the runner's spy registry knows nothing about. Wire
[`setupAutoSpy()`](https://asdalexey.github.io/vitest-auto-spy/utilities/setup) — it registers `restoreMockedProps()` in a global `afterEach`.
Without it, a patch on a global, a prototype or a singleton leaks into the next file under
`isolate: false`.

## Observable properties vs. observable methods

The distinction trips people up because the names look the same:

```ts
class NewsFeedService {
  readonly connected$ = new BehaviorSubject(false); // a PROPERTY  → observablePropsToSpyOn
  watch(id: number): Observable<Item> {}            // a METHOD    → nothing to configure
}

provideAutoSpy(NewsFeedService, { observablePropsToSpyOn: ['connected$'] });

feed.connected$.nextWith(true);     // the property, driven by the helpers
feed.watch.nextWith(item);          // the method, spied automatically
```

A method that returns an `Observable` is discovered on the prototype like any other, and gets the
observable helpers from its **return type**. Only properties need naming — nothing on the prototype
points at them.

Both need the rxjs layer loaded once, in your setup file:

```ts
import 'vitest-auto-spy/rxjs';
```

Without it, `nextWith` throws with an error saying exactly that.

## Reaching a spy that `injectSpy` cannot

`injectSpy(X)` reads the **global** `TestBed` injector. A provider declared on the component itself
(`@Component({ providers: [...] })`) lives in the element injector, which `TestBed.inject` never
sees. Go through the fixture and re-view the result:

```ts
import { asSpy } from 'vitest-auto-spy';

const player = asSpy(fixture.debugElement.injector.get(PlayerService));

player.play.mockReturnValue(true);
```

The mirror direction — handing a spy to a plain function typed against the real class — is
[`asInstance`](https://asdalexey.github.io/vitest-auto-spy/core/spy-typing):

```ts
expect(isEnabled(asInstance(featureFlags))).toBe(true);
```

Both are the same object at runtime. Reach for them only at these boundaries; a suite that needs one
in every file has declared its variables as `T` instead of `Spy<T>`.

## ngrx signals

A `signalStore()` puts everything on the **instance**, so prototype discovery finds nothing at all:

```ts
// either name every member you touch…
provideAutoSpy(TaskStore, { instanceMethodsToSpyOn: ['entities', 'isLoading', 'load'] });

// …or skip the class and mock from the type, which needs no prototype
const store = createAutoMock<TaskStore>();
```

`createAutoMock<T>()` is usually the better trade for a store: every accessed member becomes a spy
lazily, so nothing has to be listed and the list cannot fall behind the store.

An `rxMethod` is a function with a `destroy` property, which a bare mock does not have — build it
explicitly, or the component's cleanup throws:

```ts
const load = Object.assign(vi.fn(), { destroy: vi.fn() });
```

## Effects

Do not try to replace `effect()` by mocking `@angular/core`. Under the Angular unit-test builder the
specs are bundled and `@angular/core` sits in a shared chunk, so replacing it re-enters a chunk that
is still initialising and fails with `Cannot access '__vi_import_N__' before initialization`. The
same applies to any module those shared chunks depend on.

Assert the effect's **result** instead: set the signals it reads, let it run, and check what it
produced.

```ts
mockReadonlyProp(component, 'state', signal(State.Selected));

await stable(fixture); // flush effects, then await the fixture

expect(component.icon()).toBe('favouritesFilled');
```

[`stable(fixture)`](https://asdalexey.github.io/vitest-auto-spy/adapters/angular#zoneless-waiting) is the one to reach for:
`fixture.detectChanges()` runs a single change-detection pass and does **not** flush pending effects,
so an assertion right after it reads state that has not finished computing. `flushEffects()` is the
no-fixture half, for services and stores. The wait is bounded — 2000 ms by default, then it throws
the cause instead of leaving the runner to report a file-level timeout.

### A component that loads through `httpResource()`

```ts
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]);
```

[`settleResource`](https://asdalexey.github.io/vitest-auto-spy/adapters/angular#resources-httpresource-and-resource) is one wait for
`httpResource()`, `resource()` and `rxResource()`, which each need a different number of turns.
Asserting before it reads the resource's _default_ value and passes, which is the failure mode worth
knowing: a green test proving nothing until the day the default changes.

When the effect will never go dirty on its own — because its trigger is now a static signal —
`runEffect` runs that one body directly:

```ts
runEffect(component.highlightEffect); // current signal values, no scheduler involved
```

## Observers the component constructs itself

`IntersectionObserver`, `ResizeObserver` and `MutationObserver` are built inside the code under test
and kept private, so the only handle a spec has is the global constructor. Replacing it by hand goes
wrong twice: the stub is never taken off (and the next file inherits it under `isolate: false`), and
the instance is reached through a `static last` that outlives the spec just as badly.

```ts
import { intersectionEntry, stubIntersectionObserver } from 'vitest-auto-spy';

const observers = stubIntersectionObserver();

fixture.detectChanges(); // the directive constructs its observer

observers.last.emit([intersectionEntry(fixture.nativeElement, true)]);
await fixture.whenStable();
```

The stub installs through `mockValueProp`, so `restoreMockedProps()` — which `setupAutoSpy()`
already runs — puts the real constructor back. `emit()` takes a **batch**, because a fast scroll
delivers several entries in one call and code assuming one entry per call is a real bug worth
reaching.

## Timers that outlive their file

This one only appears at scale, and it appears as a failure in an **innocent** file.

With `isolate: false` every spec file in a worker shares one environment. A `setTimeout` a component
schedules and never clears keeps running after its file is done; the callback then fires while the
next file is mid-test, against mocks and a DOM that no longer match. `requestAnimationFrame` matters
just as much in a zoneless app — Angular's change-detection scheduler races a `setTimeout` against a
frame callback, so a destroyed component can still have one queued.

Symptoms, all reported against the wrong file:

- `Schedulers cannot synchronously execute watches while scheduling`
- `signal read during notification phase`
- an unhandled rejection naming a component the failing file never imported

One option covers it — it wraps the schedulers once, records every handle, and cancels the survivors
in `afterAll`:

```ts
// vitest.setup.ts
setupAutoSpy({ strayTimers: true });
```

The pieces are exported too, for a suite that wants the sweep somewhere else or wants a leak to
**fail** rather than be tidied away:

```ts
import { cancelStrayTimers, countStrayTimers, trackStrayTimers } from 'vitest-auto-spy/setup';

trackStrayTimers(); // once, as early as the setup file runs — idempotent
afterEach(() => expect(countStrayTimers()).toBe(0)); // treat a leak as a failure
afterAll(() => cancelStrayTimers()); // …or just sweep, and log the count it returns
```

If you are on `isolate: false`, assume you need this before you need it.

## A green run that still exits 1

happy-dom implements `fetch`; jsdom does not. Move a suite from one to the other and a component
that pulls a remote asset starts issuing real requests. Nothing asserts on them, so every test still
passes — and then the runner tears the environment down, the in-flight requests abort, and the
aborts arrive as unhandled rejections *after* the summary:

```text
 Test Files  260 passed (260)
      Tests  2257 passed (2257)

Vitest caught 8 unhandled errors during the test run.
DOMException [AbortError]: The operation was aborted.
```

Exit code 1, and no test named — because no test failed.

```ts
setupAutoSpy({ blockNetwork: true });
```

`fetch` then rejects immediately, naming the URL that was requested, and the code under test takes
exactly the branch it would take for a failed request. `XMLHttpRequest` and `navigator.sendBeacon`
go the same way — jsdom implements XHR in full, and a library that never left it (an ad player
pinging VAST trackers, say) reaches the internet from a suite that thought it was blocked. For a
suite whose outbound requests are pings nobody reads the response of, answer them instead of
failing them:

```ts
setupAutoSpy({ blockNetwork: { xhr: 'empty' } });
```

## Fake timers

```ts
import { advanceTimers, setupFakeTimers } from 'vitest-auto-spy/setup';

setupFakeTimers(); // once per describe — pairs install with restore

it('debounces', async () => {
  component.search('query');

  await advanceTimers(300); // advance AND drain the microtasks the advance queues
  await stable(fixture);

  expect(api.search).toHaveBeenCalledWith('query');
});
```

`vi.advanceTimersByTime()` alone leaves the promise chain the timer resolved still pending, which is
what makes a timer assertion read like a race. `advanceTimers()` closes that gap.

## Console

Import the entry once and assert on the exported spies; the output is silenced rather than printed.

```ts
import { consoleErrorSpy } from 'vitest-auto-spy/console';

service.handle(brokenPayload);

expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining('parse'));
```

Never add a second `vi.spyOn(console, 'error')` on top: whichever patch wins depends on import order,
and the assertion then runs against a spy that never intercepted the call.

## An array assertion that says nothing

```ts
import { diffByField } from 'vitest-auto-spy';

const sent = analytics.send.mock.calls.map(([event]) => event);

expect(diffByField(sent, expectedEvents)).toBeUndefined();
```

Comparing collected records against an expected list is the ordinary shape of a test for anything
that accumulates — an analytics queue, an audit log, a command history. And the ordinary cause of a
mismatch is not "the wrong element" but "one field moved in all of them": a timestamp, an id, a
counter.

That is the failure the reporter renders worst. It collapses the objects, so what arrives is
`expected [ { event_timestamp: 1, …(5) }, …(8) ] to deeply equal [ { …(6) }, … ]` — nine elements,
one changed field, nothing on screen to say which, and a `console.dir(…, { depth: null })` and two
more runs to find out. `diffByField` answers it directly:

```text
9 of 9 elements differ.
  `event_timestamp` differs in all 9: actual 1 everywhere, expected 2, 3, 4, 5, 6, 7, …
```

"Everywhere" against a run of expected values is the tell: under fake timers every `Date.now()`
inside one test answers the same, so a spec about **order** or **duration** needs
[`useCountingClock()`](https://asdalexey.github.io/vitest-auto-spy/utilities/event-loop#usecountingclock-options) rather than a frozen clock.

## What not to do

| ❌                                                          | ✅                                                            |
| ----------------------------------------------------------- | ------------------------------------------------------------- |
| a hand-written `{ provide: X, useValue: { a: vi.fn() } }`     | `provideAutoSpy(X)`                                            |
| `vi.spyOn(TestBed.inject(X), 'method')`                       | `injectSpy(X).method`                                          |
| `Object.defineProperty(service, 'ready', { value: true })`    | `mockReadonlyProp(service, 'ready', true)`                     |
| `let s: MyService = createSpyFromClass(MyService)`             | `let s: Spy<MyService>`                                        |
| `source$.subscribe(v => expect(v).toBe(1))`                    | `await expect(expectEmission(source$)).resolves.toBe(1)`       |
| `expect(component.total).toBeTruthy()` on a signal             | `expect(component.total).toHaveSignalValue(3)`                 |
| `configureTestingModule` inside every `it()`                   | one per `describe`                                             |
| `methodsToSpyOn` used to *restrict* the set                    | `onlyMethodsToSpyOn` restricts; `methodsToSpyOn` adds           |

Row five is the one worth being convinced of rather than told: the same false assertion written
four ways against four streams, and [the run that leaves every `subscribe` form
green](https://asdalexey.github.io/vitest-auto-spy/core/observable-assertions#measured-four-forms-against-four-streams).

The first three are enforceable — [the ESLint plugin](https://asdalexey.github.io/vitest-auto-spy/utilities/eslint-plugin) has a rule for each.
Scope it to spec files: an object of `vi.fn()`s is perfectly reasonable in application code.

---

Source: https://asdalexey.github.io/vitest-auto-spy/runtimes/vitest

# Vitest

The default, zero-config entry point. Importing `vitest-auto-spy` registers the Vitest mock
adapter (`vi.fn()` / `vi.spyOn()`) and exposes the full core API.

```ts
import { createSpyFromClass } from 'vitest-auto-spy'; // Vitest (default, zero-config)
```

The core is runner-agnostic behind a `MockAdapter`; the Vitest entry registers the default adapter
on import, so existing usage stays unchanged. Native mock methods (e.g. `mockReturnValue`) remain
Vitest's own — only the auto-spy helpers are normalised across runtimes.

## A spec, start to finish

```ts
import { beforeEach, describe, expect, it } from 'vitest';
import { type Spy, createSpyFromClass } from 'vitest-auto-spy';

import { UserService } from './user.service';
import { Greeter } from './greeter';

describe('Greeter', () => {
  let users: Spy<UserService>;
  let greeter: Greeter;

  beforeEach(() => {
    users = createSpyFromClass(UserService);
    greeter = new Greeter(users);
  });

  it('greets the name the service returns', () => {
    users.getName.calledWith(1).mockReturnValue('Ada');

    expect(greeter.greet(1)).toBe('Hello, Ada!');
    expect(users.getName).toHaveBeenCalledWith(1);
  });
});
```

## What belongs in the setup file

Nothing is required to create a spy. Two things are global by nature and belong in
`setupFiles` rather than in a spec:

```ts
// vitest.setup.ts
import 'vitest-auto-spy/rxjs'; // once — enables nextWith / observablePropsToSpyOn everywhere
import { setupAutoSpy } from 'vitest-auto-spy/setup';

setupAutoSpy();
```

```ts
// vitest.config.ts
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    setupFiles: ['./vitest.setup.ts'],
  },
});
```

- **`import 'vitest-auto-spy/rxjs'`** registers the observable layer. Without it, using an observable
  helper (`nextWith`, `observablePropsToSpyOn`, …) throws a message naming this exact import — a spy
  factory never pulls rxjs in on its own.
- **[`setupAutoSpy()`](https://asdalexey.github.io/vitest-auto-spy/utilities/setup)** restores `mock*Prop` patches, resets the mock registry and
  fails the run on a duplicate installed copy of the package.

Registering [signal matchers](https://asdalexey.github.io/vitest-auto-spy/adapters/angular) (`toHaveSignalValue`) is a third setup-file
candidate for Angular suites: `registerSignalMatchers()` from `vitest-auto-spy/angular`.

## Isolation

Vitest isolates each file by default, so a leftover property patch or a spy stored in a
module-scope variable dies with the file. Turning that off (`isolate: false`, a shared environment,
a single thread) is exactly the mode `setupAutoSpy()` exists for — this package runs its own suite
both ways in CI for that reason.

```ts
// vitest.config.ts — the mode to be careful in
export default defineConfig({
  test: {
    isolate: false,
    setupFiles: ['./vitest.setup.ts'], // now doing real work
  },
});
```

## The Angular subpath

An Angular suite imports from `vitest-auto-spy/angular` instead — it registers the same Vitest
adapter and adds the `TestBed` helpers:

```ts
import { injectSpy, provideAutoSpy, renderShallow, stable } from 'vitest-auto-spy/angular';
```

It needs an Angular-aware Vitest setup (for example `@analogjs/vite-plugin-angular` plus a
`setupTestBed()` call). See [Angular](https://asdalexey.github.io/vitest-auto-spy/adapters/angular) — and
[Angular on Bun](https://asdalexey.github.io/vitest-auto-spy/runtimes/bun-angular) for the same suite under `bun test`.

---

Source: https://asdalexey.github.io/vitest-auto-spy/runtimes/bun

# Bun (`bun:test`)

The `vitest-auto-spy/bun` entry runs the exact same core on Bun's `bun:test` mocks instead of
Vitest.

```ts
import { createSpyFromClass } from 'vitest-auto-spy/bun'; // Bun — bun:test
```

The public API (`createSpyFromClass`, `calledWith`, `resolveWith`, `nextWith`, …) is **identical**
to the Vitest entry. Only **native** mock methods stay the runner's own; the auto-spy helpers are
normalised. Import the entry matching your runner — it registers the Bun adapter on import.

Testing Angular under `bun test` has its own entry, [`vitest-auto-spy/bun-angular`](https://asdalexey.github.io/vitest-auto-spy/runtimes/bun-angular).

## A runnable example

```ts
// user.test.ts
import { describe, expect, it } from 'bun:test';
import { type Spy, createSpyFromClass } from 'vitest-auto-spy/bun';

class UserService {
  getName(id: number): string {
    return `user-${id}`;
  }

  async load(id: number): Promise<string> {
    return `loaded-${id}`;
  }
}

describe('UserService spy', () => {
  it('returns per-argument values and resolves promises', async () => {
    const users: Spy<UserService> = createSpyFromClass(UserService);

    users.getName.calledWith(7).mockReturnValue('seven');
    users.load.resolveWith('ok');

    expect(users.getName(7)).toBe('seven');
    await expect(users.load(1)).resolves.toBe('ok');
    expect(users.getName).toHaveBeenCalledWith(7);
  });
});
```

```bash
bun test
```

The optional rxjs layer works the same way — `import 'vitest-auto-spy/rxjs'` once, and
`nextWith` / `nextWithValues` / `observablePropsToSpyOn` are available on Bun too.

## What differs from Vitest

Everything the library normalises reads the same on both runners; what is left is Bun's own mock
behaviour, and it is worth knowing which is which.

| Behaviour                     | Vitest                       | Bun                                                     | Who handles it                                     |
| ----------------------------- | ---------------------------- | ------------------------------------------------------- | -------------------------------------------------- |
| `mock.settledResults`         | native                       | not tracked                                             | polyfilled — reads identically on both              |
| `mockReset()`                 | keeps the spy, clears calls  | also drops the implementation                           | the adapter restores it, so auto-spies survive      |
| `spyOn(obj, 'prop', 'get')`   | supported                    | throws — accessors are not supported yet                | accessor spies go through property redefinition     |
| Spy names in failure messages | `vi.fn()` names              | `mockName()`                                            | set for you                                         |
| Fake timers                   | `vi.useFakeTimers()`         | `jest.useFakeTimers()`                                  | not normalised — `vitest-auto-spy/setup` is Vitest-only |

`mock.settledResults` is documented under
[Control helpers → Inspecting promise outcomes](https://asdalexey.github.io/vitest-auto-spy/core/control-helpers#settled-results).

## Bun 1.4 test-runner flags

Bun 1.4 turned `bun test` into a runner with the scheduling controls a large suite needs. Nothing in
this package has to be configured for them — they are listed here because two of them change how a
suite behaves, and the library's answer differs per flag.

| Flag                          | What it does                                                        | Effect on your spies                                                                                            |
| ----------------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `--isolate`                   | a fresh JavaScript global per test file, in one process             | matches Vitest's default. Registries and property patches cannot leak between files                              |
| _(no flag)_                   | one shared global for the whole run                                 | the mode to be careful in — a property patch or a leftover registry outlives the file that made it                |
| `--parallel[=N]`              | spreads files over worker processes                                 | none: each worker is its own process, so each has its own registry                                                |
| `--shard=M/N`                 | splits files across CI runners                                      | none                                                                                                              |
| `--changed[=ref]`             | only the files your diff touches                                    | none                                                                                                              |
| `--timings` / `--update-timings` | balances shards by recorded wall-clock time                      | none                                                                                                              |
| `--retry <N>` / `{ repeats: n }` | re-runs a flaky or stress-tested test                            | a spy that is not reset between runs accumulates calls — reset in `beforeEach`                                     |

Without `--isolate`, treat a Bun run the way you would treat Vitest's `isolate: false`: restore what
you patch. `restoreMockedProps()` in an `afterEach` covers the property helpers; `resetAutoSpy(spy)`
clears a spy that outlives one test.

**Which mode to run**
`--isolate` is the safer default and costs little; `--parallel` is the one that makes a big suite
fast. They compose: `bun test --isolate --parallel`.

## Compatibility

This package is verified on **Bun 1.4** and tracks `latest` in CI. Its own Bun suite lives in
`src/bun-tests/` and runs on the real `bun:test` — the Vitest suite can only exercise the Bun
adapter against a stub, since `bun:test` does not resolve outside Bun.

---

Source: https://asdalexey.github.io/vitest-auto-spy/runtimes/bun-angular

# Angular on Bun (`bun:test`)

Angular has no `bun test` integration of its own. Two things are missing, and both are fatal on
their own:

1. **No DOM.** Bun ships none, and everything from `platformBrowserTesting()` onwards reads
   `document`.
2. **No template resolution.** `@Component({ templateUrl: './x.html' })` is not an import — nothing
   in the module graph points at the HTML file — so Angular's JIT compiler refuses to build the
   component (_"Component X is not resolved"_). Under Vitest, `@analogjs/vite-plugin-angular` inlines
   it during transform. Bun has no such transform.

`vitest-auto-spy/bun-angular` closes both, plus the wiring around them, from a single preload.

## Setup

```toml
# bunfig.toml
[test]
preload = ["vitest-auto-spy/bun-angular"]
```

```bash
bun add -d @happy-dom/global-registrator   # or: bun add -d jsdom
```

That is the whole configuration. On load the entry:

1. installs a DOM — `@happy-dom/global-registrator` if present, otherwise `jsdom`, and nothing at all
   if a DOM is already there;
2. registers a `Bun.plugin` `onLoad` hook that inlines `templateUrl` / `styleUrl` / `styleUrls` into
   the component source;
3. initialises a **zoneless** `TestBed` environment and resets the testing module after each test;
4. registers the Bun mock adapter, so every spy helper is Bun's.

**It has to be a preload**
A `Bun.plugin` hook only sees modules loaded **after** it is registered. Importing this entry from
inside a spec is too late for the component under test — its template will not be inlined. Importing
it from a spec **as well** is fine: the module is cached and every step is guarded.

## Writing a spec

From here a spec reads exactly like its Vitest counterpart.

```ts
// greeting.test.ts
import { TestBed } from '@angular/core/testing';
import { describe, expect, it } from 'bun:test';

import { GreetingComponent } from './greeting.component'; // declared with templateUrl
import { GreetingService } from './greeting.service';
import { injectSpy, provideAutoSpy, stable } from 'vitest-auto-spy/bun-angular';

describe('GreetingComponent', () => {
  it('renders the name the service returns', async () => {
    TestBed.configureTestingModule({ providers: [provideAutoSpy(GreetingService)] });

    injectSpy(GreetingService).currentName.mockReturnValue('external user');

    const fixture = TestBed.createComponent(GreetingComponent);

    await stable(fixture);

    expect(fixture.nativeElement.textContent).toContain('Hello, external user!');
  });
});
```

```bash
bun test              # add --isolate for a fresh global per file
```

## What you get

| Helper                                    | Works on Bun | Notes                                                   |
| ----------------------------------------- | :----------: | ------------------------------------------------------- |
| `provideAutoSpy` / `injectSpy`            |      ✅      | identical to the Vitest entry, lazy spies by default    |
| `renderShallow`                           |      ✅      | real `ComponentFixture`, child subtree dropped          |
| `createWithAutoSpies`                     |      ✅      | builds a class through Angular DI with every dep spied  |
| `stable` / `flushEffects`                 |      ✅      | zoneless waiting                                        |
| the whole core (`createSpyFromClass`, …)  |      ✅      | re-exported from this entry                             |
| `registerSignalMatchers`                  |      ❌      | needs the runner's `expect.extend` — Vitest only        |
| TestBed diagnostics (`instrumentTestBed`) |      ❌      | needs suite-level runner hooks — Vitest only            |

## Stylesheets

A test runner has no CSS pre-processor, and no spec asserts on styles. So `.css` is inlined verbatim
and everything else (`.scss`, `.less`, `.styl`) becomes an **empty** stylesheet — the component still
compiles and renders. Override it if you genuinely need the text:

```ts
inlineAngularResources(source, path, { inlineStyleExtensions: ['.css', '.scss'] });
```

## Building your own preload

Every piece is exported, so a project with its own preload can compose them instead of taking the
defaults:

```ts
// bun-preload.ts
import { createJsdomRegistrar, inlineAngularResources, registerDomGlobals } from 'vitest-auto-spy/bun-angular';

await registerDomGlobals({
  registrars: [createJsdomRegistrar({ load: () => import('jsdom'), target: globalThis, url: 'https://app.test/' })],
});
```

`registerDomGlobals` returns the name of the registrar that installed the DOM, or `undefined` when
one was already present, and throws with every attempt listed when none worked.

## Limits worth knowing

- **The rewrite is textual, not a parse.** It skips comments and string literals — a `templateUrl`
  written in prose is left alone — but it does not track `${…}` interpolation or regex literals.
- **Line numbers are preserved.** Every inlined value is a single-line literal, so a failing spec's
  stack trace still points at the component's own line.
- **`node_modules` is skipped.** Published Angular libraries are already compiled.
- **This entry is ESM-only.** It awaits its DOM registrar at the top level, which has no CommonJS
  form. Bun runs ESM natively, so nothing is lost.

---

Source: https://asdalexey.github.io/vitest-auto-spy/runtimes/node

# node:test

The `vitest-auto-spy/node` entry runs the same core on `node:test`'s `mock.fn()`.

```ts
import { createSpyFromClass } from 'vitest-auto-spy/node'; // node:test
```

The public API is identical to the Vitest entry. Importing the entry registers the `node:test`
adapter; the auto-spy helpers (`calledWith`, `resolveWith`, `nextWith`, …) are normalised, while
native mock methods stay the runner's own.

## A runnable example

`node:test` ships no `expect`, so pair it with `node:assert` — the spy surface is the same either
way.

```js
// user.test.mjs
import assert from 'node:assert/strict';
import { describe, it } from 'node:test';
import { createSpyFromClass } from 'vitest-auto-spy/node';

class UserService {
  getName(id) {
    return `user-${id}`;
  }

  async load(id) {
    return `loaded-${id}`;
  }
}

describe('UserService spy', () => {
  it('returns per-argument values and resolves promises', async () => {
    const users = createSpyFromClass(UserService);

    users.getName.calledWith(7).mockReturnValue('seven');
    users.load.resolveWith('ok');

    assert.equal(users.getName(7), 'seven');
    assert.equal(await users.load(1), 'ok');
    assert.deepEqual(users.getName.mock.calls[0].arguments, [7]);
  });
});
```

```bash
node --test
```

## Where the native surface differs

`node:test`'s mock is not Jest-compatible, and this is the one place that shows through. The
auto-spy helpers hide it; reading the raw mock does not.

| What you want            | Vitest / Bun                         | `node:test`                                        |
| ------------------------ | ------------------------------------ | -------------------------------------------------- |
| Recorded calls           | `spy.method.mock.calls[0]` → args    | `spy.method.mock.calls[0].arguments`                |
| Replace the implementation | `spy.method.mockImplementation(fn)` | `spy.method.mock.mockImplementation(fn)`            |
| Reset                    | `spy.method.mockReset()`             | `spy.method.mock.resetCalls()` / `restore()`        |
| Return value             | `spy.method.mockReturnValue(v)`      | **absent** — see the note below                     |
| Spy name in diagnostics  | set for you                          | `mock.fn()` has no name — names are absent          |

The last row is the one that bites: `spy.method.mockReturnValue('x')` is a **native** Vitest/Bun
method, and `node:test` has none, so it is `undefined` here. The library's own
`spy.method.calledWith(...).mockReturnValue('x')` **does** work on all three runtimes — it is part of
the normalised surface, not the runner's.

```js
users.getName.calledWith(7).mockReturnValue('seven'); // ✅ everywhere
users.getName.mockReturnValue('seven'); // ❌ not on node:test
```

Prefer the normalised helpers (`calledWith(...).mockReturnValue(...)`, `resolveWith`, `nextWith`)
and the differences stop mattering: they read the same on all three runtimes.

`mock.settledResults` — which `node:test` does not track natively — is provided by a built-in
polyfill, so it reads identically to Vitest (`{ type: 'fulfilled' | 'incomplete' | 'rejected', value }`).
See [Control helpers → Inspecting promise outcomes](https://asdalexey.github.io/vitest-auto-spy/core/control-helpers#settled-results).

## Every mock is retained until `mock.reset()`

`node:test` registers every `mock.fn()` in its module-level `MockTracker` and keeps the reference for
the lifetime of the process. Dropping the spy does not free it; nothing the library does can, either
— `clearAutoSpy()` / `resetAutoSpy()` revert a spy's *configuration*, not the runner's registry.

Measured: 20 000 spies of a 10-method class created and dropped, then two forced collections, held
**435.6 MB**. One `mock.reset()` brought the same measurement to 0.1 MB.

That is Node's behaviour rather than this adapter's, and it stays invisible until a long suite runs
out of heap. Reset the tracker per test and it never comes up:

```js
import { afterEach, mock } from 'node:test';

afterEach(() => {
  mock.reset();
});
```

Vitest and Bun both drop their own registries between files, so this is specific to
`vitest-auto-spy/node`.

**Which runtime**
`node:test` needs no dependency at all beyond Node, which makes it a good fit for a library with no
build step. For an app suite, [Vitest](https://asdalexey.github.io/vitest-auto-spy/runtimes/vitest) or [Bun](https://asdalexey.github.io/vitest-auto-spy/runtimes/bun) will be less work —
both ship `expect` and a watch mode.

---

Source: https://asdalexey.github.io/vitest-auto-spy/runtimes/rxjs

# RxJS

Observable spying lives behind the `vitest-auto-spy/rxjs` subpath, keeping `rxjs` out of the
runtime bundle of non-rxjs projects. Import it **once** (e.g. in your test setup) to enable
observable helpers:

```ts
import 'vitest-auto-spy/rxjs';
```

Both spied **methods** that return an `Observable` and spied **properties** of type `Observable`
get the same control surface:

```ts
myService.getProducts$.nextWith([{ name: 'Product 1' }]); // emit, stream stays open
myService.getProducts$.nextOneTimeWith([{ name: 'X' }]);  // emit one value, then complete
myService.getProducts$.throwWith('FAKE ERROR');           // error the stream
myService.getProducts$.complete();                        // complete the stream

// emit a precise sequence — values, errors, completion, optional delays
myService.getProducts$.nextWithValues([
  { value: [{ name: 'Product 1' }] },
  { errorValue: 'FAKE ERROR' },
  { complete: true },
]);

// a fresh stream per call
myService.getProducts$.nextWithPerCall([{ value: ['a'] }, { value: ['b'] }]);

// grab the underlying Subject for full manual control
const subject = myService.getProducts$.returnSubject();
```

Using an observable spy without importing `vitest-auto-spy/rxjs` throws a clear hint telling you to
add the import. The core's _type_ surface (`Spy<T>`) still references rxjs types, so keep `rxjs`
available for type-checking; none of it reaches your runtime bundle.

## The backing subject, and how long it lives

Every observable helper writes into one `ReplaySubject(1)` per spied member. Its buffer is
**configuration**, in exactly the sense a `calledWith` chain is, and until 3.5.0 it outlived the test
that filled it. Two silent failures came out of that.

```ts
// test 1
service.createSeamlessTransition.nextWith(uri); // buffered

// test 2 — the failure path is what this test is about
service.createSeamlessTransition.throwWith(error); // the subscriber gets `uri` FIRST, then the error
```

The code under test ran the **success** branch on the previous test's data, and the branch the test
existed for arrived one emission late — with nothing in the failure pointing back. The second is
quieter still: `error()` and `complete()` close a Subject for good, so every later `nextWith` on that
spy pushed into a dead subject and emitted nothing.

Both are fixed: `resetAutoSpy(spy)` drops the subject, and a terminated one is replaced by the next
configuration. Two things follow that are worth knowing.

**`vi.clearAllMocks()` and `clearMocks: true` still cannot reach it.** That is not an oversight — it
is the same boundary that keeps them from clearing a `calledWith` chain: the state lives in this
library's closures, not on the runner's mock object. When a spy outlives a test, reset it yourself:

```ts
beforeEach(() => {
  resetAutoSpy(service); // the TestBed is built in beforeAll, so the spy is shared
});
```

**Inside one test, nothing changed.** `nextWith(a)` followed by `throwWith(e)` still means "emit a,
then fail" — both calls belong to one story, and only a reset or a terminal call starts a new one.
`nextWithValues([{ errorValue: e }])` remains the way to build a stream that fails on subscription
regardless of what came before it.

## Standalone observable builder

```ts
import { createObservableWithValues } from 'vitest-auto-spy/rxjs';

const fake$ = createObservableWithValues([{ value: 1 }, { value: 2 }, { complete: true }]);

// or get the subject too
const { values$, subject } = createObservableWithValues([{ value: 1 }], { returnSubject: true });
```

`ValueConfig` (for `nextWithValues`): `{ value, delay? }` | `{ errorValue, delay? }` | `{ complete?, delay? }`.

`ValueConfigPerCall` (for `nextWithPerCall`) is `{ value, delay?, doNotComplete? }`.

## Reading a sequence as a marble

`nextWithValues` emits its entries in order, so the config list maps one-to-one onto a marble
diagram — `delay` is the only thing that puts space between frames.

```ts
myService.getProducts$.nextWithValues([{ value: 'a' }, { value: 'b' }, { complete: true }]);
// (ab|)   — both values synchronously, then completion
```

```ts
myService.getProducts$.nextWithValues([
  { value: 'a' },
  { value: 'b', delay: 20 },
  { complete: true, delay: 10 },
]);
// a 20ms b 10ms |
```

```ts
myService.getProducts$.nextWithValues([{ value: 'a' }, { errorValue: 'boom', delay: 20 }]);
// a 20ms #
```

A `{ complete: false }` entry emits nothing and does not stop the stream — it is the "leave it open"
form. Everything after the first `{ complete: true }` is dropped.

## Timing

- **`delay` is milliseconds**, applied with RxJS's own `delay()` (values, completion) and `timer()`
  (errors). It is real time, not a virtual scheduler.
- **Without a delay, emission is synchronous.** `nextWith` pushes onto a `ReplaySubject` right away,
  so a subscriber that has already run sees the value in the same tick.
- **The backing subject is a `ReplaySubject`**, so a subscriber that arrives *after* the emission
  still receives it. This is what makes `spy.thing$.nextWith(v)` work regardless of whether the code
  under test subscribed first.
- **Under fake timers**, a delayed entry needs the clock advanced.
  [`advanceTimers(ms)`](https://asdalexey.github.io/vitest-auto-spy/utilities/fake-timers) advances **and** drains the microtasks the emission
  queues — a bare `vi.advanceTimersByTime()` leaves the `await` continuation pending, and the
  assertion then reads state from before the callback finished.

```ts
import { advanceTimers, setupFakeTimers } from 'vitest-auto-spy/setup';

setupFakeTimers();

myService.getProducts$.nextWithValues([{ value: 'a', delay: 100 }]);

const seen: string[] = [];
myService.getProducts$.subscribe((value) => seen.push(value));

await advanceTimers(100);

expect(seen).toEqual(['a']);
```

## Asserting instead of subscribing

For the assertion side of a stream — "it emits", "it emits these three", "it stays silent" — use the
[observable assertions](https://asdalexey.github.io/vitest-auto-spy/core/observable-assertions). They are duck-typed, so they work on any
subscribable and pull in no rxjs of their own:

```ts
import { expectEmission, expectNoEmission } from 'vitest-auto-spy';

const emitted = expectEmission(myService.getProducts$);

myService.getProducts$.nextWith(['x']);

expect(await emitted).toEqual(['x']);
```

---

Source: https://asdalexey.github.io/vitest-auto-spy/utilities/console

# Console spies

Console spying lives behind the `vitest-auto-spy/console` subpath. Importing the entry (in a test
file or your Vitest setup file) replaces `console.debug` / `error` / `info` / `log` / `time` /
`timeEnd` / `trace` / `warn` with **silent, fully-typed spies** and exports each one ready to
assert — no `vi.spyOn(console, 'info')` boilerplate in every suite, no log output polluting the
test run:

```ts
import { consoleInfoSpy, consoleWarnSpy } from 'vitest-auto-spy/console';

service.doWork();

expect(consoleInfoSpy).toHaveBeenCalledWith('done');
expect(consoleWarnSpy).not.toHaveBeenCalled();
```

## Exports

One spy per patched method: `consoleDebugSpy`, `consoleErrorSpy`, `consoleInfoSpy`,
`consoleLogSpy`, `consoleTimeSpy`, `consoleTimeEndSpy`, `consoleTraceSpy`, `consoleWarnSpy`
(type `ConsoleMethodSpy`).

## Housekeeping

```ts
import { installConsoleSpies, resetConsoleSpies, restoreConsole } from 'vitest-auto-spy/console';

resetConsoleSpies(); // clear the recorded calls (Vitest's `clearMocks: true` does this per test)
restoreConsole(); // put the original console methods back
installConsoleSpies(); // re-install after a restore (idempotent otherwise)
```

- `resetConsoleSpies()` clears recorded calls but keeps the spies installed. With
  `clearMocks: true` in your Vitest config this happens automatically before each test.
- `restoreConsole()` undoes the patching entirely and forgets the installed spies.
- `installConsoleSpies()` returns the full `ConsoleSpies` bag; calling it while spies are
  installed returns the same bag.

## Runtimes

The spies are built on the registered [`MockAdapter`](https://asdalexey.github.io/vitest-auto-spy/runtimes/vitest), not on `vi.spyOn`
directly — import your runtime entry (`vitest-auto-spy/bun`, `vitest-auto-spy/node`) **before**
`vitest-auto-spy/console` and the console spies are driven by that runner's mocks. With no prior
runtime entry, the default Vitest adapter is registered.

## Fully detached alternative

Prefer not to touch the real global? `createAutoMock<Console>()` gives you a typed, in-memory
console to inject into code that takes a logger:

```ts
import { createAutoMock } from 'vitest-auto-spy';

const fakeConsole = createAutoMock<Console>();
const service = new ReportService(fakeConsole);

service.doWork();

expect(fakeConsole.info).toHaveBeenCalledWith('done');
```

---

Source: https://asdalexey.github.io/vitest-auto-spy/utilities/setup

# Test-run hygiene

```ts
// vitest.setup.ts
import { setupAutoSpy } from 'vitest-auto-spy/setup';

setupAutoSpy();
```

One call for the pieces of hygiene every project otherwise assembles by hand, each of which is
cheap to install and expensive to diagnose when it is missing. The first three are on by default;
the rest are switches, because they change what the code under test sees.

## 1. Restoring patched properties

`vi.restoreAllMocks()` knows about spies, not about properties
[`mockReadonlyProp` / `mockValueProp`](https://asdalexey.github.io/vitest-auto-spy/adapters/angular#signal-readonly-property-mocking)
redefined. Under `isolate: false` an un-restored patch on a global, a prototype or a singleton
leaks straight into the next file. `setupAutoSpy()` registers `restoreMockedProps()` in a global
`afterEach`.

**And in an `onTestFinished` net behind it**, because the `afterEach` is not guaranteed to run.
Vitest calls `afterEach` hooks in **reverse** registration order, so the one a setup file registers
is the *last*, and any hook the spec file registered — which therefore runs first — takes the chain
down with it when it throws:

```ts
// in the spec file, and therefore running before the library's hook
afterEach(() => vi.restoreAllMocks()); // ← throws, and the cleanup below it never happens
```

That is not hypothetical. One spec kept exactly that line for years; migrating it to
`provideAutoSpy(LayoutStateService, { gettersToSpyOn: [...] })` made the restored getter return
`undefined`, `ngOnDestroy` called it as a signal, and the resulting `TypeError` aborted the hook.
The patch travelled, and the failure surfaced in a **different `describe`** as a template error
about a null profile. With the hand-rolled `vi.fn()` it replaced, the restored getter was still
callable, so the mine had been sitting there invisible the whole time.

`onTestFinished` runs after the `afterEach` chain and runs whatever that chain did, so the net puts
the properties back and warns — naming the count and the cause, at the test where it happened rather
than two tests later. It costs one boolean on the ordinary path: it does nothing unless the hook was
skipped.

`countMockedProps()` is exported for suites that would rather assert it:

```ts
afterEach(() => expect(countMockedProps()).toBe(0));
```

## 2. One copy of the library in the process

Two copies keep two sets of console spies and two registries, so an assertion runs against a spy
that never replaced the console the code under test called — and the symptom reads as "tests fail
depending on file order". The check fails the run with a report naming both copies and what to do
about each cause: a second install, or one install loaded in both its ESM and CommonJS form.

```ts
import { describeDuplicateCopies, getPackageCopies } from 'vitest-auto-spy/setup';

getPackageCopies(); // the registered copies, for your own reporting
describeDuplicateCopies(); // the human-readable report, or undefined when there is only one
```

Both are exported from the core entry as well.

## 3. Draining the runner's restore registry

Every `vi.spyOn` adds an entry that only `vi.restoreAllMocks()` removes; with a shared environment
that list grows for the whole run. `restoreMocks: true` drains it after each test.

## 4. Cancelling timers that outlive their file

Opt-in, and only relevant with `isolate: false` — where every spec file in a worker shares one set of
globals. A `setTimeout` a component schedules and never clears survives the file that created it: the
callback fires while a **different** file is mid-test, against mocks and a DOM that no longer match,
and the runner blames whichever file happened to be running.

`requestAnimationFrame` is the half that gets missed. Angular's zoneless change-detection scheduler
races a timeout against a frame callback, so a component torn down at the end of one file can still
have a frame queued — and what surfaces later is an Angular-internal complaint (a scheduler running
watches while scheduling, a signal read in the notification phase) attributed to innocent code.

```ts
setupAutoSpy({ strayTimers: true });
```

That wraps the four schedulers once per worker and sweeps whatever is outstanding in `afterAll`. The
pieces are exported for a suite that wants the sweep elsewhere — or wants a leak to **fail** rather
than be tidied away:

```ts
import { cancelStrayTimers, countStrayTimers, trackStrayTimers } from 'vitest-auto-spy/setup';

const stop = trackStrayTimers(); // idempotent; returns the undo, which also cancels
afterEach(() => expect(countStrayTimers()).toBe(0));
afterAll(() => {
  const cancelled = cancelStrayTimers(); // how many had to be cancelled

  if (cancelled > 0) {
    process.stdout.write(`${cancelled} timer(s) outlived this file\n`);
  }
});
```

Each takes an optional host, defaulting to the real globals, so a test can contain a stand-in object
instead. Under `isolate: true` this is close to a no-op — the environment is discarded per file
anyway.

## 5. Keeping the run off the network

Opt-in, and the reason it exists is a run that is green and still fails.

jsdom ships no `fetch`, so under it a component reaching for a remote asset is inert and the suite
never notices. happy-dom implements it, and the same component starts issuing real requests — an
icon loader pulling every SVG from a CDN, a config service polling an endpoint. The tests still
pass, because nothing they assert depends on the response. The run does not:

```text
 Test Files  260 passed (260)
      Tests  2257 passed (2257)

Vitest caught 8 unhandled errors during the test run.
DOMException [AbortError]: The operation was aborted.
```

The runner aborts whatever is in flight when it tears the environment down, and those aborts arrive
as unhandled rejections after the summary. Exit code 1, and no test named — because no test failed.

```ts
setupAutoSpy({ blockNetwork: true });
```

`fetch` then rejects immediately, naming what was requested — which is the thing a stack trace does
not tell you:

```text
[vitest-auto-spy] fetch is stubbed in unit tests — the code under test requested https://cdn.example.test/sprite.svg
```

Nothing leaves the machine, the run stops depending on a host being reachable, and the code under
test takes exactly the branch it would take for a failed request. A spec that genuinely wants
`fetch` replaces it as before — this is a floor, not a ceiling. The stub is installed per test
(`restoreProps` takes it off again), and `blockNetwork()` is exported for suites that want it
somewhere narrower.

`fetch` is only half of the network, and the other half is the one jsdom implements in full.
Plenty of libraries never left `XMLHttpRequest` — `rmp-vast` pings every VAST tracker through a
hand-rolled one — so a suite with `blockNetwork: true` already on was still reaching the internet,
one ping per quartile per ad per test, and printing jsdom's `AggregateError at
Object.dispatchError` for each connection that failed. Whether a green run prints that depends on
whether the machine has a route out, which is not a property a test suite should have.

Every channel the environment implements is closed by default. The object narrows it:

| option   | default    | what it does                                                              |
| -------- | ---------- | ------------------------------------------------------------------------- |
| `fetch`  | `true`     | `fetch` rejects, naming what was requested                                 |
| `xhr`    | `'reject'` | how a diverted `XMLHttpRequest` is answered — or `false` to leave it alone |
| `beacon` | `true`     | `navigator.sendBeacon` answers `false`, where the environment has one      |

`'reject'` fails the request the way an unreachable host does: `readyState` 4, `status` 0, an
`error` event, and the marker on `statusText` — the one string channel a failed request has.
`'empty'` answers it with status 200 and an empty body instead, which is what a request nobody
reads the response of wants:

```ts
setupAutoSpy({ blockNetwork: { xhr: 'empty' } }); // tracker pings, answered and silent
```

A `data:` URL is let through, and it is the only thing that is: it is the scheme a spec serves its
own fixtures from, and the only one a DOM answers without a socket. A **relative** URL is not
exempt — the DOM resolves it against the document origin, so a spec that reaches `/config` and
passes is resting on nothing listening on that port.

`WebSocket` and `EventSource` are deliberately left alone. Their failure is an event on an object
the code keeps and reconnects, so there is no answer a blanket stub could give that is not a
behaviour change of its own;
[`stubConstructor`](https://asdalexey.github.io/vitest-auto-spy/utilities/constructor-doubles) is the tool for a spec that has one.

## 6. Putting back timer globals the fakes took with them

On by default, because it can only ever repair.

`vi.useRealTimers()` reads like the inverse of `vi.useFakeTimers()`, and in a plain Node realm it
is. Under a DOM environment it is not: `@sinonjs/fake-timers` restores a global by assigning the
original back **when it was an own property of the global object**, and deletes it otherwise. In
happy-dom `Date` is inherited from the environment's realm, so uninstalling removes it outright.

With `isolate: true` nothing notices. With `isolate: false` the next file in the same worker meets
a realm with no `Date` and dies inside Vitest's own `useFakeTimers`, several files away from
whatever installed the fakes:

```text
TypeError: Cannot read properties of undefined (reading 'now')
 ❯ hijackMethod node_modules/@sinonjs/fake-timers/src/fake-timers-src.js
 ❯ Object.useFakeTimers node_modules/vitest/dist/chunks/vi.js
 ❯ src/app/billing/invoice.component.spec.ts:24:6
```

The file in that stack is simply the one that ran next.

The real globals are captured when the library is first imported — before any spec can install
fakes — and anything left `undefined` after a test is put back. Only that: a value a spec replaced
on purpose is still there and is left alone, so the repair cannot overwrite a deliberate stub.

```ts
import { getWatchedTimerGlobals, restoreTimerGlobals } from 'vitest-auto-spy/setup';

restoreTimerGlobals(); // safe at any point, and as often as you like
getWatchedTimerGlobals(); // the names captured in this environment
```

`setupFakeTimers()` runs the same repair in its own `afterEach`, so a suite using it is covered
whether or not `setupAutoSpy()` is installed.

## 7. Naming the file that sealed a global

Opt-in, and it answers a question that is otherwise answered by grepping the repository.

`Object.defineProperty(document, 'cookie', { value, writable: true })` is the Jest-era way to stub a
browser global, and `configurable` defaults to `false`. Under per-file isolation that is harmless —
the environment is discarded anyway. Under `isolate: false` the property can no longer be redefined
_or_ deleted, so every later file in that worker inherits it, and what fails is some library, every
other run, with nothing pointing back at the file that did it.

```ts
setupAutoSpy({ guardGlobals: 'throw' }); // or 'warn' while a large suite is being cleaned up
```

```text
[vitest-auto-spy] /src/app/diagnostics/app-info.spec.ts redefined document.cookie as a
non-configurable own property, so nothing can put it back — not `restoreMockedProps()`, not
`vi.unstubAllGlobals()`, not the next file's own `Object.defineProperty`. … use
`mockValueProp(document, 'cookie', value)`, which records the descriptor it replaced …
```

`globalThis`, `document` and `navigator` are compared before and after every test; only properties
that appeared _and_ cannot be removed are reported. `guardGlobalPatches(reaction)` is exported for a
suite that wants the check somewhere narrower.

## 8. Failing on a rejection zone.js swallowed

Opt-in, and the one switch on this page that changes whether a green run is telling the truth.

zone.js replaces the global `Promise`. A rejected `ZoneAwarePromise` nobody handled is drained in
`api.microtaskDrainDone()` and reported through `api.onUnhandledError` — which is a
`console.error` and nothing else. It never reaches `process.on('unhandledRejection')`, the channel
Vitest listens on, so the runner is never told: a file that rejected a hundred promises still exits 0.

What that hides is ordinary code:

```ts
it('renders once compiled', () => {
  TestBed.compileComponents().then(() => expect(component.ready).toBe(true)); // never runs
});
```

The test is over before the callback runs, so the assertion settles after the test it belongs to was
already reported green — and when it fails, the failure _is_ a rejection nothing handled. The same
goes for an `async` helper called without `await`, and for a `TypeError` thrown inside an
`import('…').then(…)` in production code. In one migrated Angular monorepo — 1688 spec files,
11 587 tests, green, exit 0 — six real defects were sitting behind exactly this, two of them
assertions that were simply false.

```ts
setupAutoSpy({ strayRejections: true });
```

The rejection then fails the test the runner was in when zone.js gave up on it:

```text
[vitest-auto-spy] 1 promise rejection(s) went unhandled and zone.js swallowed each one into console.error:
  - AssertionError: expected false to be true — attributed to TaskListComponent > renders once compiled
An assertion that settles after its test has finished cannot fail it: the test it belongs to was
reported green without ever running it. … return or await the promise so the assertion lands inside
the test.
```

"Attributed to" rather than "thrown by", because a rejection created by one file's test routinely
surfaces during a later one; and the closing advice changes with the kind — a failed matcher and a
thrown error are different bugs.

Two deliberate limits. zone.js has to be loaded already: this package never imports it — a zoneless
project must not pull it in — so `import 'zone.js';` at the top of the setup file, or the
`@angular/build:unit-test` builder's own entry point, is what puts it there, and without it the call
**throws** rather than quietly watching nothing. And no `process.on('unhandledRejection')` listener
is installed: Vitest's own handler bails out as soon as a second listener exists, so adding one would
_silence_ the native rejections the runner already reports and fails runs for. Native rejections are
not the gap; the zone-swallowed ones are.

The pieces are exported for a suite that wants the check somewhere narrower, or wants the captures
themselves:

```ts
import { countStrayRejections, flushStrayRejections, trackStrayRejections } from 'vitest-auto-spy/setup';

const stop = trackStrayRejections(); // idempotent; returns the undo, which restores the previous handler

afterEach(() => {
  const stray = flushStrayRejections(); // { reason, assertion, testName }[], and starts again from empty

  expect(stray).toEqual([]);
});
```

Each takes the same optional host as the stray-timer trackers, defaulting to the real globals.
`countStrayRejections()` throws when nothing is tracking the host — asking for a count that is
always `0` because nothing is watching is the failure mode worth being loud about — while
`flushStrayRejections()` returns an empty array instead, so a teardown left behind after the option
is turned off does not throw at the suite.

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: the runner names
the failure, and the same error arrives here as a rejection nobody handled. A red run therefore
used to print two messages per failure, and the first thing a reader does with the second one is go
looking for a defect that is not there. What survives the filter is what this check exists for —
the rejections that fail no test at all.

The [`no-floating-assertion`](https://asdalexey.github.io/vitest-auto-spy/utilities/eslint-plugin) rule catches the commonest shape statically,
before it ever runs.

## 9. Pruning the mock registry nothing empties

Opt-in, and the one switch on this page that is about what the run costs rather than what it reports.

`vi.fn()` and `vi.spyOn()` add the mock they create to a single module-level `Set` inside
`@vitest/spy`, because that is what `vi.clearAllMocks()` walks — and no API ever takes anything out
of it again. With `isolate: true` the module is re-evaluated per file and the set starts empty every
time. With `isolate: false` it is evaluated once per worker and only grows, and a large suite feels
both halves of that:

- `clearMocks: true` walks every mock of every file already run **before every single test**, so the
  cost of clearing grows with the number of tests already behind it.
- the worker's heap holds every mock of the run at once — with their recorded arguments, and through
  those whole component trees.

```ts
setupAutoSpy({ pruneMockRegistry: true }); // keep only the mocks that outlive a file
```

There is no API for that set, so it is taken from the one thing that iterates it: `Set.forEach`
passes the set to its callback as the third argument, so `vi.clearAllMocks()` under a briefly patched
`Set.prototype.forEach` hands the registry over. The capture is verified against a probe mock, and
without a match nothing is pruned — a slower run beats a broken one.

The half worth understanding before turning it on is what must **not** go. Dropping a mock from the
registry means `vi.clearAllMocks()` and `clearMocks: true` can no longer see it, so its calls
accumulate silently: harmless for a mock that dies with the file that made it, a bug for the
module-level `vi.fn()` in a shared `*.mock.ts` that six spec files import. The first file to import
it creates it, a naive prune drops it when that file ends, and the file that happens to run **second**
then fails on calls its predecessor made — which reads as flakiness, because which file runs first is
the runner's choice.

So the split is drawn where it is observable: whatever is already in the registry when a file's hooks
start was created while the module graph was being evaluated, which is exactly what "lives in a
module" means, and it is kept; everything added afterwards belongs to a test or a hook of that file
and goes when the file ends. One case lands on the wrong side of that line — a module first loaded by
a dynamic `import()` inside a test — and says so explicitly:

```ts
// fixtures/navigation.mock.ts — imported by six spec files
export const navigation = { setFocus: keepMockRegistered(vi.fn()) };
```

The pieces are exported for a suite that wants them without the rest: `trackMockRegistry()` installs
the same pair of hooks on its own, `keepRegisteredMocks()` marks everything currently registered as
long-lived, `pruneMockRegistry()` is the one-shot sweep and returns how many went, and
`getMockRegistrySize()` reports what is left — `undefined` when the capture never took.

## Reinstalling a stub for every test

```ts
import { installPerTest } from 'vitest-auto-spy/setup';

const observers = installPerTest(() => stubIntersectionObserver({ autoEmit: true }));

it('loads the section once it scrolls into view', () => {
  fixture.detectChanges();

  expect(observers().last.targets).toEqual([host]);
});
```

Every stub this library installs is taken off again by `restoreMockedProps()` after each test — that
is what keeps it out of the next file. The consequence is easy to miss: a stub installed once at
`describe` level, or in a `beforeAll`, is gone from the second test on, and what fails is an
assertion about the component ("expected 2 calls, got 0") with the stub sitting ten lines above it,
apparently in force.

The same ordering bites from the other direction. A project-wide setup file installs default
observers in a root `beforeEach`, and root hooks run **before** a file's own — so a `beforeAll` in a
spec loses to them silently, while a `beforeEach` in the same spec wins.

`installPerTest` hands back a **reader**, not the handle, because the handle is a different object
each test: a stub installed for the previous test is exactly what must not still be reachable.

## Options

| 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`   | Track and 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** — see below                   |
| `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 |

`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.

```ts
setupAutoSpy({ restoreMocks: true, duplicateCopies: 'warn' });
```

## Fake timers for the whole run

```ts
setupAutoSpy({ globalFakeTimers: true }); // or a `vi.useFakeTimers()` config object
```

Jest had `fakeTimers: { enableGlobally: true }`; Vitest has no such setting. A suite ported from a
project that used it was written against a frozen clock throughout, and turning that back on file by
file is a thousand edits.

Both ends are guarded, which is the half a hand-written pair of hooks gets wrong. A spec that drives
the clock itself would otherwise reach a second `vi.useRealTimers()`, and under happy-dom that one
leaves the environment without `clearInterval` — which explodes during teardown of whichever file
runs next, blaming it.

It also keeps the clock fake **between** tests, which is the half of `enableGlobally` a
`beforeEach`-only pair misses: a `beforeAll` inside a nested `describe` runs _after_ the previous
test's `afterEach`, so a block that prepares its samples there would otherwise meet real timers and
fail with `the timers APIs are not mocked` — in a set whose own tests never touch a timer. The fakes
come off for good in `afterAll`, so they never outlive the file. For one `describe` rather than the
whole run, that is [`setupFakeTimers(config, { betweenTests: true })`](https://asdalexey.github.io/vitest-auto-spy/utilities/fake-timers).

## Shared fixtures are functions, not constants

Under `isolate: false` a module is evaluated **once per worker**. An exported object holding
`vi.fn()`s is therefore one set of spies shared by every file that imports it, registered against
whichever file got there first, and the other files' `clearMocks` never reaches them. The symptom is
a 30-second timeout in a different file on each run.

```ts
// ❌ a constant: one set of spies for the whole worker
export const mockActionContext = { actions: { navigateToSection: vi.fn() } };

// ✅ a factory: one set per caller
export const createActionContext = () => ({ actions: { navigateToSection: vi.fn() } });
```

The same applies to a shared provider fixture — `{ provide: X, useValue: { load: vi.fn() } }` is a
constant unless it is returned from a function. And a spec file must **export nothing**: under
`isolate: false` an exported spec file gets imported by its neighbours and loses its own suite. Put
shared doubles in a `*.mock.ts` beside them.

The [`no-shared-module-level-mock`](https://asdalexey.github.io/vitest-auto-spy/utilities/eslint-plugin) rule finds these mechanically, which
is faster than the timeout that finds them otherwise.

## Hook order differs from Jest

Vitest runs `afterEach` hooks as a stack — innermost and last-registered first — where Jest ran them
in declaration order. In a ported suite where a spec's `afterEach` depends on something the setup
file installed, the setup file's teardown now runs first and the spec's hook operates on an
already-restored environment. `sequence: { hooks: 'list' }` in the Vitest config restores the Jest
ordering.

## The hooks belong to the file this call ran in

Everything `setupAutoSpy()` installs is a `beforeEach` / `afterEach` / `afterAll`, and a hook
registered while a setup file is imported belongs to the spec file whose collection imported it.
Vitest re-imports the setup files for every spec file, so normally none of that is visible.

It becomes visible when something keeps the setup module in the module cache across files: the call
runs once, and every file after the first in that worker has none of the hooks — no property
restore, no `blockNetwork`, no stray-timer cancellation, no `restoreTimerGlobals`, no global fake
timers. Nothing reports it, and the symptom lands somewhere else entirely — a leaked global, or
`A function to advance timers was called but the timers APIs are not mocked` in a spec that is green
when it runs on its own.

The case seen in the wild is `@angular/build:unit-test` **with coverage**. The builder then serves
each test file as a wrapper that imports the built bundle, the setup module stays resolved in the
shared environment, and its top level never runs again; without coverage the same run is fine, which
is what makes it read as "coverage broke the tests".

Two ways out: run coverage with per-file isolation (`ng test <project> --coverage --isolate`, or
`isolate: true` in the config for that case alone), or call `setupAutoSpy()` from something that is
evaluated per file rather than from a module the runner can cache.

---

Source: https://asdalexey.github.io/vitest-auto-spy/utilities/fake-timers

# Fake timers

```ts
import { advanceTimers, setupFakeTimers } from 'vitest-auto-spy/setup';

describe('SearchComponent', () => {
  setupFakeTimers();

  it('debounces the query', async () => {
    component.onInput('ab');
    await advanceTimers(300);
    expect(search.query).toHaveBeenCalledWith('ab');
  });
});
```

Two pieces of boilerplate every suite that tests a debounce, a poll or a retry ends up writing, and
the one bug that hides in them.

## `setupFakeTimers(config?)`

Installs the clock in a `beforeEach` and gives it back in an `afterEach`.

Written as two separate hooks, the second is the one a suite forgets — and a frozen clock left
behind leaks into every later file in the same worker, where it surfaces as an unrelated test
hanging on a `setTimeout` that never fires. Pairing them in one call is the whole point.

Both hooks are guarded. Installing or uninstalling twice does not round-trip: a suite that drives
the clock itself, or a nested `describe` that calls this helper again, otherwise reaches a second
`vi.useRealTimers()` — and that one leaves the environment without `clearInterval`, which explodes
during teardown of whichever file happens to run next.

The `afterEach` also puts back any timer global that uninstalling removed rather than restored.
Under happy-dom `Date` is inherited from the environment's realm, so `vi.useRealTimers()` deletes
it instead of reassigning; with `isolate: false` the next file then dies inside Vitest's own
`useFakeTimers`. See [test-run hygiene](https://asdalexey.github.io/vitest-auto-spy/utilities/setup#_6-putting-back-timer-globals-the-fakes-took-with-them)
for the whole story, including the standalone `restoreTimerGlobals()`.

The optional `config` is forwarded verbatim to `vi.useFakeTimers()`, typed off Vitest's own
signature so it tracks whatever the installed version accepts:

```ts
setupFakeTimers({ toFake: ['setTimeout'] }); // leave Date and queueMicrotask real
```

## Between the tests as well — `betweenTests`

```ts
setupFakeTimers(undefined, { betweenTests: true });
```

Off by default, because a scoped call belongs to its `describe` and has to leave the clock as it
found it. Turned on, the clock stays fake in the gaps *between* tests too — which is what Jest's
`fakeTimers.enableGlobally` did, and what a suite ported from it was written against.

Arming in `beforeEach` alone does not reproduce that, and the gap is not hypothetical: a `beforeAll`
inside a **nested** `describe` runs *after* the previous test's `afterEach`, so it meets whatever
that hook left behind. A block that prepares its samples there — driving an animation clock with
`vi.advanceTimersByTimeAsync`, say — fails with `A function to advance timers was called but the
timers APIs are not mocked`, in a set whose own tests never touch a timer.

So the fakes are re-armed in `afterEach` right after they come off, and taken off for good in
`afterAll` — the boundary that matters under `isolate: false`, where a clock outliving its file
would meet the next one's imports. Every test still starts fresh: the uninstall discards whatever
the previous one scheduled.

For a whole run, [`setupAutoSpy({ globalFakeTimers: true })`](https://asdalexey.github.io/vitest-auto-spy/utilities/setup#fake-timers-for-the-whole-run)
turns this on from the setup file — that option exists for exactly this case and passes
`betweenTests` itself.

## `advanceTimers(ms?)`

`vi.advanceTimersByTime()` plus the step that is easy to miss.

Advancing runs the timer callbacks synchronously — but whatever they *queue* is still sitting in
the microtask queue when the next line executes: a resolved promise, an `await` continuation, an
RxJS `delay()` handing control back. The assertion then reads state from before the callback
finished, and the test fails in a way that reads like a race in the code under test.

```ts
// Fails like a race in the code under test:
vi.advanceTimersByTime(300);
expect(search.query).toHaveBeenCalled();

// Awaits the queue the callback filled:
await advanceTimers(300);
expect(search.query).toHaveBeenCalled();
```

That is why it is `async` — the return value must be awaited.

`ms` defaults to `0`: the "run everything already due, then flush microtasks" step, which is what a
`setTimeout(fn, 0)` or a resolved-promise chain needs.

On real timers it throws a message naming the fix, rather than letting Vitest fail deeper in with
"timers are not mocked".

**Angular**
Pair it with [`stable(fixture)`](https://asdalexey.github.io/vitest-auto-spy/adapters/angular#zoneless-waiting): `advanceTimers` moves the
clock, `stable` flushes the effects and change detection the clock set off.

---

Source: https://asdalexey.github.io/vitest-auto-spy/utilities/observer-stubs

# Observer stubs

```ts
import { intersectionEntry, stubIntersectionObserver } from 'vitest-auto-spy';

it('reveals the card once it scrolls into view', async () => {
  const observers = stubIntersectionObserver();
  const fixture = TestBed.createComponent(RevealHost);

  fixture.detectChanges(); // the directive constructs its observer

  observers.last.emit([intersectionEntry(fixture.nativeElement, true)]);
  await fixture.whenStable();

  expect(fixture.nativeElement.classList).toContain('is-visible');
});
```

`IntersectionObserver`, `ResizeObserver` and `MutationObserver` share a shape that makes them
awkward to test. The code under test constructs the observer itself, keeps the instance private,
and the only thing a spec can reach is the global constructor. So the spec has to intercept the
construction, remember the callback, and invoke it with entries it builds by hand — forty lines
that say nothing about the component, and that every project writes again.

Two details make the hand-rolled version go wrong rather than merely be tedious.

## The stub nobody takes off

A spec that assigns `globalThis.IntersectionObserver` directly leaves it there. With
`isolate: false` the next file in the worker inherits it and fails on something unrelated —
`.observe is not a function`, or an assertion that never fires — pointing at innocent code.

Installation here goes through `mockValueProp`, so `restoreMockedProps()` — which
[`setupAutoSpy()`](https://asdalexey.github.io/vitest-auto-spy/utilities/setup) already runs after every test — puts the real constructor back with no
teardown of your own.

## The instance reached through a static field

`MockObserver.last` is the usual trick, and it is shared mutable state that survives the file just
like the stub does: the observer one spec constructed is still there for the next one to find.

Here the handle returned by the installer owns the instances, so nothing outlives the spec that
made it. Reaching for `last` when the code under test constructed nothing throws and says so,
rather than failing three lines later against `undefined`:

```text
[vitest-auto-spy] stubObserver('IntersectionObserver'): the code under test has not constructed an
IntersectionObserver. Render the component (or run the effect) before reaching for `last`, and
check that the stub was installed before the construction rather than after it.
```

## The handle

```ts
const observers = stubResizeObserver();

observers.instances; // every observer constructed since the stub went in, in order
observers.last; // the newest — the usual case, where a component builds exactly one
```

Each instance exposes what a spec asserts on and what it drives:

| Member          | What it is                                                             |
| --------------- | ---------------------------------------------------------------------- |
| `targets`       | everything passed to `observe`, with `unobserve`/`disconnect` applied  |
| `observe`       | the spy — for asserting _that_ something was observed, and with what   |
| `unobserve`     | the spy                                                                |
| `disconnect`    | the spy                                                                |
| `disconnected`  | whether teardown ran — the readable form of asserting on `disconnect`  |
| `emit(entries)` | invoke the callback with one batch, exactly as the browser delivers it |

`emit` takes an array rather than a single entry on purpose. A fast scroll or a resize storm
delivers several at once, and code that assumes one entry per call is a real bug this makes
reachable:

```ts
observers.last.emit([intersectionEntry(first, false), intersectionEntry(second, true)]);
```

## Building entries

`intersectionEntry(target, isIntersecting, overrides?)` fills in the fields nothing reads.
`intersectionRatio` is derived rather than accepted, because the two disagreeing is not a state the
browser produces — a spec that sets them apart is testing something that cannot happen.

```ts
intersectionEntry(element, true);
intersectionEntry(element, true, { boundingClientRect: new DOMRect(0, 0, 200, 100) });
```

The rect fields are left out unless asked for. Fabricating four `DOMRectReadOnly`s for an assertion
that looks at `isIntersecting` would be ceremony, not fidelity — and `overrides` supplies whatever
a particular component does read.

For `ResizeObserver` and `MutationObserver` the entries stay yours, since what a component reads
from them varies too much to guess:

```ts
observers.last.emit([{ contentRect: { width: 320 } } as ResizeObserverEntry]);
```

## The installers

| Function                     | Global replaced           |
| ---------------------------- | ------------------------- |
| `stubIntersectionObserver()` | `IntersectionObserver`    |
| `stubResizeObserver()`       | `ResizeObserver`          |
| `stubMutationObserver()`     | `MutationObserver`        |
| `stubObserver(name)`         | any of the three, by name |

All four are exported from the core entry — nothing here is Angular-specific, and the spies come
from whichever [runtime adapter](https://asdalexey.github.io/vitest-auto-spy/runtimes/vitest) is registered, so they work on Bun and
`node:test` too.

**Zoneless Angular**
`emit` runs the component's callback synchronously; the change detection it schedules does not.
Follow it with `await fixture.whenStable()` or [`stable(fixture)`](https://asdalexey.github.io/vitest-auto-spy/adapters/angular#zoneless-waiting).

## Install it in `beforeEach`, never in `beforeAll`

A shared setup file's root `beforeEach` runs **after** a file's `beforeAll`. So a stub installed in
`beforeAll` is overwritten by the setup file's default observer before the first test even starts,
and the symptom is `expected "vi.fn()" to be called 2 times, but got 0 times` in a file where the
mock class sits ten lines above the assertion.

The rule that pairs with "do not assign `globalThis.IntersectionObserver` by hand" is therefore: and
do not install it in `beforeAll` either.

## `autoEmit` — everything is visible, immediately

```ts
stubIntersectionObserver({ autoEmit: true });
```

The default stub is inert, which is right when the spec wants to choose the moment of intersection.
It is wrong for a suite carried over from Jest, where the global mock fired its callback with
`isIntersecting: true` synchronously from `observe()`, so lazily-loading sections and cards fetched
their data during `detectChanges()`. Against an inert observer those specs quietly assert on a
component that never loaded anything, and fail with something unrelated to intersection — one option
here instead of rewriting every spec.

`stubObserver` takes the general form, where the entry is yours to build:

```ts
stubObserver<ResizeObserverEntry, Element>('ResizeObserver', {
  autoEmit: (target) => resizeEntry(target, { width: 320 }),
});
```

## `options` — what the constructor was given

```ts
new IntersectionObserver(callback, { rootMargin: '-20% 0px -70% 0px' });

expect(observers.last.options).toEqual({ rootMargin: '-20% 0px -70% 0px' });
```

A component that builds one observer per configuration is asserting a contract — "one observer per
unique root margin" — and without this the only thing a spec can count is the number of
constructions, which is a weaker statement about a different thing.

## Building entries

```ts
import { intersectionEntry, mutationRecord, resizeEntry } from 'vitest-auto-spy';

observers.last.emit([intersectionEntry(element, true)]);
observers.last.emit([mutationRecord(host, { addedNodes: [span] })]);
observers.last.emit([resizeEntry(host, { width: 320, height: 200 })]);
```

`IntersectionObserverEntry` has seven required fields of which production code usually reads one, and
the types cannot be narrowed away — parameter contravariance blocks it, so the alternative is a
double type assertion in every spec.

`MutationRecord` is worse: it cannot be written as an object literal at all, because `addedNodes` and
`removedNodes` are `NodeList`s. The obvious construction — append the nodes to a `DocumentFragment`
and take its `childNodes` — is the one to avoid, because appending **moves** a node: a spec that
passes an element it had just rendered silently tears that element out of the fixture, and the
assertion that follows fails on a DOM the test itself broke. `mutationRecord()` builds a list that
supports indexing, `item()`, `forEach`, `for…of`, `entries`/`keys`/`values` — and moves nothing.

---

Source: https://asdalexey.github.io/vitest-auto-spy/utilities/constructor-doubles

# Constructor doubles

```ts
import { stubConstructor } from 'vitest-auto-spy';

it('fires the tracking pixel', () => {
  const Image = stubConstructor(globalThis, 'Image', () => ({ src: '' }));

  tracker.ping();

  expect(Image).toHaveBeenCalledTimes(1);
  expect(Image.instances[0].src).toBe('https://tns.example/hit');
});
```

## The mistake this replaces

`jest.fn().mockImplementation(() => instance)` served `new` under Jest, so every suite old enough to
have mocked a global constructor carries that shape: `new Image()` for a tracking pixel, `new
Worker()`, `new WebSocket()`, `new Audio()`, a payment widget or a player SDK published as a global
class.

Vitest only forwards `new` to an implementation that is **itself constructible**, and an arrow
function is not. The call is recorded, the body never runs, and `new` hands back an empty object.
Vitest prints a warning on stderr — "the mock did not use 'function' or 'class' in its
implementation" — but it is not adjacent to the failure, and in a monorepo run it is one line among
thousands.

What arrives instead is one of two things, and neither points at the spec:

- `TypeError: (cb) => {…} is not a constructor`, with a stack **in production code** and the source
  of the arrow printed in the message but nothing saying that the arrow is the problem;
- a green test for the wrong reason: the empty object has no methods, the call throws inside a
  `try`, the `catch` logs, and `expect(logger.err).toHaveBeenCalledWith(expect.any(Error))` is
  satisfied.

## `mockConstructor(factory, name?)`

Returns a runner mock that is also a constructor. Everything a mock can do still applies —
`toHaveBeenCalledWith`, `mockClear`, `mock.calls` — and `new` reaches the factory.

```ts
import { mockConstructor } from 'vitest-auto-spy';

const LicenseClient = mockConstructor<LicenseClient>(() => ({ prepareRequest: vi.fn() }));

mockValueProp(shaka.net, 'LicenseClient', LicenseClient);
player.load(url);

expect(LicenseClient).toHaveBeenCalledWith('widevine');
expect(LicenseClient.instances[0].prepareRequest).toHaveBeenCalled();
```

- **`instances`** collects what the factory produced, in construction order. It is owned by the
  helper rather than read off the runner, so `mockClear()` does not empty it — clearing the call
  record and forgetting objects a spec still asserts against are different wishes, and the runner's
  own `mock.instances` covers the first one.
- **Called without `new`, it throws by name.** Today the only way to learn that a double was used
  wrongly is a `TypeError` several frames into somebody else's code.
- **The factory must return an object.** JavaScript discards a primitive returned from `new`, so a
  factory that returns one would hand the code under test something the spec never configured; that
  is reported immediately instead.

## `stubConstructor(target, property, factory)`

The same double, installed on a global (or on any object) and taken off again for you.

```ts
const Widget = stubConstructor(window, 'MTSPay', (params: PayParams) => ({ render: vi.fn() }));
```

Installation goes through [`mockValueProp`](https://asdalexey.github.io/vitest-auto-spy/utilities/setup), so `restoreMockedProps()` — which
`setupAutoSpy()` already runs after every test — puts the real constructor back. That is the
difference from a hand-written `vi.stubGlobal`: with `isolate: false` a stub that is never removed
is inherited by the next file in the worker and fails there.

This is the generalisation of the [observer stubs](https://asdalexey.github.io/vitest-auto-spy/utilities/observer-stubs) to everything else the
platform publishes as a class and production code constructs directly.

## Which of the three

| You have                             | Use                                              |
| ------------------------------------ | ------------------------------------------------ |
| a real class at runtime              | `createSpyClass(Foo)` — instances are auto-spies |
| only a type, or a hand-built shape   | `mockConstructor<T>(() => shape)`                |
| the constructor lives on a global    | `stubConstructor(globalThis, 'Image', factory)`  |
| it is one of the three DOM observers | `stubIntersectionObserver()` and friends         |
| it is `AbortController`              | `stubAbortController()`                          |

## `stubAbortController()`

`element.addEventListener('pointerdown', handler, { signal })` is the recommended way to detach
listeners since Angular 16, and it fails in a jsdom run with a message that names none of the three
parties responsible:

```
TypeError: 'addEventListener' called on an object that is not a valid instance of EventTarget
```

Vitest lays Node's fetch family over the jsdom globals, so a signal is a _Node_ `EventTarget`;
zone.js registers the abort listener through jsdom's own `addEventListener` with that signal as the
receiver; jsdom brand-checks the receiver and refuses. jsdom raises it, Node caused it, zone.js
triggered it, and the component under test is blamed.

```ts
import { stubAbortController } from 'vitest-auto-spy';

beforeEach(() => {
  stubAbortController();
});
```

The replacement extends whichever `EventTarget` belongs to the current realm, which is the one thing
all three parties agree on. It is registered as a property patch, so it comes off with everything
else.

---

Source: https://asdalexey.github.io/vitest-auto-spy/utilities/media-element

# Media element stub

```ts
import { stubMediaElement } from 'vitest-auto-spy';

const media = stubMediaElement({ duration: 120 });
```

jsdom implements the media elements as a shell, and every player, advertising or subtitle suite hits
the same list:

| What the code under test does    | What jsdom does                                     |
| -------------------------------- | --------------------------------------------------- |
| `await video.play()`             | throws `Not implemented: HTMLMediaElement.play()`   |
| `video.duration`                 | `NaN`, and it is an accessor — assigning it throws  |
| `video.canPlayType('video/mp4')` | `''` for every type, so feature detection says no   |
| `video.readyState`               | `0`, forever                                        |
| `video.error`                    | not on the prototype at all                         |
| `video.load()`                   | nothing                                             |

So the spec writes forty lines of `Object.defineProperty` against `HTMLMediaElement.prototype` —
which leaks into the next file, because nothing takes it off again.

## Driving one

```ts
const fixture = TestBed.createComponent(PlayerComponent);
fixture.detectChanges();

const video = fixture.nativeElement.querySelector('video');

media.set(video, { readyState: 1 }); // fires `loadedmetadata`
media.set(video, { currentTime: 119 }); // fires `timeupdate`
media.set(video, { ended: true }); // fires `ended`

expect(media.play).toHaveBeenCalledTimes(1);
expect(component.finished()).toBe(true);
```

`set` is the part a hand-written patch usually gets wrong. Production code listens for
`durationchange` / `timeupdate` / `ended`; assigning the field alone leaves those handlers unrun, so
the component stays on its initial state while the assertion reads the element and sees the new
value — a disagreement that looks like a bug in the component.

| Field passed to `set`  | Event dispatched |
| ---------------------- | ---------------- |
| `duration`             | `durationchange` |
| `readyState` ≥ 1       | `loadedmetadata` |
| `currentTime`          | `timeupdate`     |
| `ended: true`          | `ended`          |
| a non-null `error`     | `error`          |

`ended: false` and `error: null` announce nothing: those clear a state, and the platform has no
event for that.

## State is per element

```ts
media.set(advert, { duration: 15 });

expect(advert.duration).toBe(15);
expect(content.duration).toBe(120); // the option's default
```

A patch that closes over one `duration` variable reports the same duration for the ad and for the
content — precisely the pair a player spec exists to tell apart. Every element gets its own record,
weakly keyed, and `media.state(element)` reads it back.

## `play`, `pause`, `load`, `canPlayType`

They are runner mocks shared by every media element, so every matcher applies:

```ts
expect(media.pause).toHaveBeenCalledTimes(1);
```

`play()` resolves a promise rather than returning `undefined` — production code routinely calls
`.catch()` on the result to swallow an autoplay rejection, and jsdom's `undefined` makes that line
throw. It also fires `play` and `playing`, since a component may wait for either.

`canPlayType` answers `'probably'` by default, and takes an implementation when one codec has to be
unsupported:

```ts
stubMediaElement({ canPlayType: (type) => (type.includes('vp9') ? '' : 'probably') });
```

## Installation and undo

The patch goes on `HTMLMediaElement.prototype`, so it also covers an element production code creates
itself with `document.createElement('video')` — the case a per-instance stub cannot reach. It is
installed through `mockValueProp` / `mockReadonlyPropGetter`, so `restoreMockedProps()` — which
[`setupAutoSpy()`](https://asdalexey.github.io/vitest-auto-spy/utilities/setup) runs after every test — puts the real prototype back.

Install it in a `beforeEach`, or through
[`installPerTest`](https://asdalexey.github.io/vitest-auto-spy/utilities/setup#reinstalling-a-stub-for-every-test): a stub installed once at
`describe` level is restored away after the first test.

---

Source: https://asdalexey.github.io/vitest-auto-spy/utilities/module-mocks

# Module mocks that did nothing

```ts
import { assertMocked, moduleNamespace } from 'vitest-auto-spy';
```

`vi.mock()` is the one piece of a ported suite that can fail **silently**. It is a transform over
the module graph, so it has nothing to say when the graph is not what the spec assumed — and what
follows is either a test passing for the wrong reason or a failure with no connection to mocking.

## `assertMocked(namespace, options?)`

```ts
import * as engine from '@app/pricing-engine';

vi.mock('@app/pricing-engine');

beforeEach(() => {
  assertMocked(engine, { specifier: '@app/pricing-engine', exports: ['createEngine'] });
});
```

Fails at the line that assumed the mock, naming the module. Without `exports` it checks that *some*
export is a runner mock; with it, that each named one is — which is what a factory that stubs part
of a module and re-exports the rest needs, since a factory that lost the one export the test drives
still looks mocked from the outside.

### The two ways `vi.mock` becomes a no-op

**A bundler already inlined the module.** Under `@angular/build:unit-test`, or `vite-node` handed a
pre-built entry, a workspace alias (`@scope/lib`) or a barrel is part of the bundle by the time the
mock would be installed. There is nothing left to intercept. No warning is printed.

**`isolate: false` and a module already in the worker graph.** A built-in such as `node:fs` keeps
whichever mock reached it first, so the same spec passes or fails depending on the order the worker
picked up the files. A run that is green locally and red in CI, at a different file each time, is
this.

Neither has a fix inside `vi.mock`. What works is not mocking the module at all: pass the dependency
in — a TestBed provider, a constructor argument, a function parameter — and stub the value.
`assertMocked` is what turns the silent case into a sentence, so that conclusion is reached in one
run rather than three.

## `moduleNamespace(exports, options?)`

```ts
vi.mock('shaka-player', () => moduleNamespace({ Player: mockConstructor(() => playerStub) }));
```

Returns `{ ...exports, default: exports, __esModule: true }` — the shape any dependency written to
run as both CommonJS and ESM probes for with `mod.default ?? mod`.

The missing `default` is the failure this removes. A factory returning bare named exports makes
Vitest throw `No "default" export is defined on the mock` **from inside that dependency**, with a
stack that names the library rather than the factory three lines up in the spec.

### `lenient`

```ts
vi.mock('shaka-player', () => moduleNamespace({ Player }, { lenient: true }));
```

Reads an export the factory did not define as `undefined` instead of throwing.

The strict default is the better one: it catches a factory that has drifted from the module it
stands in for. But Jest did not throw, so a suite ported from it can be reaching for exports it
never stubbed — and there the guard fails inside production code, several frames from the assertion
that would have said what the test actually wanted. Turn leniency on to port first and tighten
later.

`then` and symbol keys are never claimed, whatever the mode: a namespace that answers to `then`
would be treated as a promise by `await import(…)` and never resolve.

## What this does not do

A helper cannot make `vi.mock` hoist from inside another function, so there is no
`mockModule('x', factory)` here — Vitest hoists the literal `vi.mock` call, and a wrapper around it
would be hoisted as a call to a function that does not exist yet. When the factory and the tests
need to share a fixture, `vi.hoisted` is the mechanism:

```ts
const stripe = vi.hoisted(() => {
  const charge = vi.fn();

  return { charge, createClient: vi.fn(() => ({ charge })) };
});

vi.mock('stripe', () => moduleNamespace(stripe));
```

---

Source: https://asdalexey.github.io/vitest-auto-spy/utilities/fixtures

# Fixtures without casts

Three helpers for the data a spec builds rather than the collaborators it drives. What they have in
common: each one replaces a type assertion that silently stops checking, with something that keeps
checking.

## `createMock<T>(partial?)` — now partial all the way down

```ts
const config = createMock<FeatureFlagService>({ featureFlags: { retry_count: '3' } });
const token = createMock<AccountToken>({ profiles: { active: { id: '1' } } });
```

`Partial<T>` is one level deep, so a fixture for a configuration object, an account token or a route
snapshot — a tree the test reads one leaf of — used to need the type of every nested level named and
built with its own call. The input is now a deep partial, and the part that matters survives: a key
`T` does not have, **at any depth**, is still rejected.

```ts
// @ts-expect-error — `nickname` is not on the active profile
createMock<AccountToken>({ profiles: { active: { nickname: 'ada' } } });
```

That rejection is the whole value. After a model changes, a renamed or removed field is exactly what
a spec fixture is least likely to notice and most likely to be lying about — and `as T` throws the
check away, which is why "the fixture compiles" stops meaning anything.

**Looking for `createFixture`?**
This is it. `createMock<T>` builds the data; `createAutoMock<T>` builds the collaborator whose calls
you assert. Both take a deep partial now.

Built-ins are handed through untouched — a `Date`, a `Map`, a `Promise`, a function stays itself
rather than becoming an object of optional methods.

## `narrow(value, predicate)` — the branch a test knows it got

```ts
import { narrow } from 'vitest-auto-spy';

const open = narrow(result.link, (link): link is OpenLink => 'params' in link);
const params = narrow.byKey(result.link, 'params').params;
const canMatch$ = narrow.observable(guard.canMatch(route, segments));
```

A spec routinely knows something the type does not: that `result.link` is the one form of twenty that
carries `params`, that a guard returned the `Observable` and not the `boolean`. The two usual ways to
say it are both bad — an assertion is a lie the compiler stops checking, and a hand-written
`if ('params' in link) … else throw` is six lines per site whose message is whatever the author felt
like typing.

The failure prints the shape the value actually had, which is the only thing that makes it cheaper
than the assertion it replaces:

```text
[vitest-auto-spy] narrow: expected an object with a 'params' property, but the value is Object { type, slug }.
```

`narrow.observable` exists here rather than as a call to rxjs's `isObservable` because that one
narrows to `Observable<unknown>` and drops the element type, so every call site adds a type argument
back by hand. The check is structural, so nothing in the core imports rxjs.

## `withOverrides(model, overrides?)` — a model whose getters survive

```ts
const expired = withOverrides(SUBSCRIPTION, { isExpired: true });
```

Angular codebases model API responses as classes with getters — `get isSubscribed()`,
`get isExpired()` — computed from the raw fields. "The same subscription, but expired" then has two
usual spellings, and both are broken in ways that are hard to see:

- `{ ...subscription, isExpired: true }` **drops every getter**: spread copies own enumerable
  properties, and a prototype accessor is neither. The component reads `undefined` from a flag that
  should have had a value.
- `Object.assign(new SubscriptionModel(), fields)` keeps the getters **live**, so each runs against a
  half-filled instance — and a getter written for real data throws from inside the model, with a
  stack that names neither the spec nor the missing field.

`withOverrides` reads every accessor once, while the model is still whole, and hands back a plain
object carrying the results as data. A getter that throws contributes `undefined` rather than failing
the snapshot: a spec that asserts on that field will say so far more clearly than a stack inside the
model would.

---

Source: https://asdalexey.github.io/vitest-auto-spy/utilities/zone

# `fakeAsync` on Vitest

```ts
// vitest.setup.ts
import 'zone.js';
import 'zone.js/testing';
import 'vitest-auto-spy/zone';
```

`zone.js/testing` patches three runners: jasmine, mocha and jest. Vitest is not one of them, so in an
Angular project on Vitest **every** `fakeAsync` fails:

```text
Error: Expected to be running in 'ProxyZone', but it was not found.
```

A message about a zone, in a test that never mentions one. Exactly one package does something about
it today — `@analogjs/vitest-angular`, as a side effect of importing `…/setup-zone` — which means a
project moving to the native `@angular/build:unit-test` builder loses the patch along with Analog:
the builder loads `zone.js/testing`, but installs no wrapper for Vitest.

## What it does

`fakeAsync` needs one thing: the callback it wraps must run inside a zone that carries a
`ProxyZoneSpec`, because that is the spec it swaps its own `FakeAsyncTestZoneSpec` into. So the patch
runs every test and hook body inside a forked proxy zone.

The difficulty is doing that without disturbing the runner, and the three ways a hand-written version
gets it wrong are all failures in *other people's files*:

| Detail                                            | What goes wrong without it                                                                                                                       |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| the wrapper declares **no** parameters            | Vitest reads `fn.toString()` to find fixtures; `function (...args)` fails every file with `FixtureParseError: … must use object destructuring`    |
| `fn.length` and `fn.toString()` are carried over  | the runner reads both to decide how to call the callback — a wrapper of arity 0 silently changes that decision, and hides the fixtures            |
| `it` is **proxied**, not replaced                 | `each` is a method that reads `this`; called detached it returns `undefined` and the line after it explodes. `it.skip` / `test.each` come free    |

## One zone for the run, or one per callback

```ts
import { installProxyZonePatch } from 'vitest-auto-spy/zone';

installProxyZonePatch({ scope: 'callback' });
```

`scope: 'shared'` is the default: every test and hook body of the run goes through **one** proxy
zone. That is what Angular's own jasmine patch does, and what the ecosystem is written against — a
component built in `beforeEach` schedules from its constructor, and the `tick()` inside the
`fakeAsync` test has to see those timers. Fork per callback instead and the two end up in different
zones, so the test waits on a timer nothing will ever flush.

`scope: 'callback'` is that fork-per-callback shape. It is the correct one in the abstract, and the
required one for `test.concurrent`: two callbacks are then in flight at once and would otherwise
swap the same `ProxyZoneSpec` delegate under one another.

## Requirements

**`test: { globals: true }`.** The patch works by replacing the runner globals; an `it` imported from
`'vitest'` is a module binding that nothing — no patch, in any package — can reach.

**zone.js loaded first, by you.** This entry imports none of it. Under `@angular/build:unit-test` the
builder already loads both bundles from its own entry point; otherwise import them at the top of the
setup file. If they are missing, the patch says which half:

```text
[vitest-auto-spy] vitest-auto-spy/zone: globalThis.Zone is not there, so there is nothing to patch.
This entry deliberately does not import zone.js — a zoneless project must not pull it in — …
```

## Why it is a separate entry

**zone.js is a `devDependency` of this package and nothing else** — not a dependency, not an optional
peer. `vitest-auto-spy` declares no runtime dependencies at all, so installing it cannot pull zone.js
into anybody's tree.

And no other entry of the library reaches this module, even transitively: `dist/zone.js` is
self-contained and nothing else in `dist/` references it. A zoneless project that imports
`vitest-auto-spy` gets no zone code, no zone import, and no bytes of this file. That is an invariant
of the package, not an accident of this release — see `AGENTS.md`.

`installProxyZonePatch()` is exported for a setup file that would rather call it explicitly; it
returns the undo.

---

Source: https://asdalexey.github.io/vitest-auto-spy/utilities/event-loop

# Waiting and the clock

```ts
import { flushEventLoop, settleDynamicImport } from 'vitest-auto-spy';

fixture.debugElement.query(By.css('.open')).nativeElement.click(); // production: await import(…)
await settleDynamicImport(() => import('./profile-select.modal'));

expect(dialog.open).toHaveBeenCalled();
```

## Four queues

Under Jest these were hard to tell apart, because `import()` was compiled to `require()` and fake
timers were usually global. Under Vitest with a real bundler they are four separate mechanisms, and
a test that waits on the wrong one fails with a message that names none of them.

| What is pending                               | What drives it                                     | What does **not**                         |
| --------------------------------------------- | -------------------------------------------------- | ----------------------------------------- |
| change detection                              | `fixture.detectChanges()`                          | anything `await`ed                        |
| effects, `afterNextRender`, then CD           | `await stable(fixture)`                            | `detectChanges()` alone                   |
| timers, debounces, polling                    | `await advanceTimers(ms)`                          | `await Promise.resolve()`                 |
| a dynamic `import()`, native `async` in a dep | `await flushEventLoop()` / `settleDynamicImport()` | `tick()`, `flushMicrotasks()`, microtasks |

## `flushEventLoop(turns?)`

Gives the runtime real event-loop turns, whatever the timers are doing, without touching the clock.

A suite carried over from Jest usually runs with fake timers on for every test, and that leaves no
obvious way to say "let the runtime breathe once":

- `await Promise.resolve()`, any number of times, only drains microtasks. It never advances a
  dynamic `import()`, and it never advances a native `async` function inside `node_modules` —
  both continue on a task, not a microtask.
- `setTimeout` is the fake one, so scheduling through it schedules nothing.
- `await vi.advanceTimersByTimeAsync(0)` does work, but it reads as "move the timers" in a test that
  has no timers, so the next reader deletes it as noise. That is not hypothetical: it is what
  happened to the hand-rolled version of this helper in the suite that motivated it.

Internally it schedules a `MessageChannel` task, which no fake-timer implementation replaces. It
yields a _task_ turn, and deliberately does not run pending `setTimeout` callbacks — those are a
different task source, and a helper that fired them too would be `advanceTimersByTime` under another
name.

It is not the answer for `httpResource()` / `resource()` / `rxResource`, which need a
change-detection **tick** rather than an event-loop turn —
[`settleResource()`](https://asdalexey.github.io/vitest-auto-spy/adapters/angular#resources-httpresource-and-resource) is that wait. What this
helper is right for is the case one step below: work whose delivery crosses the boundary between
zone-patched promises and native ones, where a fixed number of `await Promise.resolve()` calls is a
guess that happens to hold until it does not.

## `flushEventLoopUntil(isDone, options?)`

```ts
client.warmUp();

await flushEventLoopUntil(() => client.isReady(), { label: 'the SDK handshake' });

expect(client.session()).toBeDefined();
```

Takes real turns until the condition holds, then stops — the shape behind every hand-rolled
"settle" helper: a lazily-loaded chunk becoming reachable, an SDK reporting itself ready, a queue
draining.

**Not for an Angular resource**
This page used to show `httpResource()` here, and that example never worked. `flushEventLoopUntil`
takes event-loop turns and never **ticks**, and an `httpResource` issues no request at all until
something does — measured, a resource awaited this way finishes the whole budget having made zero
requests, then fails saying the condition was never met.
[`settleResource()`](https://asdalexey.github.io/vitest-auto-spy/adapters/angular#resources-httpresource-and-resource) from
`vitest-auto-spy/angular` is that wait.

Written by hand that is a fixed number of turns, tuned by trial until the suite goes green, which is
both slower than it needs to be (it always waits the maximum) and quietly fragile — one more
hand-off inside a dependency and the number is wrong again.

The turn budget (20 by default) is what separates this from a `while (true)`. A condition that never
becomes true is the normal way to use it wrongly — the request was never made, the stub was never
configured — and a test that hangs until the runner's timeout reports the file, not the wait. The
failure names the `label` instead:

```text
[vitest-auto-spy] flushEventLoopUntil: the SDK handshake was still not ready after 20 real
event-loop turns. Three causes, in the order they turn out to be true. The work started but a
dynamic `import()` had not finished … Or the work never started …. Or it is waiting on a timer
rather than on the event loop — timers stay frozen here, and only `advanceTimers()` moves them.
```

The first of the three is the one that costs the most time to diagnose, which is why it is named
first: a **cold** chunk takes more turns than the budget, and the giveaway is that only the *first*
such test in a file fails while every later one passes off the module cache. That reads as a flake,
and it is not — the answer is to await the module rather than count turns, with
[`settleDynamicImport`](#settledynamicimport-load-turns) below.

## `settleDynamicImport(load, turns?)`

```ts
const module = await settleDynamicImport(() => import('@scope/lazy-feature'));
```

Two situations, one mechanism.

Production code that does `await import('./thing')` on a click leaves the spec with no promise to
await. Awaiting the _same_ specifier here resolves against the same module instance, and the real
turns that follow let the component's own continuation drain.

The second is a bundled Angular suite where a symbol re-exported through a barrel reads as
`undefined` until its chunk has been evaluated. Awaiting the import is what evaluates it — and,
unlike a bare `await import('…')` with a comment, the name says why the line is there, which is what
keeps the next "remove the unused line" pass from deleting it.

Spinning `await Promise.resolve()` instead is worse than not waiting: the tests go green and the
continuation lands after teardown, producing eight `NG0205: Injector has already been destroyed`
entries under "Unhandled Errors", no failing test, and a non-zero exit code.

## The clock

```ts
import { mockSystemTime, useCountingClock, withSystemTime } from 'vitest-auto-spy/setup';
```

### `mockSystemTime(time)` and `withSystemTime(time, body)`

Freeze the clock whether or not fake timers are already running. With fakes installed this is
`vi.setSystemTime`; without them it installs `Date`-only fakes, so timers stay real.

**An assertion that contains a date must set the clock.** Otherwise the expected string is computed
from `new Date()`, and the test starts failing on its own some days after it was written — which
reads as a regression and is not one.

The ported `jest.spyOn(global, 'Date')` is not the way. Fake timers already own that global, so it
throws `Date is not a constructor` with a stack in production code and no mention of timers
anywhere.

### `useCountingClock(options?)`

```ts
describe('MetricsCollector', () => {
  const clock = useCountingClock();

  it('stamps each event with the next tick', () => {
    collector.push('a');
    collector.push('b');

    expect(sent()).toEqual([
      { name: 'a', at: 1 },
      { name: 'b', at: 2 },
    ]);
    expect(clock.value).toBe(3);
  });
});
```

Under fake timers every call inside one test reports the same "now", so a spec that asserts on
**order** or **duration** — analytics batches, tracing spans, a rate limiter, a TTL cache,
dedupe-by-time — cannot express its expectation at all.

Patching `Date.now` by hand does not survive a suite that keeps fakes on globally:
`vi.useFakeTimers()` installs a _fresh_ `Date` on every call, so a module-scope or `beforeAll` patch
is left sitting on an object nothing reads any more, and the naive undo (`afterEach(() => { Date.now
= saved })`) re-attaches a dead clock's `now` to the live one, where it breaks a later file.
`useCountingClock` and `mockNow` re-apply per test and hand the undo to `restoreMockedProps()`,
which recorded the exact object it patched.

---

Source: https://asdalexey.github.io/vitest-auto-spy/utilities/eslint-plugin

# ESLint plugin

```js
// eslint.config.js
import autoSpy from 'vitest-auto-spy/eslint-plugin';

export default [{ files: ['**/*.spec.ts'], ...autoSpy.configs.recommended }];
```

Scope it to spec files yourself: every rule is about test code, and `Object.defineProperty` or an
object of `vi.fn()`s is perfectly reasonable in application code.

**Flat config only**
The legacy `.eslintrc` `plugins: ['…']` form resolves plugin names to `eslint-plugin-*` packages,
which a subpath export of this package can never be.

## Rules

| Rule                           | Recommended | Fix       | Flags                                                                                 |
| ------------------------------ | :---------: | --------- | ------------------------------------------------------------------------------------- |
| `prefer-provide-auto-spy`      |   `warn`    | —         | a hand-rolled `useValue` **or** `useFactory` → `provideAutoSpy(Class)` / `provideAutoSpyForToken(TOKEN)` |
| `prefer-create-spy-from-class` |   `warn`    | —         | an object literal of two or more `vi.fn()`s → `createSpyFromClass` / `createAutoMock`, unless it is a factory's own seed |
| `prefer-inject-spy`            |   `warn`    | suggest   | `vi.spyOn(TestBed.inject(X), 'm')`, inline or via a `const` → `injectSpy(X).m`         |
| `prefer-as-spy`                |   `warn`    | `--fix`   | `TestBed.inject(X) as Spy<X>` → `asSpy(TestBed.inject(X))`, import and all             |
| `no-object-define-property`    |   `error`   | suggest   | `Object.defineProperty` in a spec → `mockReadonlyProp` / `mockValueProp`              |
| `no-expect-in-subscribe`       |   `error`   | suggest   | `expect()` inside a `subscribe()` callback → `expectEmission` / `firstValueFrom`      |
| `no-shared-module-level-mock`  |   `error`   | —         | an **exported** value holding `vi.fn()`s → export a factory that returns it           |
| `no-mocked-for-spy`            |   `warn`    | `--fix`   | `Mocked<T>` in any type position → `Spy<T>`, import and all                            |
| `no-done-callback`             |   `error`   | —         | `it('x', (done) => …)` → `async` + an awaited assertion                               |
| `no-floating-assertion`        |   `error`   | —         | `expect()` in a `.then()` nobody awaits → `expect(await promise)`                     |
| `no-overridden-provider`       |   `error`   | —         | two providers for one token in one array → the earlier one never runs                 |
| `no-inject-before-override`    |   `warn`    | —         | `TestBed.inject()` in a hook, in a suite that still calls `override*`                  |

The six `error` rules are the ones that catch a test being _wrong_ rather than verbose.
`Object.defineProperty` leaves no way back — nothing restores the original descriptor, so the patch
leaks into the next file under `isolate: false`. An `expect()` inside `subscribe()` never runs if
the stream stays silent, leaving a green test that asserted nothing.

And an exported double is built once per **module**, not once per test:

```ts
// ❌ every importing spec shares these spies, for the whole worker
export const actionContext = { actions: { navigateToSection: vi.fn() } };

// ✅ one set per caller
export const createActionContext = () => ({ actions: { navigateToSection: vi.fn() } });
```

Under `isolate: false` a module is evaluated once per worker, so every importing file shares one
object. `clearMocks: true` does reach the spies inside it — [measured](#no-shared-module-level-mock-one-module-two-files) — and
clears their calls; what it cannot clear is the state the fixture keeps next to them, which crosses
from whichever file ran first into all the rest. The rule
stops at every function boundary, so the factory form — the fix — is not flagged along with the
problem. Scope it to fixture modules and spec files alike; a spec file
[should export nothing at all](https://asdalexey.github.io/vitest-auto-spy/utilities/setup#shared-fixtures-are-functions-not-constants).

And a `done` parameter is not a style question. Vitest passes a callable `TestContext` there, so
calling it throws — `done() callback is deprecated, use promise instead` on Vitest 4, [measured
below](#no-done-callback-what-the-first-parameter-actually-is). That is the harmless case. In the
shape a Jasmine suite is actually full of, the call sits at the bottom of a callback, the body
returns `undefined` before it runs, and the test **passes** having run almost none of itself. Four such tests sat green for years in the suite this
rule came from; nothing but a type-checker ever noticed, and only indirectly.

And a promise chain nobody awaits is the same failure as `subscribe()`, one queue over.
`compileComponents().then(() => expect(…))` as a statement of its own runs its callback after the
test that wrote it has finished, so the assertion cannot fail it — and under zone.js the resulting
rejection is drained into `console.error` rather than reported, leaving a green test and a line of
stderr. The rule looks only at the _immediately_ enclosing callback, because that is the scope where
awaiting the chain is the actual fix: an `expect()` parked in a `subscribe()` or a `setTimeout()`
inside the `.then()` is left to `no-expect-in-subscribe` and to
[`setupAutoSpy({ strayRejections: true })`](https://asdalexey.github.io/vitest-auto-spy/utilities/setup#_8-failing-on-a-rejection-zone-js-swallowed),
which catches at runtime what no selector can see.

`no-mocked-for-spy` is a `warn` because `Mocked<T>` has legitimate uses next to `vi.mocked()`; what
it flags is the declaration form, where the assignment then fails with a list of private field names
that says nothing about the real cause.

`prefer-as-spy` is the same question one line down, and it is the one a migration meets in bulk:
`devicesService = TestBed.inject(DeviceListService) as Spy<DeviceListService>` is written once per injected
double in a `jest-auto-spies` suite, and every one of them fails with `TS2352` under this library —
[the most common compile error a migrated Angular suite produces](https://asdalexey.github.io/vitest-auto-spy/migrating#reading-a-spy-back-out-of-the-container).
`asSpy(...)` is the same assertion without the cast, so the rule fixes it under `--fix`.

## Two things these rules learned the hard way

**A configured spy is still a spy.** `vi.fn()` and `vi.fn().mockReturnValue(of([]))` are the same
double, one of them tuned — but the check behind `prefer-provide-auto-spy` and
`prefer-create-spy-from-class` read the immediate callee and stopped, so it saw the bare form and
missed every configured one. In one `providers` array that meant the double on one line was flagged
and the one on the next was not:

```ts
{ provide: A, useValue: { getProductCardData: vi.fn() } },              // flagged
{ provide: B, useValue: {                                              // silent, until now
    getProducts: vi.fn().mockReturnValue(of([])),
    getProductById: vi.fn().mockReturnValue(of(null)),
} },
```

Exactly backwards: the more a hand-rolled double has been tuned, the further it has drifted from the
class it stands in for, and the more it was worth reporting. The chain is now unwound to the call
that created the mock, however long it is.

**A token is not a class.** `prefer-provide-auto-spy` used to recommend `provideAutoSpy(Token)` for
everything, and on an `InjectionToken` that advice does not compile — `provideAutoSpy` reads a class
prototype, and a token has none. Three migration batches reported it independently; in one of them
six of eight reports were on tokens. The rule now tells the two apart — by the declaration when
`new InjectionToken(…)` is within the resolver's reach, by the `SCREAMING_SNAKE_CASE` spelling
otherwise — and names `provideAutoSpyForToken(TOKEN)` for a token, while the class message mentions
the token form too.

## The trap this plugin's own advice sets

`TestBed.inject()` and `TestBed.createComponent()` **instantiate** the testing module, and after
that every `TestBed.override*` throws. Migrating to `provideAutoSpy` walks people into it: a
hand-rolled `useValue` configured its return values inside the literal, and the replacement has
nowhere to put them, so the line goes into `beforeEach`.

```ts
beforeEach(() => {
  TestBed.configureTestingModule({ providers: [provideAutoSpy(Api)] });
  asSpy(TestBed.inject(Api)).load.mockReturnValue(of(page)); // ❌ the module is now instantiated
});
```

Every `override*` in the suite then throws — including one written *above* this line, inside a
`createComponent` helper the tests call. Found twice independently after a migration, once for
sixteen tests at a stroke. Two repairs, both in the message:

```ts
it('renders', () => {
  TestBed.overrideProvider(Other, { useValue: x });
  injectSpy(Api).load.mockReturnValue(of(page)); // ✅ configured after every override
});

const api = () => injectSpy(Api);                 // ✅ or keep the access lazy, so that
                                                  //    instantiation happens in the first test
```

The check is deliberately **order-free**, because lexical order is not run order — the helper above
is the case that proves it. It asks whether the suite overrides at all, with the one exemption that
can be read off the source: an `override*` sitting in the same hook body ahead of the injection
really does run first. A suite calling `TestBed.resetTestingModule()` is exempt outright.

## Two providers, one token

Angular keeps the **last** provider registered for a token, so everything above it is dead. In a
testing module that is not tidiness:

```ts
providers: [
  provideAutoSpy(DisplaySettingsService),                               // ❌ never runs
  { provide: DisplaySettingsService, useValue: mockDisplaySettingsService },  // this is what DI hands out
]
```

Eight tokens in one spec file were registered both ways at once. It misleads from both sides: the
author believes there is an auto-spy and writes assertions against one, while the double actually
injected is the hand-rolled object drifting from the class — and whoever later comes to replace that
object sees `provideAutoSpy` beside it and reads the migration as already done.

Tokens are compared as written, not resolved: in a `providers` array a token appears by name, once,
next to the double it stands for, so there is nothing for a resolver to add. The rule offers no fix,
because deleting either line is a valid repair and they mean opposite things — keeping the auto-spy
is usually what was wanted, and only the author knows whether the hand-rolled object was carrying
configuration that has to move into `provideAutoSpy`'s second argument first.

## `no-expect-in-subscribe` reports one shape and three different edits

Five migration batches split this work by hand, and the proportions move per *file*, not per suite:
110 of 111 places were a mechanical inversion in one, 36 of 119 in another. Reading one message for
all of them is what cost the time, so the rule now says which of the three it is looking at.

```ts
// 1. the subscription is the last thing the test does — invert it
const value = await firstValueFrom(source$);
expect(value).toBe(1);

// 2. something after it is what makes the stream emit — hold the promise instead.
//    `await firstValueFrom(...)` deadlocks here: the await never returns, so the trigger
//    never runs. `expectEmission` subscribes when you call it, not when you await it.
const emission = expectEmission(service.getCurrentLevel());
httpMock.expectOne(url).flush(payload);
await expect(emission).resolves.toEqual(payload);

// 3. the assertion is in the failure branch — `expectEmission` resolves on a value
await expect(firstValueFrom(source$)).rejects.toBeInstanceOf(UdmsStatusError);
```

The signal for the second is entirely syntactic: there is another statement after the one holding
the `subscribe`. The third is which handler the assertion sits in, positional or named — and it is
worth saying that `subscribe({ next: () => expect.unreachable(…), error: (e) => expect(e).toBe(err) })`
collapses to the single `rejects` line as well, because guarding against an emission is what
`rejects` already does.

It also reads assertions the callback reaches through a helper:

```ts
const assertShape = (data: Content): void => {
  expect(data.items).toHaveLength(3);
};

source$.subscribe((data) => assertShape(data)); // still an assertion that may never run
```

One step through a name bound in the same file, which needs no type information and covers the
shape. A helper declared *inside* the callback is counted once, not twice.

## Options

`prefer-create-spy-from-class` takes one:

```js
'vitest-auto-spy/prefer-create-spy-from-class': ['warn', { minRunnerFns: 1 }],
```

The default is `2`, and the reason is what the rule cannot see: an object holding one `vi.fn()` is
indistinguishable from an options bag with a callback in it, and the rule fires on every object
literal in a file. Seven batches nonetheless tripped over the asymmetry — two doubles on adjacent
lines, one flagged and one not — so the threshold is named in the message and configurable here. The
case those reports were actually about is covered from the side that can prove it:
`prefer-provide-auto-spy` has a `provide:` next to the object, so it fires at **one**, and since it
learnt to follow a name to the `const` above the TestBed it reaches the same doubles.

A rule must not punish its own fix, and `prefer-create-spy-from-class` used to. The object handed
to one of this library's factories is a **seed**, not a hand-rolled double, and there is no other
form it could take:

```ts
const xhr = createAutoMock<XhrLike>({ send: vi.fn(), abort: vi.fn() }); // ✅ never flagged
const api = mockDeep<Api>({ api: { load: vi.fn(), save: vi.fn() } });   // ✅ nor at any depth
```

Anything inside a call to `autoMocked`, `createAutoMock`, `createMock`, `createSpyClass`,
`createSpyFromClass`, `mockConstructor`, `mockDeep`, `provideAutoSpy` or `provideAutoSpyForToken`
is exempt. `prefer-provide-auto-spy` needs no such exemption: a `useValue` a factory built is a
call, and it only ever looked at object literals.

## Which rules fix, and why so few

Two of the twelve rewrite the source on their own, three offer the rewrite as a suggestion, and the
split is about what a wrong guess costs rather than about how hard the rewrite is.

`no-mocked-for-spy` touches nothing but a **declaration**. Get it wrong and the file stops
compiling — the loudest and cheapest failure a codebase has — so it is one of the two rules that run
under `--fix`, and it does the whole edit:

```ts
// before
import { Mocked } from 'vitest';
let cart: Mocked<CartService>;

// after --fix
import type { Spy } from 'vitest-auto-spy';
let cart: Spy<CartService>;
```

The `Mocked` import goes when the rename orphans it — with the declaration when it was the last
specifier, out of the braces when it was not. And the rule stands back where it cannot prove the
rename: a `Mocked` the file declares itself is not Vitest's, a `Spy` already bound to something
else is not free, and `Mocked<{ total: Mock }>` asks a different question of the type system than
`Spy<T>` answers. Those are still reported, without a fix.

`prefer-as-spy` earns the same licence from the other end: the cast it reports is the developer's own
assertion that this value is a `Spy<X>`, and `asSpy` is a typed identity function — so the rewrite
keeps that assertion whole, changes nothing but how it is spelled, and lives entirely at the level of
types. Nothing has to be known about another file, because the rule decides nothing: the cast decided
it, and a wrong fix fails to compile.

```ts
// before
devicesService = TestBed.inject(DeviceListService) as Spy<DeviceListService>;

// after --fix
import { asSpy } from 'vitest-auto-spy';
devicesService = asSpy<DeviceListService>(TestBed.inject(DeviceListService));
```

The type arguments are carried across rather than left to inference. `Spy<T, Options>` and
`asSpy<T, Options>` take the same parameter list, so moving them is a transposition and the line
after the fix asserts exactly what the line before it did — including `Spy<Cinemas, { overload:
'first' }>`, which inference would silently drop. It also keeps the one case where inference is
actively wrong: on a **generic** class `TestBed.inject` answers `Service<any>`, and that `any`
surfaces eight levels down as a mismatch between `AddPromiseSpyMethods<unknown>` and
`WithMockReturnValue<…>`, with nothing in the message pointing at the spec.

Two shapes are left alone on purpose. A `Spy` the file declares itself is not this library's type,
and a cast that hops through `unknown` — `{} as unknown as Spy<CartService>` — says outright that the
value is *not* a `CartService`, so `asSpy<CartService>(...)` could not compile; that shape wants a
real double (`createAutoMock<T>()`), not a rename. The one exception is
`TestBed.inject(X) as unknown as Spy<X>`, where the container returns `X` by construction and the
`as unknown` was only there to silence `TS2352` — that one is fixed, hop and all.

The other three change **behaviour**, which is exactly what they are for, and that is why they only
suggest. Whether `injectSpy(X)` finds a spy at all is decided by a `provideAutoSpy(X)` that usually
lives in another file. `mockValueProp` leaves the property writable and configurable where
`Object.defineProperty` sealed it — and the suggestion picks the helper the descriptor asks for,
`mockValueProp` for a `{ value }` and `mockReadonlyPropGetter` for a `{ get }`. And
`no-expect-in-subscribe` rewrites a whole test:

```ts
// ❌ what a mechanical migration off Jasmine's done callback produced
it('maps the products', () =>
  new Promise<void>((done) => {
    service.getProducts(id).subscribe((products) => {
      expect(products).toEqual(expected);
      done();
    });
  }));

// ✅ what accepting the suggestion produces
it('maps the products', async () => {
  const products = await firstValueFrom(service.getProducts(id));

  expect(products).toEqual(expected);
});
```

That one template was 111 of the 133 violations in a batch of 22 migrated files, so it is worth the
recogniser. It is offered only for the exact frame above — one `subscribe` statement in the promise
executor, one block-bodied callback, `done` mentioned once and called last — because anything else
in the executor is usually the statement that *triggers* the source, and that has to run while
something is already listening. An editor offers all three; a human accepts them.

The remaining five have no per-node edit to offer. `createSpyFromClass` needs the class an object
literal never names, `provideAutoSpy` discards the return values the `useValue` body was setting
up, and `Object.defineProperties` is one `mockValueProp` statement per entry. Each of those is an
edit across a file, not across a node.

## Measured: what each rule is worth

Every rationale above is a claim about what a run does, so each one was run. Vitest 4.1.9, this
repository's own configs — the default project, `vitest.shared-env.config.mts` for `isolate: false`,
the zone project for the zone.js half — with one probe spec per rule, each containing an assertion
that cannot be true.

| Rule | Without it, the run says | Verdict |
| --- | --- | :-: |
| `no-expect-in-subscribe` | nothing — [4 of 4 forms green across 4 stream behaviours](https://asdalexey.github.io/vitest-auto-spy/core/observable-assertions#measured-four-forms-against-four-streams) | green |
| `no-done-callback` | nothing, when `done()` sits in a callback: the body returns `undefined`, the test ends, the assertion lands after it | green |
| `no-floating-assertion` | zoneless: `Unhandled Rejection`, exit 1, no test named. Under zone.js: one of two rejections vanishes entirely | green |
| `no-shared-module-level-mock` | nothing — the fixture's own state crosses files under `isolate: false` | green |
| `no-object-define-property` | nothing in the file that patched; the **next** file reads the patched value | green |
| `no-mocked-for-spy` | `TS2322 … missing the following properties from type 'CartService': http, cache` | compile |
| `prefer-create-spy-from-class` | `TypeError: cart.applyPromo is not a function` | red |
| `prefer-provide-auto-spy` | the same, one DI hop away | red |
| `prefer-inject-spy` | `spy.getPlans.nextWith is not a function` | red |
| `no-inject-before-override` | `Cannot override provider when the test module has already been instantiated. Make sure you are not using \`inject\` before \`overrideProvider\`` | red |
| `no-overridden-provider` | nothing, where the hand-rolled double happens to answer: the `provideAutoSpy` beside it is dead and the assertions pass. Read back with `injectSpy` instead, it is red — and [`injectSpy` says why](https://asdalexey.github.io/vitest-auto-spy/adapters/angular#injectspy-says-when-it-got-the-real-thing) | green |

The column that matters is the last one. Six rules guard against a test that is **green and wrong**,
which is the only failure mode a suite cannot report on itself; four guard against a red test whose
message is already clear; one is a compiler error. Severity in `configs.recommended` follows exactly
that split.

`no-overridden-provider` is the one whose verdict depends on the rest of the file, which is why it
is worth having as a rule rather than a runtime check. Read the token back with `injectSpy` and the
run is red with a diagnostic naming the cause; read it back with `TestBed.inject` and assert against
the hand-rolled double, which is what the file that prompted this rule did, and everything passes
while the `provideAutoSpy` above it never ran.

### `no-done-callback` — what the first parameter actually is

The parameter is not `undefined` and not a plain object. Vitest 4 passes a **callable** `TestContext`:

```text
typeof done                → 'function'
Object.keys(done)          → signal, task, skip, annotate, onTestFailed, onTestFinished
done()                     → Error: done() callback is deprecated, use promise instead
```

So the synchronous call is caught, loudly and by name. That is the shape nobody writes. The shape
every Jasmine suite is full of puts `done()` at the bottom of a callback:

```ts
it('loads', (done) => {
  setTimeout(() => {
    expect(1).toBe(999); // ← throws here, so done() is never even reached
    done();
  }, 0);
});
```

The body returns `undefined`, so the test is over before the timer fires. Measured: **green**, with
the `AssertionError` arriving afterwards as one of the run's unhandled errors, and the deprecation
error never reached at all. The rule exists because the loud case is the rare one.

### `no-floating-assertion` — three runners, three different silences

The same two tests — an `expect()` in a `.then()` nobody awaits, and an `async` helper called without
`await` — under three configurations:

| | tests | what the runner reports |
| --- | :-: | --- |
| zoneless | **2 passed** | 2 `Unhandled Rejection`, exit 1, neither attributed to a test |
| zone.js | **2 passed** | 1 error — zone.js drained the other into `console.error` |
| zone.js + `setupAutoSpy({ strayRejections: true })` | **1 failed \| 1 passed** | the swallowed one is now a named failure on the right test |

Read down the middle column: the assertion is false in every row and the test is green in every row
but the last. `strayRejections` is what turns the case no selector can see — an `expect()` parked in a
`setTimeout` inside the `.then()` — back into a failure with a test name on it.

### `no-shared-module-level-mock` — one module, two files

The fixture carries a stable id, so there is no need to argue about whether the module is shared:

```ts
// probe fixture, imported by two spec files
export const analytics = { sent: [] as string[], track: vi.fn((e: string) => analytics.sent.push(e)) };
export const moduleLoadId = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
```

```text
isolate: true    file 1: load=…-mdncyn     file 2: load=…-ywp3q0   sent=[]
isolate: false   file 1: load=…-n0v4yh     file 2: load=…-n0v4yh   sent=[from-file-1]
```

Same id, so one evaluation, and file 2 reads what file 1 pushed. Note **what** leaked: not the spy's
calls — `clearMocks: true` does reach a module-level `vi.fn()` and does clear them, three separate
probes said so. What leaks is everything else a fixture holds next to its spies, which is why the fix
is a factory rather than a `beforeEach` that clears harder. Which file runs first is the runner's
choice, so the failure arrives as flakiness.

### `no-object-define-property` — nothing puts the descriptor back

One file patches a global the way a spec usually does, then calls everything the runner offers for
undoing things:

```ts
Object.defineProperty(navigator, 'onLine', { value: false, configurable: true });

vi.restoreAllMocks();
vi.resetAllMocks();
vi.unstubAllGlobals();
```

```text
after every restore the runner offers: onLine=false   ← same file
onLine=false                                          ← the next file
after restoreMockedProps: onLine=true                 ← mockValueProp, run on its own
```

The third line is the fix, and it is measured on its own for a reason: run it **after** the
`defineProperty` file in the same worker and it reads `false` too. The original descriptor was gone
before the correct helper ever saw the property — a suite cannot recover from this one file-by-file,
which is what makes it an `error` rather than a `warn`.

### The three `prefer-*` rules — drift, and one line that undoes a provider

A hand-written double is correct on the day it is written. The class then grows a method:

```text
F1  hand-written { total: vi.fn() }        → TypeError: cart.applyPromo is not a function
F2  createSpyFromClass(CartService)        → follows the class, no edit
```

And the type system does not help, because the double never satisfied the class in the first place —
which is what the `as unknown as CartService` in front of it is hiding:

```text
TS2741: Property 'rate' is missing in type '{ total: Mock<Procedure>; add: Mock<Procedure>; }'
        but required in type 'CartService'.
```

`no-mocked-for-spy` is the same message one step over. `Mocked<T>` demands the private fields a spy
does not have, and says so in the vocabulary of the class rather than of the mistake:

```text
TS2322: Type 'Spy<CartService, SpyOptions>' is not assignable to type 'Mocked<CartService>'.
        Type 'Spy<CartService, SpyOptions>' is missing the following properties
        from type 'CartService': http, cache
```

Nothing in that names `Mocked`, which is why the rule fixes the declaration rather than explaining
the error.

`prefer-inject-spy` is the sharpest of the three, because it is one line that quietly undoes a
provider:

```ts
TestBed.configureTestingModule({ providers: [provideAutoSpy(BillingPlansService)] });

const service = TestBed.inject(BillingPlansService);
vi.spyOn(service, 'getPlans'); // ← replaces the auto-spy's method with a plain vi.fn()

injectSpy(BillingPlansService).getPlans.nextWith(['PRO']);
// TypeError: spy.getPlans.nextWith is not a function
```

The provider is still an auto-spy; the method on it is no longer one, so every observable and promise
helper on it is gone. Read the same dependency with `injectSpy(BillingPlansService)` and `nextWith` works —
that is the second probe, and it emits `["PRO"]`.

## Picking rules by hand

`configs.recommended` is a plain flat-config object, so the severities are yours to change:

```js
import autoSpy from 'vitest-auto-spy/eslint-plugin';

export default [
  {
    files: ['**/*.spec.ts'],
    plugins: { 'vitest-auto-spy': autoSpy },
    rules: {
      'vitest-auto-spy/no-expect-in-subscribe': 'error',
      'vitest-auto-spy/prefer-provide-auto-spy': 'off',
    },
  },
];
```

Every message ends with a link to the matching recipe in the README's
[How to mock](https://github.com/ASDAlexey/vitest-auto-spy#how-to-mock) section: a rule that only
says "don't" moves the problem rather than solving it. The rules travel with the API they
recommend, so they are versioned together and stop being re-written in every project that installs
the package.

---

Source: https://asdalexey.github.io/vitest-auto-spy/utilities/cli

# The CLI

Two commands, no dependencies, 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
```

They are one binary because they answer one question from two directions — _is anything in this
test suite quietly not doing what it looks like it is doing?_ `doctor` asks it of the repository,
`init` asks it of the agent about to write the next spec.

## `doctor` — defects that never fail

Every check here 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 a person who happens
to open the file. That is what makes them survive for years, and it is also why a linter cannot
find most of them — the evidence is spread across files.

```
$ npx vitest-auto-spy doctor
vitest-auto-spy doctor — /work/app
1 284 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                                                      | Why nothing catches it                                                                                                                                                                       |
| ------------------------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tsconfig-glob-matches-nothing` | An `include` pattern that matches no file                          | A glob that matches nothing type-checks nothing, and `tsc` reports success                                                                                                                   |
| `tsconfig-file-missing`         | A `files` entry naming a file that is gone                         | Same — the config is only read by editors once the runner stopped using it                                                                                                                   |
| `spec-imported-by-non-spec`     | A production module importing a `*.spec.ts`                        | Under a shared environment the import is a cycle, and the spec loses its own suite                                                                                                           |
| `spec-exports-fixture`          | A spec importing another spec                                      | The imported file's suites are collected twice and its hooks run in a foreign file's context                                                                                                 |
| `foreign-runner-pragma`         | `@jest-environment` and friends left in a spec                     | Vitest never reads them; the environment comes from the config, so the comment looks operative                                                                                               |
| `dead-runner-config`            | `jest.config.*`, `karma.conf.*` for a runner that is not installed | It is the first file a newcomer — or an agent — reads to learn how tests run                                                                                                                 |
| `orphan-runner-file`            | A setup file only that dead config referenced                      | One found this way had been empty since before the migration: a year as a setting that configured nothing                                                                                    |
| `angular-build-splitting-off`   | `@angular/build` in `[22.1.5, 22.1.7)`                             | The unit-test bundle is built with code splitting off. `--coverage` then grows by hundreds of megabytes with no plateau, and the builder emits no warning — see [Angular](https://asdalexey.github.io/vitest-auto-spy/adapters/angular) |
| `no-agent-instructions`         | No `AGENTS.md` / `CLAUDE.md` / `GEMINI.md` names the package       | A note, not an error. It is the one moment where saying so costs nothing                                                                                                                     |

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 syntactically valid glob that matches nothing.
Nine of 152 spec tsconfigs still covered their specs.

**It never writes.** `doctor` reads the repository and prints; there is no `--fix`. Exit code 1
when anything above a note was found, 0 otherwise, so it drops into CI as one line.

Two shapes of pattern are deliberately exempt, because for them "matches nothing" is not evidence
of anything: a declaration-only glob (`src/**/*.d.ts`, routinely a placeholder for ambient types
that do not exist yet) and a pattern rooted in a directory the scan never enters (`dist`,
`out-tsc`, `coverage`).

## `init` — the pointer an agent actually reads

There is no zero-setup path into any coding agent's instruction context. Every tool discovers rules
from a fixed set of repository-root or dot-directory paths, and **none of them scans dependencies**
— the skill and the `AGENTS.md` shipped inside this package's tarball are never auto-discovered.
Something in the repository has to point at them, once.

```bash
npx vitest-auto-spy init
```

**Tier 1, always written** — three root files cover the whole field:

| File                                      | Read by                                                                                                                                                 |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AGENTS.md`                               | Codex, Cursor, Copilot, Cline, Windsurf, Zed, OpenCode, Qwen, Roo, Junie, Aider                                                                         |
| `CLAUDE.md`                               | Claude Code, and GLM / Kimi running inside it                                                                                                           |
| `GEMINI.md`                               | Gemini CLI, which does not read `AGENTS.md` by default                                                                                                  |
| `.claude/skills/vitest-auto-spy/SKILL.md` | Claude Code — a stub whose frontmatter is copied verbatim from the shipped skill, over a body that only points at `node_modules`, so it cannot go stale |

**Tier 2, only when the tool's own directory already exists**, and glob-scoped so it costs no
context on a task that is not about tests: `.cursor/rules/`, `.github/instructions/`,
`.windsurf/rules/`, `.devin/rules/`, `.clinerules/`, `.roo/rules/`.

**Never created:** `.rules`, `.cursorrules`, `.windsurfrules`, or `.clinerules` as a _file_. Zed
resolves instructions first-match-wins over an ordered list that ends in `AGENTS.md`, so creating
any of them silently shadows the entire project's instructions. If one already exists, `init`
appends to it rather than leaving it stale.

### Why a command rather than the snippet

The [paste-able snippet](https://asdalexey.github.io/vitest-auto-spy/agents) has to state every runner and every adapter, and half of it is
false for any given repository. `init` reads the consuming `package.json` and the test config and
writes only the true half — which subpath matches this runner, which adapter matches the framework,
the actual path of the setup file that needs `import 'vitest-auto-spy/rxjs'`, and it omits the rxjs
bullet entirely when rxjs is not installed.

### Idempotent by construction

Everything is written between markers:

```md
<!-- vitest-auto-spy:begin v=3.7.0 sha=90452bea -->

…

<!-- vitest-auto-spy:end -->
```

The text between them is regenerated in full on every run; text outside them is never read and
never reformatted. Running `init` after an upgrade is a no-op or a one-hunk diff. A `CLAUDE.md`
that is a symlink to `AGENTS.md`, or that already carries an `@AGENTS.md` import line, is left
alone — both are ways of keeping one instruction file, and writing through either would duplicate
the block.

The block is kept under 1.6 kB on purpose. Codex caps the whole root→cwd `AGENTS.md` chain at
`project_doc_max_bytes` (32 768 bytes by default) and silently truncates past it, so `init` warns
when the file it appended to crosses that line.

### Flags

| Flag              | Command | Effect                                                                    |
| ----------------- | ------- | ------------------------------------------------------------------------- |
| `--cwd <dir>`     | both    | Run against another directory                                             |
| `--check`         | `init`  | Write nothing; exit 1 if the block is missing or out of date. The CI form |
| `--dry-run`       | `init`  | Print what would change and write nothing                                 |
| `--uninstall`     | `init`  | Remove the managed blocks and delete the files `init` created             |
| `-h`, `--help`    | both    | The usage screen                                                          |
| `-v`, `--version` | both    | The installed version                                                     |

`init --check` in CI is the same shape as `llms:check` in this repository: it fails when the block
on disk is not the block the installed version would write, which is exactly when an upgrade
changed the advice.

## In CI

```yaml
- run: npx vitest-auto-spy doctor
- run: npx vitest-auto-spy init --check
```

Neither needs a network, a config file, or a token. The CLI ships with the package, has no runtime
dependencies of its own, and is the only part of it allowed to touch `node:fs` — an invariant this
repository checks on every build.

---

Source: https://asdalexey.github.io/vitest-auto-spy/utilities/editor-diagnostics

# Editor diagnostics

A rule that fires in CI arrives an hour late. The shapes this library warns about — a spy declared
as the class, an `expect()` inside `subscribe()`, a `done` callback Vitest never calls — are all
cheap to fix while the cursor is still on the line and expensive to find afterwards, because every
one of them **passes**.

There is one channel, and it is already in the package:
[`vitest-auto-spy/eslint-plugin`](https://asdalexey.github.io/vitest-auto-spy/utilities/eslint-plugin). Twelve rules over a real syntax tree,
with a fix or a suggestion where the rewrite is decidable — the same rules in the editor and in CI,
so nothing passes locally and fails on the build. No editor needs a plugin of this package's own;
it needs its ESLint integration switched on, which every IDE below has.

## WebStorm and the other JetBrains IDEs

WebStorm, IntelliJ IDEA Ultimate, PhpStorm, PyCharm Professional and RubyMine all run ESLint
natively, so the rules light up **inline, with no plugin to install** — the same twelve checks, in
the editor, in the Problems tool window, and under **Code → Inspect Code** for the whole project.

Install and configure once:

```bash
npm i -D vitest-auto-spy eslint
```

```js
// eslint.config.js — flat config, at the repository root
import autoSpy from 'vitest-auto-spy/eslint-plugin';

export default [
  {
    files: ['**/*.spec.ts', '**/*.spec.tsx', '**/*.test.ts', '**/*.test.tsx'],
    ...autoSpy.configs.recommended,
  },
];
```

Then in **Settings → Languages & Frameworks → JavaScript → Code Quality Tools → ESLint**, pick
**Automatic ESLint configuration** — WebStorm finds `eslint.config.js` and the local `eslint`
itself. Choose **Manual** only when the config lives outside the project root; there the fields that
matter are *ESLint package* (`node_modules/eslint`) and *Configuration file*.

Three things worth knowing, because each one looks like "the rules do not work":

- **Flat config only.** The legacy `.eslintrc` `plugins: ['vitest-auto-spy']` form resolves plugin
  names to `eslint-plugin-*` packages, which a subpath export of this package can never be. WebStorm
  supports flat config from 2023.3; on an older build, upgrade the IDE rather than the config.
- **Scope the block to spec files yourself.** `Object.defineProperty` and an object of `vi.fn()`s are
  perfectly reasonable in application code — every rule here is about test code.
- **The quick fixes are ESLint's.** `⌥⏎` on a highlighted line offers *ESLint: Fix current file* and,
  where a rule ships a suggestion, the individual rewrite. `no-mocked-for-spy` and `prefer-as-spy`
  fix on their own — both touch a type, so the worst a wrong one can do is fail to compile. The rest
  suggest, because the replacement changes behaviour and should be read before it is accepted.

Prefer to see everything at once during a migration? **Code → Inspect Code…** with the scope set to
the test sources lists every finding grouped by rule, which is the shape a "how much of this suite
still hand-rolls its doubles" question actually needs.

**A native JetBrains plugin is not planned**
A plugin in the JetBrains Marketplace would duplicate an integration the IDE already has, and would
then have to keep a second copy of twelve rules — in Kotlin — in step with the TypeScript ones.
Where the ESLint route genuinely cannot reach (a repository with no ESLint at all), the honest fix
is four lines of `eslint.config.js`, not a second implementation.

## VS Code, Cursor, Windsurf, VSCodium

Install the [ESLint extension](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint)
and the flat config above is enough: the same twelve rules, inline and in the Problems panel.

```jsonc
// .vscode/settings.json
{
  // Applies the two rules that fix on their own — `no-mocked-for-spy` and `prefer-as-spy` — when
  // the file is saved. The rest offer their rewrite as a suggestion on ⌘. instead, because each one
  // changes behaviour and should be read before it is accepted.
  "editor.codeActionsOnSave": { "source.fixAll.eslint": "explicit" },

  // Flat config is the default from ESLint 9; this line only matters on an older ESLint.
  "eslint.useFlatConfig": true
}
```

Cursor, Windsurf and VSCodium install that ESLint extension from Open VSX and read the same
`.vscode/settings.json`, so nothing about the setup changes there.

## What gets underlined

| Shape                                                  | Why it is wrong                                                                        | Rule                          |
| -------------------------------------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------- |
| `expect()` inside `subscribe()`                        | a silent stream never runs the callback — the test passes having asserted nothing       | `no-expect-in-subscribe`      |
| `it('x', (done) => …)`                                 | Vitest passes a `TestContext`; the test passes having run almost none of its body       | `no-done-callback`            |
| a `.then()` chain that asserts and is never awaited    | the assertion lands after the test has finished, where nothing fails                    | `no-floating-assertion`       |
| `{ provide: X, useValue: { m: vi.fn() } }`             | `provideAutoSpy(X)` stays in step when the class grows a method                         | `prefer-provide-auto-spy`     |
| an object of `vi.fn()`s standing in for a class        | `createSpyFromClass(X)` reads the prototype instead of a list that goes stale            | `prefer-create-spy-from-class` |
| `TestBed.inject<X>()`, or a cast on the way out        | `injectSpy(X)` returns `Spy<X>` with no generic and no assertion                        | `prefer-inject-spy`           |
| `vi.mocked()` over something that is already a spy     | `Mocked<T>` loses `calledWith`, `resolveWith` and `nextWith` — auto-fixed                | `no-mocked-for-spy`           |
| `TestBed.inject(X) as Spy<X>`                          | the cast a `jest-auto-spies` suite carries everywhere stops compiling here — `asSpy(…)` makes the same claim without one, and is auto-fixed | `prefer-as-spy` |
| `Object.defineProperty` in a spec                      | nothing records the undo — `mockReadonlyProp` / `mockValueProp` do                      | `no-object-define-property`   |
| an exported module-level object of `vi.fn()`s          | under `isolate: false` every spec file shares one set of spies                          | `no-shared-module-level-mock` |
| the same token provided twice in one array             | the second provider silently replaces the first                                          | `no-overridden-provider`      |
| `TestBed.inject()` before an `override*` in the suite  | injecting instantiates the module, and every later override throws                       | `no-inject-before-override`   |

Each message ends with a link to the README recipe that shows the replacement, so the rule never
only says "don't". The full descriptions, severities and the reasoning behind which rules fix and
which only suggest are in [ESLint plugin](https://asdalexey.github.io/vitest-auto-spy/utilities/eslint-plugin).

The shapes ESLint cannot see are covered where they surface instead: importing the wrong entry point
for the runner, or calling `nextWith` without `import 'vitest-auto-spy/rxjs'`, both throw at run time
with a message that names the fix and links the page — see
[Errors that name their own fix](https://asdalexey.github.io/vitest-auto-spy/agents#errors-that-name-their-own-fix).

---

Source: https://asdalexey.github.io/vitest-auto-spy/adapters/angular

# Angular

The `vitest-auto-spy/angular` entry adds `provideAutoSpy` — a shorthand for providing an auto-spy
in a `TestBed` — plus `injectSpy`, shallow component rendering, DI-driven instantiation, zoneless
waiting, a signal matcher, `TestBed` diagnostics and the signal/readonly property mockers.

```ts
import { injectSpy, provideAutoSpy } from 'vitest-auto-spy/angular';

TestBed.configureTestingModule({
  providers: [
    provideAutoSpy(MyService),
    // accepts the same second argument as createSpyFromClass
    provideAutoSpy(ApiService, { onlyMethodsToSpyOn: ['get', 'post'] }),
  ],
});

let myService: Spy<MyService>;

beforeEach(() => {
  myService = injectSpy(MyService);
});
```

The spies are change-detection agnostic, so they work in **both zoneless and zone.js** Angular
projects — nothing here touches `NgZone` or change detection. You still need the usual Vitest +
Angular wiring (`@analogjs/vite-plugin-angular` plus a TestBed setup file).

**Running the same suite on Bun**
`bun test` cannot run Angular specs out of the box — Bun ships no DOM and cannot resolve
`templateUrl`. [`vitest-auto-spy/bun-angular`](https://asdalexey.github.io/vitest-auto-spy/runtimes/bun-angular) closes both from one preload
and re-exports everything on this page except `registerSignalMatchers` and the `TestBed`
diagnostics, which need the runner's `expect.extend` and suite-level hooks.

## An `abstract class` DI token

`abstract class LocalStorage extends AbstractStorage {}`, provided in production as
`{ provide: LocalStorage, useClass: BrowserLocalStorage }`, is the standard way to declare a
DI token in an Angular codebase — and it used to be the one shape `provideAutoSpy` could not serve.
It failed twice over: the bare call compiled and produced an empty double, while the config form
that would fix it did not compile at all (`TS2345: Cannot assign an abstract constructor type to a
non-abstract constructor type`).

Both halves work now.

```ts
abstract class LocalStorage extends AbstractStorage {
  abstract read(key: string): string | null;
  abstract write(key: string, value: string): void;
}

TestBed.configureTestingModule({ providers: [provideAutoSpy(LocalStorage)] });

const storage = injectSpy(LocalStorage);

storage.read.calledWith('token').mockReturnValue('abc');
```

`ClassType<T>` now carries an **abstract** construct signature — nothing in this library ever calls
`new` on the token, so requiring a concrete one bought no safety. At runtime the abstract members
are erased before they reach a prototype, so there is nothing to discover; when discovery comes back
empty the factory hands back the `createAutoMock` proxy, which answers every method of the declared
type. `injectSpy` recognises it as an auto-spy and stays quiet, and the hand-written workaround —
`{ provide: LocalStorage, useValue: createAutoMock<LocalStorage>() }` — is no longer needed.

One concrete member changes that, and it is worth knowing which side of the line a token is on:

```ts
abstract class LocalStorage {
  abstract read(key: string): string | null;
  clear(): void {} // discovery is no longer empty, so the fallback does not fire
}

const storage = injectSpy(LocalStorage);

storage.clear; // a spy
storage.read; // undefined — and `Spy<T>` says it is there
```

`abstract read()` is erased before it reaches a prototype, so only `clear` is discovered and the
abstract members are simply absent — the call then dies as `storage.read is not a function` inside
the component, not in the spec. Nothing can detect it automatically: TypeScript erases `abstract`,
so at runtime this class and a concrete one are the same object. Ask for it:

```ts
providers: [provideAutoSpy(LocalStorage, { fillMissing: true })];
```

See [`fillMissing`](https://asdalexey.github.io/vitest-auto-spy/core/create-spy-from-class#fillmissing-a-partially-abstract-class) for what it
does and does not fill.

## Seeding the double in the provider

Both factories take both halves: `returns` for what a spied **method** answers, `overrides` for a
member that is not a method result — an Observable property, a plain field, a signal.

```ts
provideAutoSpy(FavoritesService, {
  returns: { load: of([]) },
  overrides: { favoritesCacheUpdated$: of(undefined), favoriteItems: [] },
});

provideAutoSpyForToken(PRODUCTS, undefined, { returns: { getProducts: of([]), getById: of(null) } });
```

Until 3.5.0 the two helpers had one half each — `provideAutoSpyForToken` took property seeds,
`provideAutoSpy` took method configuration — so a double needing both was provided in one statement
and finished in another, in a `beforeEach` below it.

A seeded `overrides` member is stored **verbatim and is no longer a spy**, which is the line between
the two: seed data there, and name a method in `returns` when it must stay assertable. The reason to
prefer either over a second statement is not brevity — the shortcut people take instead is an
exported `const` provider carrying the values, and under `isolate: false` that is one set of spies
shared by every file that imports it.

### Observable properties behind a token

`observablePropsToSpyOn` is the third option both forms now share, and it matters more on the token
path than on the class one. A class tells the factory which members are methods; a type does not, so
every unnamed key of a token-driven double is a **function** spy — an `Observable` property included,
which the code under test then subscribes to as if it were a function, with the failure surfacing
far from the double.

```ts
provideAutoSpyForToken(FAVORITES, undefined, { observablePropsToSpyOn: ['favorites$'] });
// …
injectSpy(FAVORITES).favorites$.nextWith([{ id: 1 }]);
```

A member also named in `overrides` keeps its seed — hand the double a real `Subject` there when the
spec drives the stream itself, and name it here when `nextWith` is what the spec wants; the class
factory resolves the same contradiction the same way. Until 3.5.0 the option existed only on the
class path, so a token with observable members sent people back to a hand-written double — which is
what `prefer-provide-auto-spy` and `prefer-create-spy-from-class` exist to steer them away from.

## Do not write a local `injectSpy`

A wrapper of the shape `TestBed.inject(token as never) as Spy<T>`, typed
`<T>(token: abstract new (...args: never[]) => T)`, is a common thing to find already in a
repository. The library's is strictly wider: it accepts a `ClassType<T>`, an `InjectionToken<T>` and
an abstract constructor, warns when the injector returns something that is not a spy, and carries no
type assertion for the project's lint rules to argue with. Two functions with the same name and
different signatures means the import order in each file decides which one it gets — delete the
local one, or re-export this one under that name.

## Lazy spies by default

Angular tests spy a wide service and call a couple of its methods, so a spy is built on first
access rather than eagerly up-front. Everything else is unchanged: `Object.keys`,
`vi.isMockFunction`, `calledWith`, `resetAutoSpy` / `clearAutoSpy` all behave identically, because
the placeholder is an enumerable accessor.

```ts
provideAutoSpy(WideService); // lazy — the default
provideAutoSpy(WideService, { lazySpies: false }); // opt out: build every spy eagerly
```

This is the **core default rather than something this entry adds** — `createSpyFromClass` behaves
the same. Until v2 only `provideAutoSpy` turned it on, which made the Angular path quietly faster
than the plain one for no reason anybody could see. What it buys, on a forty-method class with two
methods touched: [27 ms and 35 MB against 257 ms and 425 MB](https://asdalexey.github.io/vitest-auto-spy/core/performance#memory-not-just-time).

### Is it fast enough to call in every `beforeEach`?

Yes, and it is the fastest of the three ways to build a double. Measured on the repo's own
benchmark (`npm run bench`, a ten-method class):

| Call                                          |     ops/sec | per call |
| --------------------------------------------- | ----------: | -------: |
| `provideAutoSpy(Service)` — lazy, the default | **118 900** |    ~8 µs |
| `createSpyFromClass(Service)` — eager         |      34 600 |   ~29 µs |
| `createAutoMock<Service>()` + 4 accesses      |      30 600 |   ~33 µs |

The gap is `lazySpies`, which `provideAutoSpy` turns on and the plain factory does not: a wide
service where a test touches two methods builds two spies instead of twenty. Prototype discovery is
cached per class, so calling it once per test does not re-walk the chain.

At ~8 µs, five providers across two thousand tests come to under a tenth of a second for the whole
suite. If a spec feels slow, the time is in `TestBed` — which is what
[`enableTestBedDiagnostics()`](#where-a-spec-spends-its-time) measures, and usually what
[`renderShallow`](#shallow-component-rendering) fixes.

Two things do cost more, and both are avoidable:

- **`{ lazySpies: false }`** gives up the win above. Only worth it when a spec enumerates the spy
  object itself rather than calling methods on it.
- **`autoSpyAccessors: true`** walks the prototype chain for getters and setters on every call, and
  that walk is not cached. Name the accessors you need instead when a class is spied per test.

## Shallow component rendering

`renderShallow` is the standard `TestBed` sequence a component-heavy suite ends up copy-pasting —
`configureTestingModule` + `NO_ERRORS_SCHEMA` + `overrideComponent` with emptied `imports` and a
blank template — given a name:

```ts
import { provideAutoSpy, renderShallow } from 'vitest-auto-spy/angular';

const { fixture, component } = renderShallow(TaskListComponent, {
  providers: [provideAutoSpy(TaskService), provideHttpClient()],
  inputs: { projectId: 42 }, // set through componentRef.setInput, before the first CD
});
```

| Option          | Default | What it does                                                                                                                    |
| --------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `providers`     | `[]`    | Providers for the testing module. `EnvironmentProviders` (`provideHttpClient()`, …) welcome                                     |
| `imports`       | `[]`    | Extra imports for the testing module (a stub module, a routing harness)                                                         |
| `inputs`        | —       | Values for the component's inputs — signal inputs take the **value**, not the signal                                            |
| `keepTemplate`  | `false` | Keep the real template (for `viewChild`, content projection, host bindings)                                                     |
| `keepChildren`  | `[]`    | Child components/directives/pipes that stay resolvable; everything else is dropped                                              |
| `template`      | `''`    | A stand-in template to render instead of a blank one                                                                            |
| `beforeCreate`  | —       | Runs after the module is configured, before the component exists — the seam for stubbing a dependency a field initializer reads |
| `detectChanges` | `true`  | Run the first change detection, and therefore `ngOnInit`                                                                        |

`fixture` is a real `ComponentFixture`; nothing here replaces `@angular/core/testing`. Blanking the
template keeps lifecycle hooks, inputs, signals and DI — everything a spec that asserts on
TypeScript state actually reads.

### What it saves, measured

On a private Angular 22 zoneless suite (784 specs, the AOT `@angular/build:unit-test` builder), three
of its most expensive component specs were converted and the ten-file batch re-run three times —
medians, same batch, same machine:

| Spec (479 tests in the batch, all still green) | Before | After  | Change   |
| ---------------------------------------------- | ------ | ------ | -------- |
| a container with a deep child tree (34 tests)  | 129 ms | 61 ms  | **2.1×** |
| a list rendering 58 fixtures                   | 133 ms | 75 ms  | **1.8×** |
| a small leaf component (20 tests)              | 29 ms  | 38 ms  | **0.8×** |
| the three together                             | 291 ms | 174 ms | **1.7×** |

The third row is the honest half of the result: a leaf component has almost no subtree to remove, so
the per-test `overrideComponent` costs more than it saves. **Shallow rendering pays where there is a
real child tree to skip.** Use [the diagnostics](#where-a-spec-spends-its-time) to find the files
worth converting rather than guessing.

## Building a class with auto-spied dependencies

The alternative a project writes by hand is a `providers` array listing each dependency with a
`useValue` object of `vi.fn()`s, rewritten whenever a dependency is added. Here the injector itself
answers an unknown token with a spy, so the spec names only what it wants to control:

```ts
import { createWithAutoSpies } from 'vitest-auto-spy/angular';

const { instance, spies, injector } = createWithAutoSpies(CartService, {
  providers: [{ provide: TaxService, useValue: realTax }], // explicit providers win
});

spies.get(PricingService).total.mockReturnValue(100);
expect(instance.checkout()).toBe(100);
```

The class is built through its own Angular factory, so constructor parameters **and** `inject()`
field initializers resolve normally. An unprovided token gets a `createSpyFromClass` spy (a class)
or a `createAutoMock` proxy (an `InjectionToken`); `inject(X, { optional: true })` still returns
`null`, exactly as it would in the app. `spies.get(token)` resolves through the same injector the
instance used — so it returns the explicit provider when there is one — and `spies.autoSpiedTokens()`
lists what was invented.

**Plain providers only**
This builds an `Injector.create()` injector, which does not accept the `EnvironmentProviders`
returned by `provideHttpClient()` and friends. A class that needs those belongs in a `TestBed` —
[`renderShallow`](#shallow-component-rendering), or a plain `configureTestingModule`.

## Zoneless waiting

```ts
import { flushEffects, stable } from 'vitest-auto-spy/angular';

component.filter.set('open');
await stable(fixture); // flush effects, then await the fixture
expect(component.visible()).toEqual([openTask]);

flushEffects(); // the no-fixture half: services, stores, runInInjectionContext code
```

`fixture.detectChanges()` runs a single change-detection pass and does **not** flush pending
effects, so an assertion right after it reads state that has not finished computing. In a zoneless
app the state that matters is signal-derived and effects are what move it forward. `stable` does
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. A fixture that never stabilises —
a real `HttpClient` request nothing completed, a `PendingTasks` entry nothing released, a
`setInterval` running under real timers — used to hang here until Vitest reported a 5 s _file-level_
timeout naming neither the helper nor the fixture, which blames the file for the state of one
component.

```ts
await stable(fixture, { timeout: 5000, label: 'the products fixture' });
```

Pass `label` when a spec awaits more than one fixture, so the failure says which. Pass
`{ timeout: 0 }` to disable the watchdog and wait indefinitely — worth it only for a deliberately
long real-timer test. The watchdog runs on a timer captured at import, so `vi.useFakeTimers()`
cannot stop it: a watchdog the code under test can freeze is not a watchdog.

## Resources: `httpResource()` and `resource()`

Angular's resource primitives need a **different wait each**, and neither is the one a spec reaches
for. Measured on Angular 21.2.17, zoneless TestBed:

| What                                              | What it needs to settle              |
| ------------------------------------------------- | ------------------------------------ |
| `httpResource()`, after its response is flushed   | one tick + one microtask             |
| `resource()` with an async loader                 | two rounds of the same               |
| `httpResource()` that has just been created       | a tick, or it makes **no request**   |

Getting it wrong does not fail loudly. It asserts against the resource's _default_ value — a green
test proving nothing, until the day the default changes. `settleResource` is the loop both converge
under:

```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]);
```

**That `flushEffects()` is not optional and `settleResource` cannot replace it.** An `httpResource`
issues no request until something ticks, so there is nothing for `expectOne` to find until then —
and awaiting first would spend the whole budget on a resource that stays `loading` for a reason no
amount of waiting fixes. One tick to get the request out, your flush, then one wait to take
delivery. A plain `resource()` needs no flush and so needs no tick: `await settleResource(data)` is
the whole of it.

The wait ends on any settled status, `error` and `idle` included — waiting for those would be
waiting for something that cannot happen. On expiry it names the resource and the flush it is
missing.

**Not `flushEventLoopUntil`**
`flushEventLoopUntil` takes real event-loop turns and never ticks. A resource awaited through it
finishes the whole budget having issued zero requests, then fails saying the condition was never
met. Its docstring used to claim this exact use case; it never worked.

### Skipping the request entirely — `mockResourceProp`

Everything above is the answer when the request *is* the point. Often it is not: the spec is about a
component's own logic, it never wanted an `HttpTestingController`, and the value it needs is one it
picked in advance. `mockResourceProp` replaces the property with a double the spec moves directly.

```ts
import { mockResourceProp } from 'vitest-auto-spy/angular';

const service = injectSpy(ProductService);
const products = mockResourceProp(service, 'products', []);

expect(component.emptyState()).toBe(true);

products.set([product]); // status → 'resolved'
expect(component.emptyState()).toBe(false);

products.loading(); // status → 'loading', hasValue() → false
expect(component.spinner()).toBe(true);

products.fail('offline'); // status → 'error', error() → Error('offline')
expect(component.errorMessage()).toBe('offline');
```

Nothing is ever in flight, so there is nothing to wait for — no tick, no flush, no budget, and no
way for the test to pass against a default value by accident. The resource starts `'resolved'` at
the initial value, because that is the state most assertions want and the one that would otherwise
have to be arranged.

Reactivity is genuine: the double is built from real `signal()`s, so a `computed()` reading
`products.value()` recomputes and an `effect()` watching `products.status()` runs, exactly as
against a real `httpResource`. A plain object with the same keys would satisfy every read and notify
nothing.

| Member                | What it is                                                             |
| --------------------- | ---------------------------------------------------------------------- |
| `set(value)`          | resolve with a value; clears any error                                 |
| `fail(error)`         | fail with an `Error` or a message string                               |
| `loading()`           | put it back in flight                                                  |
| `reload`              | the spied `reload()` — assert the call, nothing is re-issued           |
| `resource`            | the installed double, for asserting on it directly                     |

Undone by `restoreMockedProps()` like every other property patch, so a suite running `setupAutoSpy()`
needs no teardown of its own.

## Asserting a resource

`registerResourceMatchers()` adds three matchers that read the value **and** the status, because
either one alone is misleading.

```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]);
expect(other.products).toHaveResourceError(/503/);
```

The one that earns its place is `toHaveResourceValue`: it **fails a resource that has not resolved
even when its default value matches**. That is precisely the assertion this family exists to stop
passing — `expect(products.value()).toEqual([])` is just as happy against a resource still loading
with its default `[]` as against one that genuinely resolved to nothing. The failure names the
status it was actually in and the flush that is missing.

Duck-typed on `{ status, value, error }` with `error` optional, so `httpResource`, `resource`,
`rxResource` and a `mockResourceProp` double all work. Handed something that is not a resource, each
matcher says so rather than throwing a `TypeError` — the two ways to get there are passing
`products.value()` instead of `products`, and passing a property that was never a resource, and both
are silent otherwise.

## Running one effect on demand

`flushEffects()` asks the scheduler to run everything currently dirty. Sometimes a spec needs one
specific effect to run _now_ — typically because its trigger has been replaced with a static signal,
so it will never become dirty on its own:

```ts
import { mockReadonlyProp, runEffect } from 'vitest-auto-spy/angular';

mockReadonlyProp(component, 'state', signal(State.Selected));

runEffect(component.highlightEffect);

expect(component.icon()).toBe('starFilled');
```

`runEffect` runs the body with the signal values as they stand, cleanup registration intact, without
marking the effect clean — a later flush still behaves normally.

**Do not reach for `vi.mock('@angular/core')` instead**
The instinct is to replace `effect()` with the identity function so the callback becomes something
the spec holds. Under the Angular unit-test builder that is not available: specs are bundled,
`@angular/core` lands in a chunk other chunks already depend on, and substituting it re-enters that
chunk mid-initialisation. The run dies with `Cannot access '__vi_import_N__' before initialization`,
which says nothing about mocking. The same applies to `vi.mock()` with a relative path — once
bundled there is no module boundary left to replace.

It reads Angular's reactive node off the `EffectRef`, so it is tied to an internal-by-convention
detail. If a future Angular moves the effect body, `runEffect` throws with a message saying to assert
the effect's **result** instead — set the signals it reads, `await stable(fixture)`, check what came
out. That is the more durable shape wherever it is practical.

## Asserting a signal

```ts
import { registerSignalMatchers } from 'vitest-auto-spy/angular';

registerSignalMatchers(); // once, in your setup file

expect(component.total).toHaveSignalValue(3);
expect(component.items).toHaveSignalValue([{ id: 1 }]);
```

`expect(component.total).toBeTruthy()` passes for every signal ever created — a signal is a
function. The matcher reads it, deep-compares with the runner's own equality, and rejects anything
that is not a zero-argument getter, so the missing-parentheses mistake fails instead of quietly
passing.

## Signal / readonly property mocking

```ts
import { mockAccessorsProp, mockReadonlyProp, mockReadonlyPropGetter, mockValueProp, restoreMockedProps } from 'vitest-auto-spy/angular';

mockReadonlyProp(service, 'isReady', true); // static value (incl. signals)
mockReadonlyPropGetter(service, 'label', () => 'A'); // dynamic getter
mockValueProp(service, 'retries', 3); // plain writable value
mockAccessorsProp(service, 'theme'); // spied get + set
```

Every helper records the descriptor it overwrote, so a single `restoreMockedProps()` puts them all
back — and each one also returns the undo for _its own_ patch, for a stub that has to come off
inside a single test. That matters when the patched object outlives the spec file (a global, a
class prototype, a singleton), which is always the case under Vitest's `isolate: false`:
[`setupAutoSpy()`](https://asdalexey.github.io/vitest-auto-spy/utilities/setup) wires the `afterEach` for you.

Nothing about these helpers is Angular-specific: they are exported from the **core** entry too, and
`vitest-auto-spy/angular` keeps re-exporting them unchanged. `countMockedProps()` reports how many
patches are still applied.

### Driving a signal

`createSpyFromClass` walks the prototype, and a `signal()` / `computed()` field is not there — it is
assigned on the instance. Listing it in `methodsToSpyOn` does not help either: that makes it a
function spy, and a function spy answers `undefined` until configured, so a component reading
`service.count()` gets nothing where it expects a value.

What a spec wants is the signal real and writable, so the component reacts the way it does in the
application. That is the two-line pair every suite ends up writing — a writable handle for the test,
a readonly one for the service:

```ts
const count = signal(0);
mockReadonlyProp(service, 'count', count);
```

`mockSignalProp` is that pair with the handle returned rather than declared:

```ts
import { mockSignalProp } from 'vitest-auto-spy/angular';

const service = injectSpy(CounterService);
const count = mockSignalProp(service, 'count', 0);

expect(component.label()).toBe('0 items');

count.set(42);
await fixture.whenStable();

expect(component.label()).toBe('42 items');
```

The signal comes from `@angular/core`, so reactivity is genuine: a `computed()` downstream
recomputes, an `effect()` runs, a template binding updates. A stand-in with a `set` method would
satisfy `service.count()` and silently notify nothing — the failure this helper exists to avoid
rather than cause.

Returning the handle also removes the temptation to reach for `service.count` and call `.set` on
it: `Signal<T>` has no `set`, so that only type-checks after an assertion.

## Where a spec spends its time

```ts
// vitest.setup.ts
import { enableTestBedDiagnostics } from 'vitest-auto-spy/angular';

if (process.env['SPEC_TIMING']) {
  enableTestBedDiagnostics();
}
```

```
[vitest-auto-spy] src/app/…/layer-editor.component.spec.ts — TestBed 353ms of 661ms (53%), logic 308ms, 155 component(s), 132 module config(s)
```

One line per spec file: how much of its wall clock went into `TestBed` (module configuration,
template compilation, component creation) versus plain logic, and how many components it created.
That is the list of rewrite candidates, and the number that says whether a rewrite helped.

| Option         | Default           | Notes                                                           |
| -------------- | ----------------- | --------------------------------------------------------------- |
| `report`       | one line per file | Receives the `SpecTiming` object — collect the timings yourself |
| `minTestBedMs` | `0`               | Stay quiet about files cheaper than this                        |

`disableTestBedDiagnostics()` puts the untouched `TestBed` back; `instrumentTestBed()`,
`getTestBedTiming()`, `formatSpecTiming()` and `reportSpecTiming()` are the pieces underneath, for
a suite that wants the numbers without the per-file line. The clock is
captured at import time, so a spec using `vi.useFakeTimers()` is still measured honestly rather
than reported as free, and the report goes to `process.stdout` — not `console.info`, which
[`vitest-auto-spy/console`](https://asdalexey.github.io/vitest-auto-spy/utilities/console) replaces with a silent mock.

## Overriding a provider the component declares for itself

`provideAutoSpy` registers on the testing module, and a testing-module provider **loses** to one the
component declares in its own `@Component({ providers: [...] })` — route-scoped services,
per-component stores, `provideX()` helpers. Nothing reports the loss: the spec configures a spy, the
component keeps the real service, and the assertion fails two steps away from the cause.

How far away is worth spelling out, because this is one of the most-reported traps in the whole
library. `@Component({ providers: [DeleteAccountService] })` with a module-level
`provideAutoSpy(DeleteAccountService)` builds the **real** service, and what fails is whatever that
service touches first — in one observed case a logger, with
`TypeError: Cannot read properties of undefined (reading 'pipe')`. That message names neither the
component, nor the provider, nor the spy.

There are two fixes and the choice is about intent. Use `overrideComponentProvider` when the spec
wants a double at the component level; use `TestBed.overrideComponent(..., { remove: { providers } })`
when the module already provides the spy and the component's own declaration is simply in the way:

```ts
TestBed.overrideComponent(ProfileComponent, { remove: { providers: [DeleteAccountService] } });
```

```ts
import { overrideAutoSpy, overrideComponentProvider } from 'vitest-auto-spy/angular';

// the component is instantiated through a parent's template, so it is not in `imports` yet
const menu = overrideComponentProvider(CatalogPageComponent, NavigationBuilderService); // → Spy<NavigationBuilderService>

// or, when the component is already in the testing module
TestBed.configureTestingModule({ imports: [CheckoutComponent] }).overrideProvider(PaymentMethodService, overrideAutoSpy(PaymentMethodService));
```

`overrideProvider(X, provideAutoSpy(X))` is **not** broken, contrary to what this page used to say.
`provideAutoSpy` returns `{ provide, useValue }`; `overrideProvider` reads `useValue` off it and
ignores the extra `provide`, so the spy is installed. Prefer `overrideAutoSpy` because it says what
it does and hands the spy back directly, not because the other form is a no-op.

The silent failure that is real: `overrideProvider` only reaches a component the TestBed compiler
knows about. A standalone component
instantiated through a parent's template is not in the testing module's `imports`, so the override
never applies to it, and finding that out means knowing how `TestBedCompiler.queueType` works.
`overrideComponentProvider` queues the component — as an import when it is standalone, as a
declaration otherwise.

Do **not** reach for `TestBed.overrideComponent` here. It forces a JIT recompilation, and under an
AOT test bundle that recompilation resolves the component's directives and pipes from a runtime
scope the bundler has stripped, leaving it with none of them — see the next section.

## An NgModule that contributes nothing

Under an AOT test bundle — what `@angular/build:unit-test` produces, and what a Jest suite moving to
the native builder starts getting — `ɵɵsetNgModuleScope` is stripped, because only the TestBed reads
it. Every NgModule then has an empty `ɵmod.declarations` / `ɵmod.exports` at runtime.

Nothing notices while AOT is in charge: the flat dependency list is already baked into each `ɵcmp`.
But the moment the TestBed resolves a scope itself — through `imports: [SomeModule]`, or through a
JIT recompilation after `overrideComponent` — it resolves it from nothing, and reports that in four
different ways, none of which mentions the module:

```
NG0303: Can't bind to 'appTruncate' since it isn't a known property of 'div'
NG0301: Export of name 'focusable' not found!
NG0304: 'ui-smart-row' is not a known element
(nothing at all — an attribute directive simply never instantiates)
```

```ts
import { assertNgModuleScopes } from 'vitest-auto-spy/angular';

assertNgModuleScopes(DirectivesModule, PipesModule);
TestBed.configureTestingModule({ imports: [DirectivesModule, PipesModule] });
```

The error names the module and the cause, and the fix is to declare what the spec needs in the
TestBed module directly. Pass only modules you import **for their declarations** — a providers-only
module is legitimately empty and would be reported as a false positive.

## Focus assertions

```ts
import { registerFocusMatchers } from 'vitest-auto-spy/setup';

registerFocusMatchers(); // once, in the setup file

expect(fixture.nativeElement.querySelector('.play')).toHaveFocus();
```

Focus tests are written in one of two shapes and both report nothing useful.
`expect(document.activeElement).toBe(button)` prints two enormous DOM dumps with no visible
difference; `expect(activeFocus() === getElement(row)).toEqual(value)` collapses the comparison to a
boolean before `expect` ever sees it, and fails with `expected false to deeply equal true` — a
message compatible with every possible cause.

The three causes worth telling apart are: the expected element does not exist at all (by far the most
frequent), focus is still on `<body>` because nothing claimed it, and focus is on a different
element. `toHaveFocus` names which of the three happened and describes both nodes by tag, id and
class rather than by dumping their subtrees.

## `injectSpy` and tokens

`injectSpy` takes an `InjectionToken` as well as a class, which matters in a codebase where half the
dependencies live behind one (`LIST_DATA_PROVIDER_TOKEN`, `ROOT_MEDIA_ELEMENT`).

For a **generic** class, name the type argument. `TestBed.inject` infers `Service<any>` from the
constructor rather than the declared default, and the `any` then surfaces much later as a mismatch
between `AddPromiseSpyMethods<unknown>` and `WithMockReturnValue<…>` — eight levels deep, with
nothing in the message about type parameters:

```ts
const config = injectSpy<FeatureFlagService>(FeatureFlagService);
```

## Zone and zoneless in the same run

```ts
// vitest-setup.ts
import { setupAngularTestEnv } from 'vitest-auto-spy/angular';
import { setupZoneTestEnv, setupZonelessTestEnv } from 'jest-preset-angular/setup-env';

setupAngularTestEnv({
  zoneless: (testPath) => testPath.includes('/libs/catalog/') || testPath.includes('/apps/storefront/'),
  initZone: setupZoneTestEnv,
  initZoneless: setupZonelessTestEnv,
});
```

`TestBed.initTestEnvironment` may be called once per platform, and under `isolate: false` the
platform lives for the whole worker. A repository migrating to zoneless gradually — a few libraries
switched, the rest still on zone.js — therefore cannot express itself in setup files at all: the
second file the worker picks up in the other mode fails with `Cannot set base providers because it
has already been called`, and the message names neither file.

Vitest's own answer, `test.projects`, does not solve it either. Nothing promises that a worker serves
files of one project, and a worker handed a file of the other mode fails exactly the same way.

What works is to decide the mode from the file about to run and, when it differs from the one
installed, tear the environment down before initialising the other. The mode is remembered per
worker, so a run of files in the same mode pays for one initialisation and no resets.

The initialisers stay yours: which platform, which providers and which `teardown` policy a project
wants is not something this library should decide, and the packages that supply them
(`@analogjs/vitest-angular`, `jest-preset-angular`, a hand-written `initTestEnvironment`) are not
dependencies of it.

## A host for a directive under test

```ts
import { createDirectiveHost, registerDirectiveMatchers } from 'vitest-auto-spy/angular';

const Host = createDirectiveHost({
  template: `<div [appTruncate]="enabled" [truncateText]="text"></div>`,
  scope: [DirectivesModule],
  props: { enabled: false, text: 'hello' },
});

TestBed.configureTestingModule({ imports: [Host] });

const fixture = TestBed.createComponent(Host);
fixture.componentInstance.enabled = true; // typed from `props`
```

Under the native builder the two halves of Angular disagree about where `imports` is resolved, and
the same line is alive in one place and dead in the other:

| Where                                   | Resolved by                          | An `NgModule` there                          |
| --------------------------------------- | ------------------------------------ | -------------------------------------------- |
| `@Component({ imports })`               | the AOT compiler, at build time      | **works** — the flat list is baked into `ɵcmp` |
| `TestBed.configureTestingModule({ imports })` | `TestBedCompiler`, at runtime, from `ɵmod` | **contributes nothing** — `ɵɵsetNgModuleScope` is not emitted into a test bundle |

So the host must be **standalone** and must carry the module in its *own* `imports`. A host written
`standalone: false` inside a spec is worse still: it is compiled outside any scope at all, with no
`NgClass`, no `AsyncPipe`, nothing. `createDirectiveHost` is that knowledge applied — the host is
always standalone, `scope` becomes the component's imports, and `props` types
`fixture.componentInstance`.

### `toHaveDirectiveApplied`

```ts
registerDirectiveMatchers(); // once, in the setup file

expect(fixture).toHaveDirectiveApplied(TruncateDirective, 'div');
```

Angular reports a directive that is out of scope in three different wrong ways: `NG0303` sends the
reader to the `@NgModule` where the directive *is* correctly declared; `NG0304` reports an absent
**directive** as an absent **component**; and a directive used as a bare attribute, with no binding,
reports *nothing at all* — a green test asserting on a directive that never ran.

The matcher asserts the fact, and its failure names the cause and the fix, including the one that
looks like a fix and is not: `schemas: [NO_ERRORS_SCHEMA]` applies to a testing module's
`declarations` and never to a standalone component, so next to a standalone component it is a dead
entry that reads as if something were deliberately silenced.

## Patching a property of a spy

```ts
const playback = injectSpy(PlaybackStateService);

mockSignalProp(playback, 'navigationState', 'idle'); // a real, writable signal
mockReadonlyProp(playback, 'currentItem', signal(item));
```

The `mock*Prop` helpers accept the `Spy<T>` that `injectSpy` / `asSpy` returns, and check the value
against the member's **own** type rather than the spy-decorated one. Without that, a signal-valued
member on a spy is typed `Signal<T> & Mock & …`, no real signal can be written into it, and the spec
has to keep the instance under a second name purely to patch it.

For a signal-valued getter prefer `mockSignalProp` over `gettersToSpyOn`: a spied getter returns
`undefined` until it is configured, while a real signal keeps every `computed()` and `effect()`
downstream of it reactive.

## A dependency behind an `InjectionToken`

```ts
TestBed.configureTestingModule({ providers: [provideAutoSpyForToken(PASSCODE_SERVICE_TOKEN)] });

const passcode = injectSpy(PASSCODE_SERVICE_TOKEN); // Spy<PasscodeService>
```

A token typed with an *interface* has no class to read, which is where the usual workaround comes
from: a `PasscodeServiceMock` written in the spec, spied, and provided — after which `Spy<Mock>` and
`Spy<PasscodeService>` disagree about `calledWith` and somebody reaches for an assertion (or, more
often, `TestBed.inject<any>(TOKEN)` with an `eslint-disable` at the top of the file).
`provideAutoSpyForToken` reads the type off the token; `injectSpy` already accepts one. Note the
name: `provideAutoSpy` reads a *class prototype*, which a token has none of, so it is not the call
that works here.

The second argument is needed more often than it looks. A spy answers `undefined` until it is told
otherwise, which is fatal the moment the code under test **chains** off it: a constructor doing
`inject(LOGGER).channel('auth').debug('…')` dies on the `.debug` of `undefined` before the spec's
first line runs, because nothing in production wrote `?.` there. Seed the link that returns the
object:

```ts
provideAutoSpyForToken(LOGGER, { channel: vi.fn().mockReturnThis() });
```

For a chain more than one link long, [`mockDeep<T>()`](https://asdalexey.github.io/vitest-auto-spy/core/auto-mock-by-type#recursive-deep-mocks-%E2%80%94-mockdeep) is the double that answers
at every level.

## `injectSpy` says when it got the real thing

```text
[vitest-auto-spy] injectSpy(DeviceRegistryService): the injector returned a plain instance, not an
auto-spy. Register it with provideAutoSpy(DeviceRegistryService) …
```

A provider the spec forgot to register is otherwise found much later — when `.mockReturnValue(…)` is
called on the real method, or, if the class has no private members to make the types disagree, never.
The warning is printed once per token.

---

Source: https://asdalexey.github.io/vitest-auto-spy/adapters/nestjs

# NestJS

The `vitest-auto-spy/nestjs` entry ships a `{ provide, useValue }` provider tailored for
`Test.createTestingModule({ providers: [...] })`, plus a typed `injectSpy` that pulls a spy out of
the resulting `TestingModule`.

```ts
import { provideAutoSpy, injectSpy } from 'vitest-auto-spy/nestjs';

const moduleRef = await Test.createTestingModule({
  providers: [
    provideAutoSpy(MyService),
    provideAutoSpy(ApiService, { onlyMethodsToSpyOn: ['get', 'post'] }),
  ],
}).compile();

const myService = injectSpy(moduleRef, MyService);
```

Dependency-free by design: `@nestjs/common` / `@nestjs/testing` are optional peers, so the entry
describes the module reference with a minimal structural type instead of importing them.

**`injectSpy` takes two arguments here**
Angular's `injectSpy(token)` reads from the global `TestBed`. NestJS has no global module, so the
NestJS variant is **`injectSpy(moduleRef, token)`** — the module reference comes first.

## A full spec

```ts
import { Test, type TestingModule } from '@nestjs/testing';
import { beforeEach, describe, expect, it } from 'vitest';
import { type Spy } from 'vitest-auto-spy';
import { injectSpy, provideAutoSpy } from 'vitest-auto-spy/nestjs';

import { AuthService } from './auth.service';
import { UserService } from './user.service';

describe('AuthService', () => {
  let moduleRef: TestingModule;
  let auth: AuthService;
  let users: Spy<UserService>;

  beforeEach(async () => {
    moduleRef = await Test.createTestingModule({
      providers: [AuthService, provideAutoSpy(UserService)],
    }).compile();

    auth = moduleRef.get(AuthService);
    users = injectSpy(moduleRef, UserService);
  });

  it('signs in a known user', async () => {
    users.findByEmail.calledWith('ada@example.com').resolveWith({ id: 1, name: 'Ada' });

    await expect(auth.signIn('ada@example.com')).resolves.toMatchObject({ id: 1 });
    expect(users.findByEmail).toHaveBeenCalledWith('ada@example.com');
  });

  it('rejects an unknown one', async () => {
    users.findByEmail.resolveWith(null);

    await expect(auth.signIn('nobody@example.com')).rejects.toThrow('Unknown user');
  });
});
```

`AuthService` itself is provided **for real** — it is the class under test. Everything it injects is
provided as an auto-spy.

## Abstract classes and interface tokens

Nest often injects against an abstract class or a string/symbol token. `provideAutoSpy` needs a
constructor to read methods from, so give it the concrete class and re-point the token:

```ts
// abstract class as the token, concrete class as the shape
providers: [{ provide: PaymentGateway, useValue: provideAutoSpy(StripeGateway).useValue }];

// a string/symbol token
providers: [{ provide: 'PAYMENT_GATEWAY', useValue: provideAutoSpy(StripeGateway).useValue }];
```

Then read it back the way Nest resolves it:

```ts
const gateway = injectSpy(moduleRef, PaymentGateway);
```

When there is no class at all — a pure interface — use
[`createAutoMock<PaymentGateway>()`](https://asdalexey.github.io/vitest-auto-spy/core/auto-mock-by-type) as the `useValue` instead; it builds
the same spy surface from the type.

## Why there is no `@nestjs` dependency

`@nestjs/common` and `@nestjs/testing` stay **your** dev dependencies. The entry describes the module
reference with a minimal structural type (`NestModuleRef` — anything with a `get(token)`), so
nothing from Nest reaches this package's runtime bundle, and `injectSpy` also works against a hand-
rolled fake in a unit test.

---

Source: https://asdalexey.github.io/vitest-auto-spy/adapters/react

# React

React has no DI container, so `vitest-auto-spy/react` ships **no** `provide*` helper — it is a
*recipe*: spy the **classes** you own (services, stores, API clients, the deps you inject into
hooks or hand to a Context provider), not the components themselves.

```ts
import { createSpyFromClass, type Spy } from 'vitest-auto-spy/react';
```

The spy is a plain object of mocks, so you pass it straight into a `<Context.Provider value={spy}>`
or a hook's dependency argument, then drive return values with `calledWith` / `resolveWith` /
`mockReturnValue` and assert against `spy.method.mock.calls`.

Importing this entry registers the default Vitest mock adapter and re-exports the same public API
as the core. It pulls in `vitest` only — never `react` or `@testing-library/react`, which stay your
own dev dependencies.

## Through a Context provider

The spy is a plain object of mocks, so it goes straight into a provider's `value`:

```tsx
import { render, screen } from '@testing-library/react';
import { beforeEach, describe, expect, it } from 'vitest';
import { type Spy, createSpyFromClass } from 'vitest-auto-spy/react';

import { Cart, CartContext } from './cart';
import { CartStore } from './cart-store';

describe('<Cart />', () => {
  let cart: Spy<CartStore>;

  beforeEach(() => {
    cart = createSpyFromClass(CartStore);
  });

  it('renders the total the store reports', () => {
    cart.total.mockReturnValue(42);

    render(
      <CartContext.Provider value={cart}>
        <Cart />
      </CartContext.Provider>,
    );

    expect(screen.getByText('$42')).toBeInTheDocument();
  });

  it('checks out with the items on screen', async () => {
    cart.checkout.resolveWith({ orderId: 'ord_42' });

    render(
      <CartContext.Provider value={cart}>
        <Cart />
      </CartContext.Provider>,
    );

    await userEvent.click(screen.getByRole('button', { name: 'Check out' }));

    expect(cart.checkout).toHaveBeenCalledWith('tok_abc');
  });
});
```

`Spy<CartStore>` is a mapped type and drops `#private` members, so it is not assignable to
`CartStore`. If the context is typed as the class, bridge it with
[`asInstance(cart)`](https://asdalexey.github.io/vitest-auto-spy/core/spy-typing) rather than an `as`.

## As a hook dependency

A hook that takes its collaborator as an argument is the easiest thing in a React codebase to test,
and the spy needs no wrapper at all:

```ts
import { renderHook, waitFor } from '@testing-library/react';
import { expect, it } from 'vitest';
import { createSpyFromClass } from 'vitest-auto-spy/react';

import { UserApi } from './user-api';
import { useUser } from './use-user';

it('exposes the loaded user', async () => {
  const api = createSpyFromClass(UserApi);

  api.fetchUser.calledWith(1).resolveWith({ id: 1, name: 'Ada' });

  const { result } = renderHook(() => useUser(1, api));

  await waitFor(() => expect(result.current.user?.name).toBe('Ada'));
  expect(api.fetchUser).toHaveBeenCalledTimes(1);
});
```

**What not to spy**
Spy the classes you own, not components or hooks. A spied component tells you nothing about
rendering, and a spied hook makes the test assert its own mock. Keep the boundary at the
service/store/API-client seam.

---

Source: https://asdalexey.github.io/vitest-auto-spy/adapters/vue

# Vue / Pinia

The `vitest-auto-spy/vue` entry re-exports the full core (zero-config on Vitest) and adds a small
`provideAutoSpy(token, Class)` that builds a `global.provide` entry for `@vue/test-utils`. Nothing
here imports `vue`, `pinia` or `@vue/test-utils` — they stay optional peers.

Class-based services injected via `provide`/`inject` and class-based Pinia stores are the natural
fit:

```ts
import { createSpyFromClass, provideAutoSpy } from 'vitest-auto-spy/vue';

// Spy a Pinia store's actions
const store = createSpyFromClass(CartStore);
store.checkout.resolveWith({ ok: true });

// Provide a spied service to a mounted component
const provide = provideAutoSpy(UserServiceKey, UserService);
provide[UserServiceKey].getName.mockReturnValue('Fake Name');
```

## A full `mount` example

`provideAutoSpy(token, Class, methodsOrConfig?)` returns a **`global.provide` map** —
`{ [token]: Spy<T> }` — so it spreads straight into `@vue/test-utils`:

```ts
import { mount } from '@vue/test-utils';
import { expect, it } from 'vitest';
import { provideAutoSpy } from 'vitest-auto-spy/vue';

import Greeting from './Greeting.vue';
import { UserService, UserServiceKey } from './user.service';

it('renders the name the service returns', () => {
  const provide = provideAutoSpy(UserServiceKey, UserService);

  provide[UserServiceKey].getName.calledWith(1).mockReturnValue('Ada');

  const wrapper = mount(Greeting, {
    props: { userId: 1 },
    global: { provide },
  });

  expect(wrapper.text()).toContain('Ada');
  expect(provide[UserServiceKey].getName).toHaveBeenCalledWith(1);
});
```

Providing more than one collaborator is a merge of the maps:

```ts
const provide = {
  ...provideAutoSpy(UserServiceKey, UserService),
  ...provideAutoSpy(CartKey, CartStore, { onlyMethodsToSpyOn: ['total', 'checkout'] }),
};
```

The token can be a plain string, a `symbol`, or a typed `InjectionKey<T>` (which is a branded
`symbol`) — the returned map is keyed by exactly the token you passed.

## A class-based Pinia store

A store written as a class is just a class, so `createSpyFromClass` spies every action and getter:

```ts
import { expect, it } from 'vitest';
import { type Spy, createSpyFromClass } from 'vitest-auto-spy/vue';

import { CartStore } from './cart.store';

it('drives the store the component talks to', async () => {
  const cart: Spy<CartStore> = createSpyFromClass(CartStore);

  cart.itemCount.mockReturnValue(3); // a getter-style action
  cart.checkout.resolveWith({ orderId: 'ord_42' }); // an async action

  expect(cart.itemCount()).toBe(3);
  await expect(cart.checkout('tok_abc')).resolves.toEqual({ orderId: 'ord_42' });
  expect(cart.checkout).toHaveBeenCalledWith('tok_abc');
});
```

Every action is inert until you configure it — `cart.addItem('sku', 1)` records the call and returns
`undefined`, so no real store logic runs.

**Setup-store (composition API) stores**
`defineStore('cart', () => …)` returns a plain object of refs and functions, not a class. Use
[`createAutoMock<T>()`](https://asdalexey.github.io/vitest-auto-spy/core/auto-mock-by-type) there — it mocks from the store's **type** with the
same helpers, no class required.

---

Source: https://asdalexey.github.io/vitest-auto-spy/adapters/svelte

# Svelte

Svelte has no class-based dependency injection, so `vitest-auto-spy/svelte` adds **no** helper of
its own — it is a recipe, not a framework integration. Svelte apps typically keep their logic in
plain class-based services or stores; `createSpyFromClass` spies that class, and you inject the spy
into the component under test (props, context, or a mocked module) exactly the way the component
receives the real one.

```ts
import { createSpyFromClass } from 'vitest-auto-spy/svelte';
import { render } from '@testing-library/svelte';
import Cart from './Cart.svelte';
import { CartStore } from './cart-store';

const cartStore = createSpyFromClass(CartStore);
cartStore.total.mockReturnValue(42);

render(Cart, { props: { store: cartStore } });
```

Importing this entry registers the default Vitest mock adapter and re-exports the whole core, so a
Svelte suite needs a single import. It pulls in neither `svelte` nor `@testing-library/svelte`.

## Through context

When the component reads its collaborator from `getContext`, seed the same key with the spy:

```ts
import { render, screen } from '@testing-library/svelte';
import { expect, it } from 'vitest';
import { createSpyFromClass } from 'vitest-auto-spy/svelte';

import Cart from './Cart.svelte';
import { CART_STORE, CartStore } from './cart-store';

it('renders the total the store reports', () => {
  const cartStore = createSpyFromClass(CartStore);

  cartStore.total.mockReturnValue(42);

  render(Cart, { context: new Map([[CART_STORE, cartStore]]) });

  expect(screen.getByText('$42')).toBeInTheDocument();
});
```

## Through a mocked module

When the component imports a singleton directly, replace the module — the spy is what the factory
returns:

```ts
import { render } from '@testing-library/svelte';
import { expect, it, vi } from 'vitest';
import { createSpyFromClass } from 'vitest-auto-spy/svelte';

import { CartStore } from './cart-store';

const cartStore = vi.hoisted(() => createSpyFromClass(CartStore));

vi.mock('./cart-store', async (importOriginal) => ({
  ...(await importOriginal<typeof import('./cart-store')>()),
  cartStore,
}));

it('checks out through the module singleton', async () => {
  cartStore.checkout.resolveWith({ orderId: 'ord_42' });

  render(await import('./Cart.svelte').then((m) => m.default));

  expect(cartStore.checkout).toHaveBeenCalled();
});
```

**`vi.mock` needs a module boundary**
A `vi.mock` factory is hoisted above the file's own imports, so it must not close over anything
declared at module scope — `vi.hoisted` is what makes the spy available to it. And in setups that
bundle the spec (Angular's `@angular/build:unit-test` builder, for instance) a relative path has no
module boundary left to replace; inject the spy through props or context there instead.

---

Source: https://asdalexey.github.io/vitest-auto-spy/migrating

# Migrating from jest-auto-spies

The public API is intentionally identical to
[`jest-auto-spies`](https://www.npmjs.com/package/jest-auto-spies). In most projects the migration
is a **find-and-replace of the import**:

```diff
- import { createSpyFromClass, provideAutoSpy } from 'jest-auto-spies';
+ import { createSpyFromClass } from 'vitest-auto-spy';
+ import { provideAutoSpy } from 'vitest-auto-spy/angular';
+ import 'vitest-auto-spy/rxjs'; // once, if you use observable spies
```

The only API-shape change is that the Angular helpers and the observable layer live behind the
`/angular` and `/rxjs` subpaths (see [Installation → Entry points](https://asdalexey.github.io/vitest-auto-spy/core/installation)).

## Mapping table

This also covers migrating from
[`@bugsplat/vitest-auto-spies`](https://www.npmjs.com/package/@bugsplat/vitest-auto-spies) —
it re-exports the same `jest-auto-spies` API, so the swap is identical (and you gain Bun /
`node:test`, `createAutoMock`, framework recipes and console spies on top).

| jest-auto-spies                                                       | vitest-auto-spy                                            | Status       |
| --------------------------------------------------------------------- | ---------------------------------------------------------- | ------------ |
| `createSpyFromClass`                                                  | `createSpyFromClass`                                       | ✅ identical |
| `methodsToSpyOn`                                                      | `methodsToSpyOn` — additive there and additive here        | ✅ identical |
| `provideAutoSpy`                                                      | `provideAutoSpy` (from `/angular`)                         | ✅ identical |
| `calledWith` / `mustBeCalledWith`                                     | same                                                       | ✅ identical |
| `calledWith(...).returnValue(v)`                                      | same — `.returnValue` **and** `.mockReturnValue` both work | ✅ identical |
| `resolveWith` / `rejectWith` / `resolveWithPerCall`                   | same                                                       | ✅ identical |
| `nextWith` / `nextOneTimeWith` / `nextWithValues` / `nextWithPerCall` | same                                                       | ✅ identical |
| `throwWith` / `complete` / `returnSubject`                            | same                                                       | ✅ identical |
| `accessorSpies.getters/setters`                                       | same                                                       | ✅ identical |
| `createObservableWithValues`                                          | same (from `/rxjs`)                                        | ✅ identical |
| underlying mock                                                       | `jest.fn()` → `vi.fn()`                                    | 🔁 swapped   |

Just make sure your tests run under Vitest (or Bun / `node:test` via the matching entry), and — for
Angular — that `TestBed` is set up.

### Reading a spy back out of the container

`Spy<T>` is stricter here than it was in `jest-auto-spies`, so the cast a migrated suite is full of
stops compiling:

```ts
// jest-auto-spies
devicesService = TestBed.inject(DeviceListService) as Spy<DeviceListService>;
// TS2352: Conversion of type 'DeviceListService' to type 'Spy<DeviceListService>'
//         may be a mistake because neither type sufficiently overlaps with the other.

// vitest-auto-spy
devicesService = asSpy(TestBed.inject(DeviceListService));
```

`asSpy` is a typed identity — it asserts what `provideAutoSpy` already put in the container, without
the cast. `injectSpy(DeviceListService)` is the same thing with the `TestBed.inject` folded in. This is
the most common compile error a migrated Angular suite produces, and it produces one per injected
double, so it is worth a global search before the first run.

Or leave the search to [`prefer-as-spy`](https://asdalexey.github.io/vitest-auto-spy/utilities/eslint-plugin), which reports every one of those
casts and rewrites them under `--fix`, import and all.

### The type names

`vi` is a global, so the only thing a migrated spec imports from `vitest` is types. Three of the four
renames are plain, and the fourth quietly means the opposite of what it did:

| Jest                  | Vitest              | Import                                         |
| --------------------- | ------------------- | ---------------------------------------------- |
| `jest.Mocked<T>`      | `Mocked<T>`         | `import type { Mocked } from 'vitest'`         |
| `jest.MockedFunction` | `MockedFunction`    | `import type { MockedFunction } from 'vitest'` |
| `jest.SpyInstance`    | `MockInstance`      | `import type { MockInstance } from 'vitest'`   |
| `jest.Mock<R, [A]>`   | `Mock<(a: A) => R>` | `import type { Mock } from 'vitest'`           |

**`jest.Mock` reorders its own generics**
Jest writes the **return type first and the arguments second**; Vitest's `Mock` takes a single call
signature. A rename that leaves the arguments where they were compiles cleanly into a type meaning
the reverse, and nothing fails until a call site disagrees with it:

```ts
// jest — returns void, takes one AdjustedSubscriptionDetails
let callBack: jest.Mock<void, [AdjustedSubscriptionDetails]>;

// vitest — the same intent, written as the call signature
let callBack: Mock<(details: AdjustedSubscriptionDetails) => void>;
```

The bare `jest.Mock` with no generics is the safe case: `Mock` on its own means the same thing.

For anything this library produced, declare `Spy<T>` rather than `Mocked<T>` —
[`no-mocked-for-spy`](https://asdalexey.github.io/vitest-auto-spy/utilities/eslint-plugin) explains why, and is one of the two rules that fix
themselves.

Put the `vitest` type import in the external-packages group with everything else. Placing it above
the framework imports is tempting, because it is the only line in the file that is not really a
dependency — and `eslint-plugin-import` then has an opinion about every spec in the suite:

```
error  There should be at least one empty line between import groups        import/order
error  `vitest` type import should occur after import of `@angular/router`  import/order
```

### The `jest.*` calls that have no `vi.*` twin

A mechanical `jest.` → `vi.` rename produces calls that do not exist, and the resulting
`TypeError: vi.requireMock is not a function` reads as "the runner broke". These are the ones worth
knowing before the rename, because for each of them the honest answer is a different design, not a
different name.

| Jest                                                    | Vitest                | What to do instead                                                                                         |
| ------------------------------------------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------- |
| `jest.requireMock(id)`                                  | **none**              | provide the double through the TestBed / the container, or pass it as an argument                          |
| `jest.requireActual(id)`                                | `vi.importActual(id)` | `await`ed, and only inside a `vi.mock` factory                                                             |
| `jest.fn().mockImplementation(() => o)` used with `new` | **not constructible** | [`mockConstructor` / `stubConstructor`](https://asdalexey.github.io/vitest-auto-spy/utilities/constructor-doubles)                                    |
| `jest.spyOn(global, 'Date')`                            | **throws**            | `mockSystemTime(iso)` — fake timers already own `Date`                                                     |
| `jest.replaceProperty(obj, key, value)`                 | **none**              | `mockValueProp(obj, key, value)` — and it restores itself                                                  |
| `fakeTimers: { enableGlobally: true }`                  | **no setting**        | `setupAutoSpy({ globalFakeTimers: true })`                                                                 |
| `jest.mock('some-barrel')`                              | `vi.mock(…)`          | a **silent no-op** once the specs are bundled — the module boundary it would replace no longer exists      |
| `jest.spyOn(barrel, 'exported')`                        | **throws**            | `TypeError: Cannot redefine property` — a bundled export is not configurable; same answer as the row above |
| `jest.fn().mockImplementation()` with no argument       | **requires one**      | `mockImplementation(() => undefined)` — Jest installed the no-op for you                                   |
| `xit` / `xdescribe`                                     | **none**              | `it.skip` / `describe.skip`; the rename fails as `TS2304: Cannot find name 'xit'`                          |

That last row is the one that costs the most, because nothing reports it. Under a bundling test
builder — and under `isolate: false`, where the module may already be in the worker's graph — a
`vi.mock()` of a workspace barrel, of `@angular/core`, or of a relative path either does nothing or
does something only on some runs. If a mock "works in a narrow run and not in a wide one", this is
why: replace the mock with a real seam (a provider, an argument, `vi.hoisted()` for a package that
genuinely must be replaced).

**Restricting is a separate option**
Up to v1 this library read `methodsToSpyOn` as an exhaustive whitelist, which is the opposite of
`jest-auto-spies` and the one thing that made the swap not a swap: a migrated spec listing a couple
of names silently lost every other method, and the failure surfaced as `… is not a function` inside
a constructor, with nothing in the stack pointing at the spec. Since v2 the option is additive, and
the whitelist lives under its own name, `onlyMethodsToSpyOn`.

## Step by step

1. **Install and remove.**

   ```bash
   npm i -D vitest-auto-spy
   npm rm jest-auto-spies   # or @bugsplat/vitest-auto-spies
   ```

2. **Rewrite the imports.** The core keeps its name; the Angular helpers and the observable layer
   moved behind subpaths.

   ```diff
   - import { createSpyFromClass, provideAutoSpy } from 'jest-auto-spies';
   + import { createSpyFromClass } from 'vitest-auto-spy';
   + import { provideAutoSpy } from 'vitest-auto-spy/angular';
   ```

3. **Add the rxjs import once** — in the setup file, not per spec — if any spy uses `nextWith`,
   `nextWithValues` or `observablePropsToSpyOn`:

   ```ts
   // vitest.setup.ts
   import 'vitest-auto-spy/rxjs';
   ```

   Skipping this does not fail silently: the first observable helper throws a message naming this
   exact import.

4. **Pick the entry that matches your runner.** `vitest-auto-spy` registers Vitest's adapter,
   `/bun` registers `bun:test`'s, `/node` registers `node:test`'s. One per run.

5. **Type the variables as `Spy<T>`.** If a spec declared `let service: MyService = createSpyFromClass(...)`,
   it will now fail to compile when the class has `#private` or `private` members — `Spy<T>` is a
   mapped type and drops them. `let service: Spy<MyService>` is the fix, or
   [`asInstance` / `asSpy`](https://asdalexey.github.io/vitest-auto-spy/core/spy-typing) where the spy must be handed to something typed as the
   class.

6. **Run the suite.** Nothing else in the API changed, so what fails now is real.

7. **Optional, but worth it once green:**
   [`setupAutoSpy()`](https://asdalexey.github.io/vitest-auto-spy/utilities/setup) in the setup file, and the
   [ESLint rules](https://asdalexey.github.io/vitest-auto-spy/utilities/eslint-plugin) that steer the suite onto the newer helpers.

## Per-runner gotchas

**Vitest.** Nothing beyond the import swap. If the suite runs with `isolate: false` or a shared
environment, add `setupAutoSpy()` — Jest isolated every file, and a `mock*Prop` patch that was
harmless there now outlives its spec.

**`vi.fn(() => x)` is not `mockReturnValue(x)`.** The one rename in a migration that looks safest
and is not equivalent. A factory reads `x` when the double is **called**; `mockReturnValue` freezes
the value `x` had when the double was **configured**. Nothing tells them apart until the test
reassigns `x` — and the commonest reason to do that is a fresh `Subject` after the previous one was
`error()`ed or completed, which is precisely what a suite is exercising when it reassigns:

```ts
let source$ = new Subject<Page>();

const api = createSpyFromClass(Api);

api.load.mockReturnValue(source$); // ❌ pinned to the subject that existed on this line
api.load.mockImplementation(() => source$); // ✅ re-read on every call

source$.error(new Error('boom'));
source$ = new Subject<Page>(); // the double still hands out the dead one, above
```

In one spec that meant the service received a completed subject and silently skipped the modal it
was meant to show, with the test green throughout. Carry `vi.fn(() => x)` over as
`mockImplementation(() => x)` and keep `mockReturnValue` for a literal — and if you are writing a
codemod, this is the rewrite to special-case.

**Bun (`bun:test`).** `mockReset()` on Bun also drops the implementation (Vitest keeps the spy) —
the adapter restores it, so auto-spies are unaffected, but a hand-rolled `mock()` in the same spec
will behave differently. `spyOn` refuses accessor properties on Bun; the accessor spies here go
through property redefinition and work anyway. Angular suites need
[`vitest-auto-spy/bun-angular`](https://asdalexey.github.io/vitest-auto-spy/runtimes/bun-angular).

**`node:test`.** There is no `expect` — pair it with `node:assert`. And `spy.method.mockReturnValue`
is a _native_ Vitest/Bun method that `node:test` does not have; the normalised
`spy.method.calledWith(...).mockReturnValue(...)` works everywhere. Recorded calls read as
`mock.calls[0].arguments`, not `mock.calls[0]`. See [node:test](https://asdalexey.github.io/vitest-auto-spy/runtimes/node).

**Angular.** `provideAutoSpy` defaults to **lazy** spies here (`jest-auto-spies` was always eager).
Behaviour is identical; if you depend on every spy existing before first access, pass
`{ lazySpies: false }`.

## What you gain by moving

Beyond the runner swap, everything the old API did not have:
[`createAutoMock` / `mockDeep` / `createMock`](https://asdalexey.github.io/vitest-auto-spy/core/auto-mock-by-type),
[`renderShallow` and `createWithAutoSpies`](https://asdalexey.github.io/vitest-auto-spy/adapters/angular),
[observable assertions](https://asdalexey.github.io/vitest-auto-spy/core/observable-assertions),
[fake timers that settle](https://asdalexey.github.io/vitest-auto-spy/utilities/fake-timers),
[console spies](https://asdalexey.github.io/vitest-auto-spy/utilities/console), [five ESLint rules](https://asdalexey.github.io/vitest-auto-spy/utilities/eslint-plugin),
Bun and `node:test` support — and [Angular's `TestBed` under `bun test`](https://asdalexey.github.io/vitest-auto-spy/runtimes/bun-angular).

## Did the migration lose a test?

```ts
import { compareTestRuns, formatTestRunComparison } from 'vitest-auto-spy';

const diff = compareTestRuns(JSON.parse(before), JSON.parse(after), '/my-repo/');

expect(diff.missing).toEqual([]);
process.stdout.write(formatTestRunComparison(diff));
```

Counters do not answer this. Under `isolate: false` a file can lose a whole suite — an exported spec
file imported by its neighbour loses its own `describe` — and, in the same run, a flaky test
elsewhere can start passing. The totals match, the run looks identical, and a suite is silently gone.

The question is about **which** tests ran, so the answer is the symmetric difference of two sets of
`file::full name`. Both runners write the same JSON shape (`--reporter=json`), so the baseline may
come from Jest and the current run from Vitest; the optional third argument cuts everything above a
shared path root, so a report from CI compares against one from a laptop.

A renamed test appears in both `missing` and `added` — which is the honest answer, since from the
outside a rename and a delete-plus-add are the same event.

**What this actually caught**
On the migration this comes from, the comparison after seven agents' worth of edits showed exactly
one test gone — it asserted on a config key that had been deleted six months earlier in an unrelated
commit — and nothing else lost silently. That is the only way that sentence could have been said.

## A codemod that edits globs is verified by matching, not by diffing

The natural check on a codemod is "did the file change the way I meant?". For a codemod that rewrites
**globs** that check passes while the result is broken, because an empty `include` is a legal
`tsconfig.json` and TypeScript says nothing about it.

This is not hypothetical. A migration codemod removing `jest.config.ts` from `include` used a greedy
pattern that also ate `/**/*`, so `src/**/*.spec.ts` became `src*.spec.ts` — syntactically valid, and
matching no file. Of 152 spec tsconfigs, **nine** still covered their specs. Nothing failed:
`tsc --noEmit` reported zero errors because there was nothing to check, and the only person who found
out was one who opened a spec in an editor and saw `Cannot find name 'vi'`.

So the check is: **does the resulting pattern match at least one file that exists?** And print the
resulting `include` in full rather than a count — "fixed: 152" hides the case where the replacement
produced two different wrong shapes, which is what happened on the first attempt at the repair.

---

Source: https://asdalexey.github.io/vitest-auto-spy/api

# API reference

The exported surface of `vitest-auto-spy` and its subpaths.

| Export                                                                                                       | Description                                                                                                                           |
| ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| `createSpyFromClass(Class, methodsOrConfig?)`                                                                | Build a fully-typed `Spy<T>` from a class                                                                                             |
| `createAutoMock<T>(overrides?)`                                                                              | Build a `Spy<T>` from a **type/interface** alone (Proxy, no class)                                                                    |
| `createMock<T>(partial?)`                                                                                    | Build a plain, spy-free `T` from the fields a test seeds — for data shapes, not collaborators                                         |
| `mockDeep<T>(overrides?, options?)`                                                                          | Recursive `DeepMockProxy<T>` — nested **access** auto-creates chainable spies; `{ selfReturning: true }` chains through **calls** too |
| `clearAutoSpy(spy)` / `resetAutoSpy(spy)`                                                                    | Clear calls (keep config) / full reset of every spy inside an assembled spy                                                           |
| `provideAutoSpy(Class, methodsOrConfig?)`                                                                    | Angular `{ provide, useValue }` shorthand (`/angular`), abstract classes included; NestJS / Vue variants in their subpaths            |
| `injectSpy(token)`                                                                                           | `TestBed.inject` typed as `Spy<T>` (`/angular`); NestJS variant takes `(moduleRef, token)`                                            |
| `createFunctionSpy(name)`                                                                                    | A single standalone function spy with all helpers                                                                                     |
| `createObservableWithValues(configs, opts?)`                                                                 | Build an Observable from value configs (`/rxjs`)                                                                                      |
| `mockReadonlyProp` / `mockReadonlyPropGetter` / `mockValueProp` / `mockAccessorsProp`                        | Mock readonly / writable / accessor / signal props (core, also re-exported from `/angular`)                                           |
| `restoreMockedProps()` / `countMockedProps()`                                                                | Undo every `mock*Prop` patch / how many are still applied                                                                             |
| `expectEmission(source$, opts?)` / `expectEmissions(source$, n, opts?)` / `expectNoEmission(source$, opts?)` | Assert an Observable without a `subscribe` callback that may never run; the emitted type is inferred                                  |
| `expectCompletion(source$, opts?)`                                                                           | Assert that a stream **terminates** — the `Observable<void>` case `firstValueFrom` rejects with `EmptyError`                          |
| `setEmissionTimeout(ms)`                                                                                     | Change the process-wide default wait of the emission helpers; for a suite under global fake timers                                    |
| `asInstance(spy)` / `asSpy(instance)`                                                                        | The two named views between `Spy<T>` and `T`, instead of `as any`                                                                     |
| `createSpyClass(Class, config?)`                                                                             | A spy that can be called with `new`; records `calls` and `instances`                                                                  |
| `setupAutoSpy(opts?)`                                                                                        | Property restore, duplicate-copy detection, stray timers and rejections, mock-registry hygiene — one call (`/setup`)                  |
| `setupFakeTimers(config?, opts?)` / `advanceTimers(ms?)`                                                     | Paired fake-timer install/restore, and an advance that settles queued microtasks (`/setup`)                                           |
| `stubIntersectionObserver()` / `stubResizeObserver()` / `stubMutationObserver()` / `stubObserver(name)`      | Replace an observer global with one the spec drives; restored by `restoreMockedProps()`                                               |
| `intersectionEntry(target, isIntersecting, overrides?)`                                                      | Build one `IntersectionObserverEntry` without the fields nothing reads                                                                |
| `mockResourceProp(object, prop, initial)`                                                     | Replace a resource-valued property with a double the spec drives — `set` / `fail` / `loading` / spied `reload` (`/angular`)             |
| `mockSignalProp(object, prop, initial)`                                                                      | Replace a signal-valued property with a real writable signal, and hand back the handle (`/angular`)                                   |
| `blockNetwork(options?)`                                                                                     | Close `fetch`, XHR and `sendBeacon`, naming what was requested (`/setup`)                                                             |
| `trackStrayRejections()` / `countStrayRejections()` / `flushStrayRejections()`                               | Read back the promise rejections zone.js swallowed into `console.error` (`/setup`)                                                    |
| `trackMockRegistry()` / `keepMockRegistered(mock)` / `pruneMockRegistry()`                                   | Keep `@vitest/spy`'s ever-growing mock registry to the mocks that outlive a file (`/setup`)                                           |
| `guardGlobalPatches(reaction)`                                                                               | Name the test that redefined a global property as non-configurable (`/setup`)                                                         |
| `installPerTest(install)`                                                                                    | Re-install a stub before every test of the block, and read back the current handle (`/setup`)                                         |
| `stubMediaElement(opts?)`                                                                                    | A `<video>` / `<audio>` that plays, reports a duration and fires the media events                                                     |
| `assertMocked(namespace, opts?)`                                                                             | Fail when the `vi.mock()` this spec relies on silently did not apply                                                                  |
| `moduleNamespace(exports, opts?)`                                                                            | The `vi.mock` factory result an interop probe recognises (`default` + `__esModule`)                                                   |
| `flushEventLoopUntil(isDone, opts?)`                                                                         | Real event-loop turns until a condition holds, with a budget instead of a hang                                                        |
| `diffByField(actual, expected)`                                                                              | Which field of an array of records moved, in how many elements — the diff the reporter collapses                                      |
| `setupAngularTestEnv(opts?)`                                                                                 | Zone and zoneless spec files in one worker, switching platforms per file (`/angular`)                                                 |
| `provideAutoSpyForToken(token, overrides?)`                                                                  | `{ provide, useValue }` for an `InjectionToken`, with the spy built from the token's type (`/angular`)                                |
| `createDirectiveHost(opts)`                                                                                  | A standalone host for a directive under test, with its scope where the compiler reads it (`/angular`)                                 |
| `registerDirectiveMatchers()`                                                                                | Adds `expect(fixture).toHaveDirectiveApplied(Directive, selector?)` (`/angular`)                                                      |
| `asInstances(...spies)`                                                                                      | `asInstance` for a whole argument list, in one edit against one compiler error                                                        |
| `captureArg<T>()`                                                                            | Take hold of an argument the code under test built, rather than describing it — for assertions, not `calledWith`                       |
| `narrow(value, predicate)` / `narrow.byKey` / `narrow.observable`                                            | The branch of a union a test knows it got, failing with the shape the value actually had                                              |
| `withOverrides(model, overrides?)`                                                                           | A fixture from a model instance: its getters read once, as data                                                                       |
| `compareTestRuns(a, b, root?)` / `formatTestRunComparison(diff)` / `summarizeTestRun(report, root?)`         | Whether a migration lost a test — the set of names, which counters cannot answer                                                      |
| `installProxyZonePatch(opts?)`                                                                               | `fakeAsync` / `waitForAsync` on Vitest (`/zone`, which installs it on import)                                                         |
| `restoreTimerGlobals()` / `getWatchedTimerGlobals()`                                                         | Put back timer globals the fakes deleted / the names captured (`/setup`)                                                              |
| `renderShallow(Component, opts?)`                                                                            | `TestBed` component without its children and (by default) its template (`/angular`)                                                   |
| `createWithAutoSpies(Class, opts?)`                                                                          | Build a class through Angular DI with every unprovided token auto-spied (`/angular`)                                                  |
| `stable(fixture, opts?)` / `flushEffects()`                                                                  | Zoneless waiting: flush effects, then await the fixture, with a 2 s budget that names the cause (`/angular`)                          |
| `settleResource(resource, opts?)`                                                                            | Tick until an `httpResource()` / `resource()` / `rxResource()` leaves `loading` (`/angular`)                                          |
| `registerResourceMatchers()`                                                                 | Adds `toBeLoading` / `toHaveResourceValue` / `toHaveResourceError`; the value matcher fails an unresolved resource (`/angular`)        |
| `registerSignalMatchers()`                                                                                   | Adds `expect(sig).toHaveSignalValue(value)` (`/angular`)                                                                              |
| `enableTestBedDiagnostics(opts?)`                                                                            | Per-file report of how much of a spec's time went into `TestBed` (`/angular`)                                                         |
| `registerDomGlobals(opts?)`                                                                                  | Install a DOM into a runtime that ships none; returns the registrar used (`/bun-angular`)                                             |
| `createJsdomRegistrar(opts)` / `createGlobalRegistratorRegistrar(opts)`                                      | The two DOM strategies `registerDomGlobals` tries, for a custom preload (`/bun-angular`)                                              |
| `copyWindowGlobals(source, target)`                                                                          | Copy a window's properties onto a global-like target, without clobbering runtime built-ins                                            |
| `inlineAngularResources(source, path, opts?)`                                                                | Rewrite `templateUrl` / `styleUrl` / `styleUrls` into inline `template` / `styles`                                                    |
| `consoleDebugSpy` … `consoleWarnSpy`                                                                         | Silent typed spies replacing the global `console` methods on import (`/console`)                                                      |
| `installConsoleSpies()` / `resetConsoleSpies()` / `restoreConsole()`                                         | Install / clear / undo the console spies (`/console`)                                                                                 |
| `errorHandler`                                                                                               | The `mustBeCalledWith` argument-mismatch error helper                                                                                 |
| `vitest-auto-spy/eslint-plugin`                                                                              | Nine flat-config lint rules that steer a suite onto these helpers                                                                     |

## Helper surface by return type

**Spied sync method:** `mockReturnValue`, `calledWith(...)`, `mustBeCalledWith(...)` —
`calledWith` / `mustBeCalledWith` accept asymmetric matchers (`expect.any`, `expect.objectContaining`, …)

**Spied Promise method:** `resolveWith`, `rejectWith`, `resolveWithPerCall`; outcomes are
recorded on `mock.settledResults` (native on Vitest, polyfilled on Bun / `node:test`)

**Spied Observable method / property:** `nextWith`, `nextOneTimeWith`, `nextWithValues`,
`nextWithPerCall`, `throwWith`, `complete`, `returnSubject`

## Configuration

**`ClassSpyConfiguration`:** `methodsToSpyOn` (added to the discovered methods),
`onlyMethodsToSpyOn` (spy on nothing but these — discovery skipped), `instanceMethodsToSpyOn` (same
behaviour as `methodsToSpyOn`, named for callables that live on the instance — `signal()` fields,
arrow props, `signalStore()` methods), `observablePropsToSpyOn`,
`gettersToSpyOn`, `settersToSpyOn` (any string key — "is an accessor" is a fact about the
descriptor, not about the value's type, so a signal-valued getter is nameable), `returns` (return
values installed as the spy is built), `autoSpyAccessors` (auto-discover getters/setters),
`fillMissing` (answer a name the prototype never carried with a spy — for a **partially** abstract
class, where the erased members leave the empty-prototype fallback unable to fire),
`lazySpies` (build each method spy on first access — the `provideAutoSpy` default on Angular)

**`ValueConfig`** (for `nextWithValues`): `{ value, delay? }` | `{ errorValue, delay? }` |
`{ complete?, delay? }`.

## Public types

**`Spy<T>`** — the assembled spy. A **mapped type** over `T`: every method becomes
`AddSpyMethodsByReturnTypes<Method>` (the mock plus the helpers its return type earns), every
`Observable` property gains the observable helpers, everything else keeps its own type. It also adds
an `accessorSpies` bag: `accessorSpies.getters[key]` / `accessorSpies.setters[key]`.

Because it is a mapped type it **drops `#private` and `private` members**, so `Spy<T>` is not
assignable to `T`. Declare the variable as `Spy<T>` — `injectSpy(X)` already returns it — or bridge
the two with [`asInstance` / `asSpy`](https://asdalexey.github.io/vitest-auto-spy/core/spy-typing).

**`ClassType<T>`** — a constructor of `T`, the token `createSpyFromClass` / `provideAutoSpy` take. The
construct signature is _abstract_, so an `abstract class` DI token is accepted; nothing here ever
calls `new` on it.

**`DeepMockProxy<T>`** — what `mockDeep<T>()` returns: object properties become nested deep mocks,
so `mock.a.b.c` is chainable without seeding. Depth comes from property _access_: a chain that goes
through a call (`a.b().c()`) needs `{ selfReturning: true }`.

**`SubscribableLike<T>` / `CallbackSubscribable<T>` / `EmissionSource<T>`** — the two subscription
contracts the emission helpers accept (an observer object, as rxjs takes; a bare `next` callback, as
Angular's `output()` takes) and their union.

**`AddSpyMethodsByReturnTypes<Method>`** — the per-method surface: the mock itself intersected with
`calledWith` / `mustBeCalledWith`, plus the `Promise` or `Observable` helper bundle when the return
type earns one.

**`Spy<T, Options>`** — the second parameter is `{ overload?: 'first' | 'last' }`. `Parameters` and
`ReturnType` read the **last** signature of an overloaded method, which on a generated API client is
`observe: 'events'` — the one nobody calls. `Overload<F, 0>` names one signature on its own.

**`DeepPartial<T>`** — what `createMock` / `createAutoMock` take: partial at every depth, and a key
`T` does not have is still rejected at every depth. Built-ins (`Date`, `Map`, `Promise`, functions)
pass through untouched. A real value is accepted wherever a partial is, so a host object such as
a `NodeList` stays assignable to the mapping of itself.

**`ClassSpyConfiguration<T>`**, **`ValueConfig<T>`**, `NextValueConfig`, `ErrorValueConfig`,
`CompleteValueConfig`, `ValueConfigPerCall`, `OnlyMethodKeysOf<T>`, `OnlyObservablePropsOf<T>`,
`AccessorKeysOf<T>`, `MethodReturns<T>`, `PropStubValue<V>`, `SpyOptions`, `Overloads<F>` are
exported from the core as well.

## Exports by subpath

Every runtime and framework subpath re-exports the **whole core** on top of what it adds, so a spec
never needs two imports from this package.

| Subpath             | Adds on top of the core                                                                                                                                                                                                                                                                                                                                |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `vitest-auto-spy`   | — (this is the core; registers the Vitest adapter)                                                                                                                                                                                                                                                                                                     |
| `/bun`              | — (registers the `bun:test` adapter)                                                                                                                                                                                                                                                                                                                   |
| `/node`             | — (registers the `node:test` adapter)                                                                                                                                                                                                                                                                                                                  |
| `/bun-angular`      | `provideAutoSpy`, `injectSpy`, `renderShallow`, `createWithAutoSpies`, `stable`, `flushEffects`, `settleResource`, the DOM/inliner building blocks; registers the Bun adapter and boots a zoneless `TestBed`                                                                                                                                                             |
| `/rxjs`             | `createObservableWithValues` + the observable type surface; registers the observable layer                                                                                                                                                                                                                                                             |
| `/angular`          | `provideAutoSpy`, `provideAutoSpyForToken`, `injectSpy`, `overrideAutoSpy`, `overrideComponentProvider`, `assertNgModuleScopes`, `setupAngularTestEnv`, `createDirectiveHost`, `registerDirectiveMatchers`, `renderShallow`, `createWithAutoSpies`, `stable`, `flushEffects`, `settleResource`, `mockResourceProp`, `mockSignalProp`, `registerSignalMatchers`, `registerResourceMatchers`, the TestBed diagnostics                        |
| `/nestjs`           | `provideAutoSpy`, `injectSpy(moduleRef, token)`, `NestModuleRef`, `NestValueProvider`                                                                                                                                                                                                                                                                  |
| `/vue`              | `provideAutoSpy`, `VueInjectionToken`, `VueProvideSpy`                                                                                                                                                                                                                                                                                                 |
| `/react`, `/svelte` | — (the core, under a name that reads right in those suites)                                                                                                                                                                                                                                                                                            |
| `/console`          | `consoleDebugSpy` … `consoleWarnSpy`, `installConsoleSpies`, `resetConsoleSpies`, `restoreConsole`                                                                                                                                                                                                                                                     |
| `/zone`             | `installProxyZonePatch` — and installs it on import. The only entry that touches zones; zone.js is a **devDependency of this package and nothing else**, and no other entry reaches this module                                                                                                                                                        |
| `/setup`            | `setupAutoSpy`, `setupFakeTimers`, `advanceTimers`, `mockSystemTime`, `withSystemTime`, `mockNow`, `useCountingClock`, `registerFocusMatchers`, `blockNetwork`, `guardGlobalPatches`, `installPerTest`, `restoreTimerGlobals`, the stray-timer and stray-rejection trackers, the mock-registry trackers, `describeDuplicateCopies`, `getPackageCopies` |
| `/eslint-plugin`    | the flat-config plugin object                                                                                                                                                                                                                                                                                                                          |

The core itself also carries, beyond the factories: `captureArg`, `asInstances`, `narrow`, `withOverrides`,
`compareTestRuns`, `mockConstructor`, `stubConstructor`,
`stubAbortController`, `stubMediaElement`, `flushEventLoop`, `flushEventLoopUntil`,
`settleDynamicImport`, `assertMocked`, `moduleNamespace`, `diffByField`, `autoMocked`, the observer
stubs (`stubIntersectionObserver` / `stubResizeObserver` / `stubMutationObserver` / `stubObserver`)
and their entry builders (`intersectionEntry`, `mutationRecord`, `resizeEntry`).

**One adapter per run**
Each entry registers its mock adapter **on import**. Import the one that matches your runner —
pulling `vitest-auto-spy` into a `bun test` run leaves Vitest's adapter installed.

Two helpers are Vitest-only and deliberately absent from `/bun-angular`, because they need the
runner's `expect.extend` and suite-level hooks: `registerSignalMatchers` / `registerResourceMatchers`
and the TestBed diagnostics family. `mockResourceProp` is Vitest-only for a different reason — it
lives beside the other `mock*Prop` helpers, which `/bun-angular` does not re-export either.

---

Source: https://asdalexey.github.io/vitest-auto-spy/comparison

# Comparison

How `vitest-auto-spy` compares to other mocking / auto-spy libraries. The niche: the only auto-spy
library that reads a **class** and gives a **fully-typed** spy of every method with
**return-type-aware** control helpers — across any Vitest-compatible runtime and framework.

| Library                                                                                      | Reads a class? | Return-type-aware helpers? | Runtime     | We win on                                                                                                                                                                                                                 |
| -------------------------------------------------------------------------------------------- | -------------- | -------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [**jest-auto-spies**](https://www.npmjs.com/package/jest-auto-spies)                         | ✅             | ✅                         | Jest only   | Vitest/Bun/`node:test` successor, same API — direct migration path.                                                                                                                                                       |
| [**@bugsplat/vitest-auto-spies**](https://www.npmjs.com/package/@bugsplat/vitest-auto-spies) | ✅             | ✅                         | Vitest only | Same class-based API **plus** Bun & `node:test`, type-only `createAutoMock`, framework recipes, console spies, and **zero runtime deps** (it depends on `@hirez_io/auto-spies-core`; `rxjs < 8` cap — we support rxjs 8). |
| [**vitest-mock-extended**](https://www.npmjs.com/package/vitest-mock-extended)               | ❌ (Proxy)     | ❌                         | Vitest      | Return-type ergonomics **and** reading a real class. Its type-only mode is matched by `createAutoMock` / `mockDeep`, with the helpers kept.                                                                               |
| [**@golevelup/ts-vitest**](https://www.npmjs.com/package/@golevelup/ts-vitest)               | partial        | ❌                         | Vitest      | Typed Promise/Observable helpers + explicit class→spy + `mustBeCalledWith`.                                                                                                                                               |
| [**ts-auto-mock**](https://www.npmjs.com/package/ts-auto-mock)                               | ❌ (transform) | ❌                         | Jest/ts     | No compiler transformer to install — runtime-only, no toolchain coupling.                                                                                                                                                 |
| [**sinon**](https://www.npmjs.com/package/sinon)                                             | ❌ (manual)    | ❌                         | Any         | Auto-generated + fully typed vs manual + loosely typed.                                                                                                                                                                   |
| [**testdouble.js**](https://www.npmjs.com/package/testdouble)                                | partial        | ❌                         | Any         | Stronger typing, return-type-aware helpers, framework recipes.                                                                                                                                                            |

**Pitch:** the only auto-spy library that reads a **class** and gives a **fully-typed** spy of
every method with **return-type-aware** control helpers (`resolveWith` / `nextWith` /
`calledWith`) — across any Vitest-compatible runtime and framework.

## Feature by feature

|                                         | vitest-auto-spy | jest-auto-spies | vitest-mock-extended | @golevelup/ts-vitest |  sinon  |
| --------------------------------------- | :-------------: | :-------------: | :------------------: | :------------------: | :-----: |
| Spy every method of a class in one call |       ✅        |       ✅        |          ❌          |       partial        |   ❌    |
| Mock from a **type/interface**          |       ✅        |       ❌        |          ✅          |          ✅          |   ❌    |
| Recursive deep mock                     |       ✅        |       ❌        |          ✅          |          ❌          |   ❌    |
| Spy-free data double (`createMock`)     |       ✅        |       ❌        |          ❌          |          ❌          |   ❌    |
| `resolveWith` / `rejectWith`            |       ✅        |       ✅        |          ❌          |          ❌          |   ❌    |
| `nextWith` / `nextWithValues` (RxJS)    |       ✅        |       ✅        |          ❌          |          ❌          |   ❌    |
| `calledWith` / `mustBeCalledWith`       |       ✅        |       ✅        |     `calledWith`     |          ❌          |   ❌    |
| Getter / setter spies                   |       ✅        |       ✅        |          ❌          |          ❌          |   ✅    |
| Vitest                                  |       ✅        |       ❌        |          ✅          |          ✅          |   ✅    |
| Bun (`bun:test`)                        |       ✅        |       ❌        |          ❌          |          ❌          | partial |
| `node:test`                             |       ✅        |       ❌        |          ❌          |          ❌          | partial |
| Angular `TestBed` under `bun test`      |       ✅        |       ❌        |          ❌          |          ❌          |   ❌    |
| Runtime dependencies                    |      **0**      |        1        |          1           |          0           |    4    |

Dependency counts are each package's own `dependencies` on npm, checked 2026-08-26 —
`@hirez_io/auto-spies-core` for `jest-auto-spies`, `ts-essentials` for `vitest-mock-extended`, and
four `@sinonjs/*` + `diff` packages for `sinon`.

## Beyond the class spy

The tables above compare the part every one of these libraries does. What none of the others ship
alongside it:

- [**Angular's `TestBed` under `bun test`**](https://asdalexey.github.io/vitest-auto-spy/runtimes/bun-angular) — Bun ships no DOM and cannot
  resolve `templateUrl`, so Angular specs do not run there at all. One preload closes both gaps.
- [`renderShallow`](https://asdalexey.github.io/vitest-auto-spy/adapters/angular#shallow-component-rendering) and
  [`createWithAutoSpies`](https://asdalexey.github.io/vitest-auto-spy/adapters/angular#building-a-class-with-auto-spied-dependencies) — the
  shallow-`TestBed` copy-paste and DI-driven instantiation as one call each.
- [`stable` / `flushEffects`](https://asdalexey.github.io/vitest-auto-spy/adapters/angular#zoneless-waiting) and `toHaveSignalValue` — zoneless
  waiting and a signal matcher, for a codebase where `detectChanges()` is no longer enough.
- [Observable assertions](https://asdalexey.github.io/vitest-auto-spy/core/observable-assertions) that fail when the stream stays silent,
  duck-typed so they pull in no rxjs.
- [`setupFakeTimers()` / `advanceTimers()`](https://asdalexey.github.io/vitest-auto-spy/utilities/fake-timers) — an advance that also drains the
  microtasks a bare `advanceTimersByTime()` leaves pending, and
  [`flushEventLoop` / `settleDynamicImport`](https://asdalexey.github.io/vitest-auto-spy/utilities/event-loop) for the queue the clock does not
  reach at all.
- [`mockConstructor` / `stubConstructor`](https://asdalexey.github.io/vitest-auto-spy/utilities/constructor-doubles) — a double the code under
  test can call with `new`, which a runner's own `vi.fn(() => instance)` is not.
- [`fakeAsync` and `waitForAsync` on Vitest](https://asdalexey.github.io/vitest-auto-spy/utilities/zone) — `zone.js/testing` installs its
  ProxyZone through Jasmine and Jest hooks only, so both throw until this patch is imported.
- [`assertMocked` / `moduleNamespace`](https://asdalexey.github.io/vitest-auto-spy/utilities/module-mocks) — proof that a `vi.mock()` actually
  applied under a bundler, instead of a spec quietly asserting on the real module.
- [`setupAutoSpy({ strayRejections: true })`](https://asdalexey.github.io/vitest-auto-spy/utilities/setup#_8-failing-on-a-rejection-zone-js-swallowed) —
  the promise rejections zone.js drains into `console.error` and no further, turned into failed
  tests. Nothing else on this list looks there: a swallowed rejection never reaches the channel
  Vitest watches, so a spec that asserts inside a `.then()` nobody awaits stays green and exits 0.
- [`setupAutoSpy({ pruneMockRegistry: true })`](https://asdalexey.github.io/vitest-auto-spy/utilities/setup#_9-pruning-the-mock-registry-nothing-empties) —
  the `Set` inside `@vitest/spy` that every `vi.fn()` joins and that nothing ever takes anything out
  of, kept to the mocks that outlive a file. On `isolate: false` it is what makes `clearMocks` cost
  more with every test already run, and what keeps a whole run's recorded arguments — and the
  component trees behind them — alive in one worker.
- [Twelve ESLint rules](https://asdalexey.github.io/vitest-auto-spy/utilities/eslint-plugin) versioned together with the API they recommend, and
  [`setupAutoSpy()`](https://asdalexey.github.io/vitest-auto-spy/utilities/setup) for the test-run hygiene a shared environment needs.
- [Per-file `TestBed` diagnostics](https://asdalexey.github.io/vitest-auto-spy/adapters/angular#where-a-spec-spends-its-time) — which specs
  actually pay for `TestBed`, and by how much.
- [`compareTestRuns`](https://asdalexey.github.io/vitest-auto-spy/migrating) — whether the migration that brought you here lost a test, from
  the two sets of names rather than from two totals that happen to match.

## Where another library is the better answer

- **You are on Jest and staying there.** `jest-auto-spies` is the same API; there is nothing to gain
  from switching runner just for this.
- **You only ever mock interfaces, never classes, and want nothing else.**
  `vitest-mock-extended` is smaller and does exactly that. `createAutoMock` /
  [`mockDeep`](https://asdalexey.github.io/vitest-auto-spy/core/auto-mock-by-type) cover the same ground here if you want the helpers too — the
  two are complementary, not exclusive.
- **You need sandboxes, fake servers, or a full test-double toolkit.** `sinon` is a wider tool; this
  package is deliberately only about turning a type or a class into a typed spy.

---

Source: https://asdalexey.github.io/vitest-auto-spy/agents

# For AI agents

Most tests are now written with an assistant in the loop. Documentation an agent has to *infer* the
API from costs tokens on every task and produces the same handful of mistakes each time, so this
package ships a second, compressed form of its documentation written for a machine reader: the
decision tree, the configuration semantics, an error→fix table and the anti-patterns.

## The five entry points

| What                                                             | Where                                                        | Best for                                                  |
| ---------------------------------------------------------------- | ------------------------------------------------------------ | --------------------------------------------------------- |
| [`llms.txt`](https://asdalexey.github.io/vitest-auto-spy/llms.txt)                                          | the site root                                                | a crawler choosing the one page it needs                  |
| [`llms-full.txt`](https://asdalexey.github.io/vitest-auto-spy/llms-full.txt)                                | the site root                                                | reading the entire documentation in a single fetch        |
| [`AGENTS.md`](https://github.com/ASDAlexey/vitest-auto-spy/blob/master/AGENTS.md) | `node_modules/vitest-auto-spy/AGENTS.md` | any agent, **with no network** — it ships in the tarball  |
| [Spec patterns](https://asdalexey.github.io/vitest-auto-spy/recipes)                                        | the docs site                                                 | the shapes a real suite converged on, with the frequencies |
| A Claude Code skill                                              | `skills/vitest-auto-spy/SKILL.md`, also in the tarball        | Claude Code, loaded only when a spec mentions the library |

[`llms.txt`](https://llmstxt.org) is the convention an LLM-facing crawler looks for at a docs site
root: a link-only map, so an agent fetches one page instead of scraping the rendered HTML of ten.
Both files are generated from this site's sidebar and checked in CI, so they cannot drift.

## One command

```bash
npx vitest-auto-spy init
```

It writes the pointer below into the files the agents in *this* repository actually read, and
specialises it: which subpath matches this runner, which adapter matches the framework, the real
path of the setup file that needs `import 'vitest-auto-spy/rxjs'` — and it omits the rxjs line
entirely when rxjs is not installed. Everything it writes sits between markers and is regenerated
on the next run, so an upgrade is a one-hunk diff and `init --uninstall` puts the file back.

`npx vitest-auto-spy init --check` is the CI form: it fails when the block on disk is not the
block the installed version would write. The whole command is documented on
[The CLI](https://asdalexey.github.io/vitest-auto-spy/utilities/cli); the rest of this page is what it writes, and how to do it by hand.

## Point your agent at it once

The single highest-leverage line, in the instruction file your agent actually reads — a root
`AGENTS.md` for Codex, Cursor, Copilot and most of the field, `CLAUDE.md` for Claude Code and for
GLM or Kimi running inside it:

```md
When writing or fixing tests that use `vitest-auto-spy`, first read
`node_modules/vitest-auto-spy/AGENTS.md`. It is the authoritative reference for the API,
the configuration semantics and the common mistakes.
```

That file is already on disk in every project that installs the package, so the agent pays no
network round-trip and gets the version it actually has installed rather than whatever the web
returned.

## Which file your agent reads

The snippet above is the same for every tool; only the filename changes. **Two files cover the whole
field: a root `AGENTS.md` and a root `CLAUDE.md`.** Put the identical block in both and every agent
in this table is served — including the ones your teammates use and you do not.

| Agent                                                               | Instruction file it reads                                                                                                                                                               | Reads `AGENTS.md`?                                                |
| --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| **Claude Code**                                                     | `CLAUDE.md` — project, `.claude/CLAUDE.md` and `~/.claude/CLAUDE.md`, all concatenated                                                                                                   | **No.** Bridge with an `@AGENTS.md` import line, or a symlink      |
| **OpenAI Codex** — the `codex` CLI, the IDE extension, Codex cloud  | `AGENTS.md`, one per directory from the git root down to the cwd ([below](#openai-codex))                                                                                               | native                                                             |
| **GLM (z.ai coding plan)**, **Kimi K2**                             | whatever their client reads — inside Claude Code that is `CLAUDE.md` ([below](#glm-z-ai-kimi-k2-and-other-claude-compatible-models))                                                     | through the client                                                 |
| **Cursor**                                                          | root `AGENTS.md`; `.cursor/rules/*.mdc` for glob-scoped rules                                                                                                                            | native — and it applies a root `CLAUDE.md` the same always-on way  |
| **GitHub Copilot**                                                  | root `AGENTS.md`; `.github/copilot-instructions.md`                                                                                                                                      | native, coding agent included                                      |
| **OpenCode**                                                        | `AGENTS.md`, then `CLAUDE.md`, per directory upwards                                                                                                                                     | native                                                             |
| **Cline**                                                           | root `AGENTS.md`; the `.clinerules/` directory                                                                                                                                           | native                                                             |
| **Windsurf / Cascade**                                              | root `AGENTS.md`; `.windsurf/rules/*.md` (`.devin/rules/*.md` when present)                                                                                                              | yes                                                                |
| **Zed**                                                             | **first match wins, no merging**: `.rules` → `.cursorrules` → `.windsurfrules` → `.clinerules` → `.github/copilot-instructions.md` → `AGENT.md` → `AGENTS.md` → `CLAUDE.md` → `GEMINI.md` | yes — only if nothing earlier in that list exists                  |
| **Gemini CLI**                                                      | `GEMINI.md` ([below](#gemini-cli))                                                                                                                                                       | **not by default**                                                 |
| **Qwen Code**                                                       | `QWEN.md`                                                                                                                                                                                | native fallback                                                    |
| **Roo Code**                                                        | root `AGENTS.md`; `.roo/rules/`                                                                                                                                                          | yes                                                                |
| **Junie**                                                           | root `AGENTS.md` — note that `.junie/AGENTS.md` replaces it outright                                                                                                                     | yes                                                                |
| **Aider**                                                           | nothing implicitly — list the file: `read: [AGENTS.md]` in `.aider.conf.yml`                                                                                                             | on request                                                         |
| **Jules, Factory, goose, Amp, Warp, Devin, Kilo, Augment, VS Code** | root `AGENTS.md`                                                                                                                                                                         | native                                                             |

**Never create a legacy rules file just to hold the snippet**
Zed resolves `.rules` → `.cursorrules` → `.windsurfrules` → `.clinerules` → … **first-match-wins,
with no merging**, so a newly created legacy file silently shadows the `AGENTS.md` the rest of the
project relies on. Append to one only if it already exists.

## Install it in your agent

Two commands at the repository root cover every tool in that table:

```bash
# 1 — AGENTS.md: Codex, Cursor, Copilot, Cline, Windsurf, Zed, OpenCode, Qwen, Roo, Junie, Aider…
cat >> AGENTS.md <<'MD'

## Tests that use `vitest-auto-spy`

When writing or fixing tests that use `vitest-auto-spy`, first read
`node_modules/vitest-auto-spy/AGENTS.md`. It is the authoritative reference for the API,
the configuration semantics and the common mistakes.
MD

# 2 — CLAUDE.md: Claude Code, and GLM / Kimi running inside it. One line, no second copy to maintain
printf '\n@AGENTS.md\n' >> CLAUDE.md
```

`@AGENTS.md` is Claude Code's own import syntax, so the instructions live in exactly one file. A
symlink (`ln -s AGENTS.md CLAUDE.md`) does the same job if you would rather not have the second file
at all.

Then, per tool — everything in the right-hand column is optional on top of those two files:

| Agent                                       | Install                                                                                                                                                                 |
| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Claude Code**                             | `/plugin marketplace add ASDAlexey/vitest-auto-spy`, then `/plugin install vitest-auto-spy@vitest-auto-spy` — [the skill](#claude-code-plugin), no project files touched |
| **OpenAI Codex**                            | nothing more; optionally `~/.codex/config.toml` from [below](#openai-codex)                                                                                             |
| **GLM (z.ai)**, **Kimi K2**                 | identical to Claude Code — same client, same plugin command                                                                                                             |
| **Cursor**                                  | `.cursor/rules/vitest-auto-spy.mdc` to load it only for spec files (see below)                                                                                          |
| **GitHub Copilot**                          | `.github/instructions/vitest-auto-spy.instructions.md` (see below)                                                                                                      |
| **Cline**                                   | `.clinerules/vitest-auto-spy.md` — the same three lines, plus `paths: ["**/*.spec.ts","**/*.test.ts"]`                                                                   |
| **Windsurf / Cascade**                      | `.windsurf/rules/vitest-auto-spy.md` with `trigger: glob` (see below)                                                                                                   |
| **Roo Code**                                | `.roo/rules/vitest-auto-spy.md` — always on, so keep it to the three-line pointer                                                                                       |
| **Gemini CLI**                              | `GEMINI.md`, or the `.gemini/settings.json` patch from [below](#gemini-cli)                                                                                             |
| **Aider**                                   | `.aider.conf.yml`: `read: [AGENTS.md]`                                                                                                                                  |
| **Zed, OpenCode, Qwen Code, Junie, Jules…** | nothing — the root `AGENTS.md` is the whole install                                                                                                                     |

The glob-scoped variants, for the three tools whose format is not plain Markdown. Each body is the
same pointer; only the frontmatter differs:

```md
<!-- .cursor/rules/vitest-auto-spy.mdc -->
---
description: How to write tests with vitest-auto-spy
globs: **/*.spec.ts, **/*.spec.tsx, **/*.test.ts, **/*.test.tsx
alwaysApply: false
---

Read `node_modules/vitest-auto-spy/AGENTS.md` before writing or fixing a spec that uses
`vitest-auto-spy` — the API, the configuration semantics and the common mistakes.
```

```md
<!-- .github/instructions/vitest-auto-spy.instructions.md -->
---
applyTo: '**/*.spec.ts,**/*.spec.tsx,**/*.test.ts,**/*.test.tsx'
---

Read `node_modules/vitest-auto-spy/AGENTS.md` before writing or fixing a spec that uses
`vitest-auto-spy`.
```

```md
<!-- .windsurf/rules/vitest-auto-spy.md — .devin/rules/ when that directory exists -->
---
trigger: glob
globs: **/*.spec.ts, **/*.test.ts
---

Read `node_modules/vitest-auto-spy/AGENTS.md` before writing or fixing a spec that uses
`vitest-auto-spy`.
```

Cursor's `globs` is a **comma-separated string, not a YAML array**, and a Windsurf rule file is
capped at 12 000 characters — both are reasons the rule points at the reference instead of copying
it.

## OpenAI Codex

Codex — the `codex` CLI, the IDE extension and Codex cloud — reads the open `AGENTS.md` convention,
so a root `AGENTS.md` is the whole integration. Two details decide whether it reaches the model at
all:

- **The chain is git-root→cwd, at most one file per directory** (`AGENTS.override.md` wins over
  `AGENTS.md`), concatenated. In a monorepo, put the block in the package's own `AGENTS.md` as well
  when that package runs a different runner — it is the only way to say "this one is `bun test`, the
  one next door is Vitest", which is exactly the distinction that decides
  [which entry point](#point-it-at-the-subpath-not-only-at-the-package) the agent imports.
- **The whole chain is capped** by `project_doc_max_bytes`, **32 768 bytes by default**; anything
  over budget is truncated with a warning. If your `AGENTS.md` is already long, keep the pointer near
  the top of it.

For a repo that keeps its instructions in `CLAUDE.md`, teach Codex to fall back. This is global
config on your own machine, so there is nothing to commit:

```toml
# ~/.codex/config.toml
project_doc_fallback_filenames = ["CLAUDE.md"]   # per directory, when no AGENTS.md is there
project_doc_max_bytes = 65536                    # raise the 32 KB budget for a monorepo chain
```

Codex cloud reads the same root `AGENTS.md`, and its agent has **no internet access by default** —
which is precisely why the reference ships inside the tarball rather than only on this site.
`node_modules/vitest-auto-spy/AGENTS.md` is on disk the moment the setup script has installed
dependencies, so nothing has to be fetched.

## GLM (z.ai), Kimi K2 and other Claude-compatible models

GLM is a **model**, not an agent — the thing that reads files is the client you run it in.

The z.ai coding plan runs GLM **inside Claude Code**, by pointing `ANTHROPIC_BASE_URL` (with
`ANTHROPIC_AUTH_TOKEN`) at z.ai's Anthropic-compatible endpoint. File discovery is untouched by
that: `CLAUDE.md`, `.claude/skills/` and the [plugin](#claude-code-plugin) below behave exactly as
they do on Claude, because it is the same client. Kimi K2 driven through Claude Code is the same
story — and there the skill and the plugin are worth more than a pasted snippet, because they load
only when a spec actually mentions the library and cost no context the rest of the time.

Run GLM through a different client and that client decides: OpenCode, Cline, Roo Code and Kilo Code
all read the root `AGENTS.md`. Moonshot's own `kimi-cli` reads its own `AGENTS.md` chain, including
`.kimi/AGENTS.md`.

## Gemini CLI

Gemini CLI reads `GEMINI.md` and does **not** read `AGENTS.md` by default. Either paste the snippet
into `GEMINI.md`, or name both files once:

```json
// .gemini/settings.json
{ "context": { "fileName": ["GEMINI.md", "AGENTS.md"] } }
```

Qwen Code is derived from Gemini CLI and takes the same `context.fileName` setting, but already
falls back to `AGENTS.md` on its own.

## Claude Code plugin

The repository doubles as a Claude Code plugin marketplace, so the skill installs without touching
your project files:

```
/plugin marketplace add ASDAlexey/vitest-auto-spy
/plugin install vitest-auto-spy@vitest-auto-spy
```

The skill's description lists the library's exports and its four most common error messages, so it
loads when a task is actually about this package and stays out of the way otherwise. Its body is a
short decision tree plus a "reach for this before hand-rolling" table keyed by the *symptom* — the
error text or the failing shape — because that is what an agent has in hand when it starts.

## Point it at the subpath, not only at the package

Each entry registers its own mock adapter on import, and three of them are opt-in on purpose. An
agent that knows only the bare specifier writes a spec that throws at the first helper:

| Subpath                     | Needed for                                                               |
| --------------------------- | ------------------------------------------------------------------------ |
| `vitest-auto-spy/rxjs`      | `nextWith`, `observablePropsToSpyOn`, `throwWith` — imported once, in setup |
| `vitest-auto-spy/bun`       | any spec run by `bun test` (`/bun-angular` for Angular's TestBed there)  |
| `vitest-auto-spy/node`      | a `node --test` suite, ESM or CJS                                         |
| `vitest-auto-spy/angular`   | `provideAutoSpy`, `injectSpy`, `renderShallow`, the override helpers      |
| `vitest-auto-spy/setup`     | `setupAutoSpy`, the clock helpers, `installPerTest`, focus matchers       |
| [`vitest-auto-spy/zone`](https://asdalexey.github.io/vitest-auto-spy/utilities/zone) | `fakeAsync` / `waitForAsync` on Vitest — zone.js stays out of every other entry |

## Errors that name their own fix

An agent reads a stack trace far more often than it reads a README, so every error and warning this
package throws ends with a link to the page that explains it:

```
Observable spies require rxjs. Import 'vitest-auto-spy/rxjs' once (e.g. in your test setup)
to enable observablePropsToSpyOn / nextWith / nextWithValues / throwWith / complete / returnSubject.
Docs: https://asdalexey.github.io/vitest-auto-spy/runtimes/rxjs
```

The same applies to a missing mock adapter, a method that is not on the prototype, `advanceTimers()`
without fake timers, a `bun-angular` preload with no DOM package, an unresolvable `templateUrl`, a
`mustBeCalledWith` violation and the duplicate-install report.

## What agents get wrong most often

These account for the large majority of broken specs, and every one of them is covered in
`AGENTS.md`:

1. **`let s: MyService = createSpyFromClass(MyService)`.** `Spy<T>` is a mapped type and drops
   private members. Declare it as `Spy<T>`, or bridge with [`asInstance` / `asSpy`](https://asdalexey.github.io/vitest-auto-spy/core/spy-typing) —
   never with `as unknown as T`.
2. **Reaching for `methodsToSpyOn` to restrict.** It **adds** to the discovered methods, matching
   `jest-auto-spies`. The exhaustive whitelist is
   [`onlyMethodsToSpyOn`](https://asdalexey.github.io/vitest-auto-spy/core/create-spy-from-class), and it skips prototype discovery entirely.
3. **Calling `nextWith` without `import 'vitest-auto-spy/rxjs'`.** The observable layer is opt-in.
4. **Importing `vitest-auto-spy` inside a `bun test` file.** Each entry registers its own mock
   adapter on import; use [`vitest-auto-spy/bun`](https://asdalexey.github.io/vitest-auto-spy/runtimes/bun).
5. **`expect()` inside a `subscribe()` callback.** A silent stream makes it a green test that
   asserted nothing — use [`expectEmission`](https://asdalexey.github.io/vitest-auto-spy/core/observable-assertions), where the assertion is
   the `await`.
6. **`vi.fn().mockImplementation(() => instance)` for something the code calls with `new`.** The
   Jest idiom does not port: Vitest only forwards `new` to a constructible implementation, so an
   arrow records the call, skips the body and hands back an empty object — or throws
   `X is not a constructor` from inside production code. Use
   [`mockConstructor` / `stubConstructor`](https://asdalexey.github.io/vitest-auto-spy/utilities/constructor-doubles).
7. **An exported `const` holding `vi.fn()`s, shared between spec files.** Under `isolate: false` a
   module is evaluated once per worker, so that is one set of spies for every file that imports it.
   A fixture is a factory; a spec file exports nothing at all.
8. **`it('x', (done) => …)`.** Vitest passes a `TestContext`, so `done()` throws inside a promise
   nobody awaits and the test **passes** having run almost none of its body. The lint rule
   `no-done-callback` catches it; the fix is `await`.
9. **`await Promise.resolve()` to wait out a dynamic `import()` under fake timers.** It never
   advances one, and `setTimeout` is the fake one — use
   [`settleDynamicImport` / `flushEventLoop`](https://asdalexey.github.io/vitest-auto-spy/utilities/event-loop).
10. **Assuming a setup file's hooks reach every spec file.** They belong to the file whose
    collection imported the module, and a runner that keeps that module cached across files —
    `@angular/build:unit-test` under `--coverage` is the case seen in the wild — gives them to the
    first file of each worker and to no other. Nothing reports it; the symptom is a leaked global or
    real timers in a spec that passes on its own. Run coverage with `--isolate`, or call
    [`setupAutoSpy()`](https://asdalexey.github.io/vitest-auto-spy/utilities/setup) from something evaluated per file.