vitest-auto-spy 4.0.1 → 4.2.0

package/AGENTS.md

@@ -261,19 +261,23 @@ xhr.send.mockImplementation(() => respond(asInstance(xhr)));
 
 ### Cost, so it stops being a question
 
-Building a spy is not a thing to optimise. On a ten-method class: `provideAutoSpy` ~8 µs,
-`createSpyFromClass` ~29 µs, `createAutoMock` ~33 µs, a `calledWith` lookup ~0.7 µs — five providers
-across two thousand tests is under a tenth of a second. Call the factory in `beforeEach` and look at
-`TestBed` instead. The only two settings that cost: `{ lazySpies: false }` gives up the laziness
-`provideAutoSpy` defaults to, and `autoSpyAccessors: true` walks the prototype chain uncached on
-every call — name the accessors instead.
+Building a spy is not a thing to optimise. On a ten-method class, `npm run bench` on Node v24.19.0
+and Vitest 4.1.11, measured 2026-09-04: `createSpyFromClass` plus two methods called **2.25 µs**,
+plus all ten 5.83 µs, `createAutoMock` plus four members 1.79 µs, a `calledWith` lookup 0.21 µs —
+five providers across two thousand tests is about two hundredths of a second. Call the factory in
+`beforeEach` and look at `TestBed` instead. The only two settings that cost:
+`{ lazySpies: false }` gives up the laziness `provideAutoSpy` defaults to, and
+`autoSpyAccessors: true` walks the prototype chain uncached on every call — name the accessors
+instead.
 
 Memory is the exception, and only on classes wide enough for it to matter. `lazySpies: true` still
 defines one accessor per method, and that placeholder is nearly all of what an untouched double
-retains: 101.6 kB on a 400-method class against 11.8 kB with `lazySpies: 'proxy'`, which answers
-every method from a single trap object instead (25 B per method against 253 B). It is opt-in because
-a `Proxy` cannot remove itself — +30 ns per read and +43 ns per call, forever — and it loses on a
-five-method service. Reach for it on generated API clients and ngrx facades under `isolate: false`,
+retains: an untouched 100-method double holds 25 601 B against 4 097 B with `lazySpies: 'proxy'`,
+which answers every method from a single trap object instead — 256 B per method against 41 B
+(`npm run bench:memory`, 2026-09-04). It is opt-in because a `Proxy` cannot remove itself: the
+default leaves a plain data property behind once a method materialises, while the proxy goes through
+a trap on every read and every call for the life of the double, and on a narrow class it is also
+slower to create. Reach for it on generated API clients and ngrx facades under `isolate: false`,
 where the doubles of a whole file are alive at once; leave the default everywhere else.
 
 ---
@@ -1053,6 +1057,48 @@ is therefore remembered and put back, in `beforeEach`, but only when it has gone
 returns how many went), `restoreLongLivedImplementations()` is that repair (it returns how many it
 put back) and `getMockRegistrySize()` reports what is left.
 
+One entry is never pruned, and it is not one of yours: the Vitest adapter registers a single
+`vi.fn()` whose `mockClear` sweeps this library's own spies. Dropping it would turn
+`vi.clearAllMocks()` into a silent no-op for every double in the run, so it carries a mark the
+pruner skips. Why the library needs a mock of its own for that is the next section.
+
+### What a method spy is, and the one thing that differs from `vi.fn()`
+
+A method spy is **not** a `vi.fn()`. It is this library's own mock function: one shared prototype
+carrying the whole `Mock` surface, call state allocated on the first call rather than at creation,
+and no entry in any global registry. `vi.fn()` assigns some twenty-five closures as own properties
+of every mock it makes and allocates six arrays up front — per method, on every double a spec
+builds — and that cost is most of what a wide service used to pay for methods no test touches.
+
+Everything a spec can observe is the same, and the suite pins it by putting the two side by side:
+
+- `vi.isMockFunction(spy.load)`, `expect(spy.load).toHaveBeenCalledWith(…)`, `toHaveReturned`,
+  `toHaveResolved`, `toHaveBeenNthCalledWith` — every matcher reads `_isMockFunction`, `mock.*` and
+  `getMockName()`, all of which the spy implements with the runner's semantics.
+- `spy.load.mock.calls` / `.results` / `.settledResults` / `.instances` / `.contexts` /
+  `.invocationCallOrder` / `.lastCall`, `mockReturnValue`, `mockResolvedValue`,
+  `mockImplementation(Once)`, `withImplementation`, `mockClear` / `mockReset` / `mockRestore`,
+  `mockName`, `using`.
+- `vi.clearAllMocks()`, `vi.resetAllMocks()`, and the `clearMocks` / `mockReset` config keys, which
+  Vitest applies through those two functions.
+
+**The one difference.** `mock.invocationCallOrder` counts on this library's own scale, so
+`expect(a).toHaveBeenCalledBefore(b)` is exact between two auto-spies and meaningless between an
+auto-spy and a hand-written `vi.fn()` — the two counters never met. Nothing else in the library or in
+Vitest reads that field. If a suite needs the comparison, switch the whole run back to the runner's
+factory:
+
+```ts
+// vitest.setup.ts
+import { setSpyEngine } from 'vitest-auto-spy/setup';
+
+setSpyEngine('runner'); // every double built afterwards is `vi.fn()` per method, as before 4.1
+```
+
+`getSpyEngine()` reports the current one, `'auto-spy'` is the default, and doubles already built keep
+the engine they were built with. The switch is Vitest-only: on Bun and `node:test` the runner's own
+matchers recognise only the runner's own mocks, so those adapters keep using them.
+
 Two more switches, both about the environment rather than the spies:
 
 ```ts
@@ -2058,20 +2104,30 @@ thing to check by hand after the swap: Suites' double answers every property nam
 stubbed a since-renamed method was passing over nothing and will now fail. Full mapping:
 <https://asdalexey.github.io/vitest-auto-spy/migrating-suites>.
 
-- **`renderShallow` has no single speed number, and quoting one is a bug.** Per render it ranges
-  from 1.2× (no children) to 16.2× (400 child instances) — `docs-site/core/performance.md`,
-  measured 2026-08-26. Per spec file, where imports and the `TestBed` module are also on the clock,
-  the published conversion is 1.7× over three specs with one of them a 0.8× regression. The two are
-  not interchangeable: the per-render ratio is the upper bound on what a file can gain. Any surface
-  that mentions the helper's speed quotes the range and links to
-  `/core/performance#_2-rendering-the-child-subtree`. A figure of **4.1×** appears in
-  `PRIORITIES.md` and is backed by nothing in this repository — do not publish it until someone
-  produces the measurement.
+- **`renderShallow` has no single speed number, and quoting one is a bug.** This repository commits
+  no harness for the helper, so no surface publishes a ratio for it and none may be invented.
+  Describe the shape instead: `renderShallow` is flat in the number of children because it never
+  builds the subtree, while `TestBed.createComponent` scales linearly with it — so the win is
+  however much markup the component under test happens to own, nothing on a leaf component and a
+  great deal on a table or a dashboard. A per-render ratio would in any case be the upper bound on
+  what a spec file can gain rather than a prediction of it, because a file also pays for imports,
+  the `TestBed` module and the assertions. Link to
+  `/core/performance#_2-rendering-the-child-subtree`. A speed figure for the helper also sits in
+  `PRIORITIES.md`, backed by nothing in this repository — do not publish it until someone produces
+  the measurement.
 - **Competitor defects are quoted from the published tarball, with a file, a line and a date.** The
   `@testing-library/angular` `createMock` claims in `docs-site/comparison.md` are pinned to
   `fesm2022/testing-library-angular-vitest-utils.mjs` lines 14 and 18 at 19.4.2. Re-`npm pack` and
   re-read before restating them against a new version; the "Where the numbers come from" box records
   each re-verification date rather than replacing the previous one.
+- **Head-to-head benchmark numbers are quoted from the measurement, not from memory.** `npm run
+bench:vs` and `npm run bench:suite` (see `CONTRIBUTING.md` for setup) back the claims in
+  `core/performance.md`; point at that page rather than retyping a figure here, so it lives in one
+  place. Micro-benchmark ratios do not transfer to suite scale: double construction is on the order
+  of 1% of a test's cost, and an advantage that looks like several times faster per double can be
+  gone, or reversed, once a whole suite runs. Suite-scale wall-clock is noisy between invocations;
+  peak RSS reproduces far more tightly and is the safer claim. Never state a magnitude the source
+  marks as not established.
 
 `node:test` keeps every `mock.fn()` in one process-wide `MockTracker` for the life of the process.
 On a long suite that is real memory — 20 000 spies of a 10-method class retained 124.5 MB on
@@ -2521,6 +2577,35 @@ worth one run after any large edit to a test suite — especially after a codemo
 the eaten glob below came from. Full reference:
 <https://asdalexey.github.io/vitest-auto-spy/utilities/cli>.
 
+### If you were asked why a suite is slow
+
+```bash
+npx vitest-auto-spy perf              # runs the suite once and reports; always exits 0
+npx vitest-auto-spy perf src/some/dir # a path is passed through to Vitest as a file filter
+```
+
+It reads Vitest's own per-file phase timings through `TestModule.diagnostic()` — nothing here
+parses terminal output — and reports six phases: `environment`, `import`, `tests`, `setup`,
+`prepare` (all measured per file) and `transform` (measured once for the whole run). **The phase
+totals are CPU time summed across every worker, not wall clock** — a report showing `20.29s of CPU
+time` under `986ms wall clock` is not a bug, it is the work spread over workers.
+
+When `environment` dominates, the `perf-environment` finding names spec files that could run under
+the `node` environment instead — but only the ones it could _prove_ reach no DOM: the spec, its
+configured setup files, and every repository module any of them imports were all read, none
+mentions a DOM name, and every package they import is on a short allowlist (`vitest`, `rxjs`,
+`date-fns`, `lodash`, `zod`, …). Anything it could not resolve is reported **undecided**, never
+assumed safe — do not treat an undecided file as a candidate, and do not add packages to that list
+yourself; a false positive breaks someone's suite on `document is not defined`. When `import`
+dominates, `perf-import` names specs that reach their subject through a barrel (`index`/`public-api`
+re-exporting a whole directory). When `environment` + `setup` + `prepare` together dominate,
+`perf-isolation` suggests `test.isolate: false` and links to this package's own memory measurements
+of that trade rather than restating them — read that page before recommending the flag, since it
+raises peak memory.
+
+`--json <path>` re-analyses a report an earlier `--out <path>` run wrote, instead of running Vitest
+again. Full reference: <https://asdalexey.github.io/vitest-auto-spy/utilities/cli>.
+
 ### Migrating a suite off `jest-auto-spies` — run the codemod, then verify it
 
 ```bash

package/README.md

@@ -11,17 +11,19 @@ skip the class entirely and mock straight from a **type or interface** with `cre
 recursive `mockDeep<T>()`. Runs on **Vitest**, **Bun** (`bun:test`) and **`node:test`** behind one
 identical API, with **RxJS** spies and **Angular / NestJS / React / Vue·Pinia / Svelte** recipes
 ([availability](#availability)). A drop-in replacement for
-[`jest-auto-spies`](https://www.npmjs.com/package/jest-auto-spies) — same API — and for
+[`jest-auto-spies`](https://www.npmjs.com/package/jest-auto-spies) — same API, and roughly 1.5x
+faster at suite scale ([benchmarks](#benchmarks)) — and for
 [`jasmine-auto-spies`](https://www.npmjs.com/package/jasmine-auto-spies) through
 [`vitest-auto-spy/jasmine`](#migrating-from-jasmine-auto-spies), which keeps `.and`, `.calls` and
 `.withArgs` working while you land the suite green.
 
 [![npm version](https://img.shields.io/npm/v/vitest-auto-spy?color=brightgreen&logo=npm)](https://www.npmjs.com/package/vitest-auto-spy)
+[![downloads per day](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapi.npmjs.org%2Fdownloads%2Fpoint%2Flast-day%2Fvitest-auto-spy&query=%24.downloads&color=brightgreen&logo=npm&label=downloads%2Fday)](https://www.npmjs.com/package/vitest-auto-spy)
 [![downloads per week](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapi.npmjs.org%2Fdownloads%2Fpoint%2Flast-week%2Fvitest-auto-spy&query=%24.downloads&color=brightgreen&logo=npm&label=downloads%2Fweek)](https://www.npmjs.com/package/vitest-auto-spy)
 [![downloads per month](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapi.npmjs.org%2Fdownloads%2Fpoint%2Flast-month%2Fvitest-auto-spy&query=%24.downloads&color=brightgreen&logo=npm&label=downloads%2Fmonth)](https://www.npmjs.com/package/vitest-auto-spy)
 [![downloads over 18 months](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapi.npmjs.org%2Fdownloads%2Fpoint%2F2026-06-21%3A2030-01-01%2Fvitest-auto-spy&query=%24.downloads&color=brightgreen&logo=npm&label=downloads%2F18mo)](https://www.npmjs.com/package/vitest-auto-spy)
 [![CI](https://github.com/ASDAlexey/vitest-auto-spy/actions/workflows/ci.yml/badge.svg)](https://github.com/ASDAlexey/vitest-auto-spy/actions/workflows/ci.yml)
-[![minzipped size](https://img.shields.io/badge/minzip-12.9%20kB-brightgreen)](#install)
+[![minzipped size](https://img.shields.io/badge/minzip-14.3%20kB-brightgreen)](#install)
 [![types](https://img.shields.io/npm/types/vitest-auto-spy?logo=typescript&logoColor=white)](https://www.npmjs.com/package/vitest-auto-spy)
 [![coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](https://github.com/ASDAlexey/vitest-auto-spy/actions/workflows/ci.yml)
 [![license](https://img.shields.io/npm/l/vitest-auto-spy?color=blue)](./LICENSE)
@@ -53,7 +55,7 @@ identical API, with **RxJS** spies and **Angular / NestJS / React / Vue·Pinia /
 - 📡 First-class RxJS `Observable` spying (`nextWith`, `nextWithValues`, `throwWith`, …)
 - ⚙️ Getter / setter spies via `accessorSpies` — **including on Bun**, where `bun:test`'s own `spyOn(obj, 'prop', 'get')` throws _"does not support accessor properties yet"_ (verified on Bun 1.4.0); no library that generates a double from a class or a type has accessor spies on any runner
 - 🧰 DI & mocking utilities — `provideAutoSpy` / `injectSpy` (Angular, NestJS, Vue), `createFunctionSpy`, `mockReadonlyProp` for signals
-- ⚡ Angular speed & zoneless helpers — `renderShallow` (**1.7×** across three converted specs of a real suite; per render, **1.2×** on a childless leaf up to **16.2×** on a 400-child tree — [both measurements below](#shallow-component-rendering)), `createWithAutoSpies`, `stable` / `flushEffects`, `settleResource` for `httpResource()`, `toHaveSignalValue`, per-file `TestBed` timings
+- ⚡ Angular speed & zoneless helpers — [`renderShallow`](#shallow-component-rendering), which brings a component up through the real `TestBed` without its child subtree, `createWithAutoSpies`, `stable` / `flushEffects`, `settleResource` for `httpResource()`, `toHaveSignalValue`, per-file `TestBed` timings
 - **`node:test` stops retaining every spy.** Node's built-in runner keeps every `mock.fn()` in one
   process-wide `MockTracker` and has no way to drop a single entry, so a long suite accumulates every
   spy it ever made along with every argument they recorded. `trackNodeMocks()` gives this library a
@@ -75,7 +77,8 @@ identical API, with **RxJS** spies and **Angular / NestJS / React / Vue·Pinia /
 - 🚚 A migration you can verify — `vitest-auto-spy/diagnostics`: `compareTestRuns` on the two JSON reports, `summarizeTestRun` / `formatTestRunComparison` to read the answer, `diffByField` for the assertion the reporter collapses
 - 📏 Lint rules and one-line test-run hygiene — nineteen rules in `vitest-auto-spy/eslint-plugin` (three `--fix`, seven suggestions, four of them for a suite mid-migration off jasmine), `setupAutoSpy()`
 - 🩺 [Editor diagnostics](#editor-diagnostics--webstorm--vs-code) — the same anti-patterns underlined while you type: native ESLint inspections in **WebStorm** and the other JetBrains IDEs, the ESLint extension in **VS Code**, no extra plugin either way
-- 🔎 [`npx vitest-auto-spy doctor`](#the-cli--doctor-codemod-and-init) — suite-level defects **that never fail a run**: a `tsconfig` `include` matching no file, a production module importing a spec, a `@jest-environment` pragma the runner never reads, config left behind for a runner that is gone. Read-only, no config, exits 1 in CI
+- 🔎 [`npx vitest-auto-spy doctor`](#the-cli--doctor-perf-codemod-and-init) — suite-level defects **that never fail a run**: a `tsconfig` `include` matching no file, a production module importing a spec, a `@jest-environment` pragma the runner never reads, config left behind for a runner that is gone. Read-only, no config, exits 1 in CI
+- ⏱️ [`npx vitest-auto-spy perf`](#perf--where-the-cpu-time-actually-goes) — where a suite's CPU time actually goes, phase by phase, and which spec files to act on: the ones that reach no DOM and could run under `node`, the ones that import a barrel. Runs Vitest once with a reporter this package ships, reads `TestModule.diagnostic()`, names files, states the rule behind each finding
 - 🚚 [`npx vitest-auto-spy codemod`](#codemod--migrating-a-suite-off-jest-auto-spies) — thirteen transforms that move a suite off `jest-auto-spies` and Jest, or off `jasmine-auto-spies` and jasmine (`--from jasmine`), dry-run by default, with a `--verify` pass that also checks a file somebody edited by hand
 - 🔇 Console spies — `import { consoleInfoSpy } from 'vitest-auto-spy/console'` silences `console` and asserts its calls
 - 🧭 [**Spec patterns**](https://asdalexey.github.io/vitest-auto-spy/recipes) — the shapes a ~370-file Angular suite converged on, and the traps that only surface at scale
@@ -104,8 +107,9 @@ includes — that one import is what keeps `returnSubject()` typed as rxjs's own
 - [Install](#install)
   - [Requirements](#requirements)
   - [Peer dependencies](#peer-dependencies)
-- [The CLI — `doctor`, `codemod` and `init`](#the-cli--doctor-codemod-and-init)
+- [The CLI — `doctor`, `perf`, `codemod` and `init`](#the-cli--doctor-perf-codemod-and-init)
   - [`doctor` — defects that never fail](#doctor--defects-that-never-fail)
+  - [`perf` — where the CPU time actually goes](#perf--where-the-cpu-time-actually-goes)
   - [`codemod` — migrating a suite off `jest-auto-spies`](#codemod--migrating-a-suite-off-jest-auto-spies)
   - [`init` — the pointer an agent reads](#init--the-pointer-an-agent-reads)
 - [Using this library with an AI agent](#using-this-library-with-an-ai-agent)
@@ -138,6 +142,8 @@ includes — that one import is what keeps `returnSubject()` typed as rxjs's own
 - [Angular on Bun (`bun:test`)](#angular-on-bun-buntest)
 - [Comparison](#comparison)
   - [@testing-library/angular /vitest-utils](#testing-libraryangular-vitest-utils)
+- [Benchmarks](#benchmarks)
+  - [Reproducing the numbers](#reproducing-the-numbers)
 - [Migrating from jest-auto-spies](#migrating-from-jest-auto-spies)
 - [Migrating from jasmine-auto-spies](#migrating-from-jasmine-auto-spies)
 - [Migrating from @ngneat/spectator](https://asdalexey.github.io/vitest-auto-spy/migrating-spectator)
@@ -217,7 +223,7 @@ all**, because Vite 7 calls `crypto.hash` (added in Node 20.12) and the run dies
 `TypeError: crypto.hash is not a function` before a spec loads. On Vitest ≤ 3 Node 18 is fine. Which
 version to actually run is measured in
 [Performance → Which Node version](https://vitest-auto-spy.dev/core/performance#which-node-version):
-the core is 9–15% faster from Node 24 on, and a cold import more than halves.
+the break is between 22 and 24, where a cold import more than halves.
 
 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`
@@ -238,12 +244,13 @@ them only for the matching entry point. The package itself has **zero runtime de
 | `rxjs`          | `vitest-auto-spy/rxjs` observable spies — `>=7`, **no upper bound** (the rxjs 8 line included); not needed to type-check a spy since 4.0.0 | yes       |
 | `@angular/core` | `vitest-auto-spy/angular` helpers                                                                                                          | yes       |
 
-## The CLI — `doctor`, `codemod` and `init`
+## The CLI — `doctor`, `perf`, `codemod` and `init`
 
 The package ships one executable, with no dependencies and nothing to configure:
 
 ```bash
 npx vitest-auto-spy doctor   # read-only. Exits 1 when it finds something
+npx vitest-auto-spy perf     # where the suite's CPU time goes. Always exits 0
 npx vitest-auto-spy codemod  # prints the migration diff. Writes nothing without --write
 npx vitest-auto-spy init     # writes the agent instructions pointer
 ```
@@ -291,6 +298,56 @@ spec tsconfigs still covered their specs.
 
 `doctor` never writes. There is no `--fix`.
 
+### `perf` — where the CPU time actually goes
+
+Vitest prints one summary line per run with a phase breakdown; it is the only place those numbers
+surface, and it is for the whole suite, not a file. `perf` reads the same numbers per file — through
+`TestModule.diagnostic()`, Vitest's own public accessor, via a reporter this package ships — and
+turns whichever phase dominates into a list of files and the rule that put them there. Nothing here
+parses terminal output, and it always exits 0: a slow suite is not a failing one.
+
+```bash
+npx vitest-auto-spy perf              # run the whole suite once and report
+npx vitest-auto-spy perf src/cli      # path passed through to Vitest as a file filter
+npx vitest-auto-spy perf --json out/perf.json  # re-analyse a report instead of running Vitest
+```
+
+```
+$ npx vitest-auto-spy perf src/cli
+vitest-auto-spy perf — /path/to/repo
+16 test files, 860ms wall clock, 17.30s of CPU time summed over the workers
+
+  phase               time    share
+  prepare            6.34s    36.7%
+  environment        5.46s    31.6%
+  setup              3.01s    17.4%
+  transform          1.19s     6.9%
+  import             879ms     5.1%
+  tests              411ms     2.4%
+
+info   perf-environment
+       Environment setup is 31.6% of the measured CPU time, against 2.4% in the test bodies. No
+       spec file could be proved DOM-free, so this names none; 109 were left undecided.
+       → Move what does not need a DOM to the `node` environment. …
+
+0 errors, 0 warnings, 2 notes
+```
+
+That is this repository's own suite: `perf` names zero DOM-free candidates and leaves the rest
+undecided, because `src/test-setup.ts` builds an Angular `TestBed` before every spec. The rule is
+deliberately one-sided — a spec is a candidate only when it, the setup files, and every module they
+import were read, none mentions a DOM name, and every package they import is on a short
+DOM-free allowlist. Anything the rule cannot resolve is **undecided**, never assumed safe: a false
+positive is somebody's suite failing on `document is not defined`.
+
+**The phase totals are CPU time summed across workers**, which is why 860ms of wall clock reads as
+17.30s of CPU above — the six phases are `environment`, `prepare`, `import`, `setup`, `tests` (all
+per file) and `transform` (whole run). Where the isolation finding suggests `test.isolate: false`,
+it links to this package's own memory measurements rather than repeating the numbers here — that
+flag trades per-file cleanup for memory that grows with the suite.
+
+Full reference, phase by phase and finding by finding: **[The CLI](https://asdalexey.github.io/vitest-auto-spy/utilities/cli)**.
+
 ### `codemod` — migrating a suite off `jest-auto-spies`
 
 ```bash
@@ -1129,6 +1186,178 @@ since 19.2.0 (2026-03-17), present in the tarball's `exports` map. That is a rea
 favour. Full write-up, including ng-mocks and Spectator:
 [Comparison → Angular](https://asdalexey.github.io/vitest-auto-spy/comparison#angular).
 
+## The spy engine
+
+A method spy is not a `vi.fn()`. It is this library's own mock function — one shared prototype
+carrying the whole `Mock` surface, call state allocated on the first call rather than at creation,
+and no entry in any global registry. `vi.fn()` assigns some twenty-five closures as own properties
+of every mock it creates and allocates six arrays up front, per method, on every double a spec
+builds; on a service whose methods a test mostly never calls, that is the bill.
+
+Everything a spec can observe is unchanged, and the suite pins it by putting a spy and a `vi.fn()`
+through the same steps and comparing their state:
+
+- `vi.isMockFunction`, every `expect` matcher (`toHaveBeenCalledWith`, `toHaveReturned`,
+  `toHaveResolved`, `toHaveBeenNthCalledWith`, …), and the failure messages that name the mock.
+- `spy.method.mock.calls` / `.results` / `.settledResults` / `.instances` / `.contexts` /
+  `.lastCall`, the whole `mockReturnValue` / `mockResolvedValue` / `mockImplementation` family,
+  `withImplementation`, `mockClear` / `mockReset` / `mockRestore`, `mockName`, `using`.
+- `vi.clearAllMocks()`, `vi.resetAllMocks()`, and the `clearMocks` / `mockReset` config keys, which
+  Vitest applies through those two.
+
+It is measured in bytes as well as microseconds. A materialised method went from **5 445 B to
+1 929 B** — the hand-written control, which is the runner's own mock with no library in the way,
+retains 5 169 B — and an eagerly built double that nothing calls went from 4 418 to **632 B per
+method**, because a spy that is never called now allocates none of the six arrays `vi.fn()`
+allocates up front. Full tables:
+[Performance → retained memory per double](https://asdalexey.github.io/vitest-auto-spy/core/performance#retained-memory-per-double).
+
+**The one difference.** `mock.invocationCallOrder` counts on this library's own scale, so
+`expect(a).toHaveBeenCalledBefore(b)` is exact between two auto-spies and meaningless between an
+auto-spy and a hand-written `vi.fn()`. If a suite needs that comparison, switch the run back:
+
+```ts
+// vitest.setup.ts
+import { setSpyEngine } from 'vitest-auto-spy/setup';
+
+setSpyEngine('runner'); // every double built afterwards uses vi.fn() per method
+```
+
+The switch is Vitest-only. On Bun and `node:test` the runner's own matchers recognise only the
+runner's own mocks, so those entries keep building spies from `mock()` and `t.mock.fn()`.
+
+## Benchmarks
+
+Wall-clock at suite scale is the noisiest thing here, and the noise does not disappear inside a
+single invocation: the suite harness prints its own widest round-to-round spread, and in the run
+below that was **16%** of the cell's median — the three rounds of the 1 000-test cell came out at
+1.35 / 1.33 / 1.32 s and the 10 000-test cell at 10.02 / 10.65 / 9.72 s. Peak RSS, by contrast,
+reproduces tightly and separates arms by multiples. Treat the ratios below as the durable figure and
+any single wall-clock number as describing one machine, not a promise about yours.
+
+**The micro-benchmark below has the same problem, measured directly.** Every micro figure is the
+**median p75 of seven independent runs**, each its own process, at doubled iteration budgets, run
+with `npm run bench:vs:precise` — not a single run. What each row's ± column reports is how far that
+published median can be off: across the 47 rows of the 2026-09-04 run, a median of **±0.9%** and at
+worst **±6.3%** — on the `calledWith` dispatch row, the fastest and therefore the one closest to the
+stand's own floor. The blunter rule still holds for reading a single local run — **a difference under
+about 20% is not worth quoting** — and the narrowest margin below is 2.19×.
+
+`jest-auto-spies@3.0.1`, `jasmine-auto-spies@8.0.1` and `@bugsplat/vitest-auto-spies@1.0.0` are all
+measured directly here — no more standing in for one another. All three depend on
+`@hirez_io/auto-spies-core@3.0.0` and differ only in the spy factory they hand it (`jest.fn()`,
+`jasmine.createSpy()`, `vi.fn()`), and on the micro-benchmark they land within a few per cent of each
+other on every case — see the 40-methods/3-called row in
+[Performance](https://asdalexey.github.io/vitest-auto-spy/core/performance#micro-benchmark).
+`jest-auto-spies` and `jasmine-auto-spies` run here under a minimal `jest` / `jasmine` global backed
+by `vi.fn()`, so every arm creates the same underlying mock and the runner's own per-mock cost is a
+shared constant — what these numbers describe is each library's own code, not what a real Jest or
+Jasmine suite would show.
+
+The micro-benchmark runs every arm inside a block to the same iteration count (`n`), not the same
+time budget — these cases allocate doubles by the tens of thousands, and GC cost scales with objects
+created rather than elapsed time, so a fixed time budget would have handed a faster arm more
+allocations and made it pay for its own speed.
+
+**Every micro-benchmark table is this library's**, and the margin is against the *best* other arm in
+that table. The three class sizes are measured project profiles, not round numbers — across four
+private Angular suites (~2 700 spec files, 2 742 doubles built from a class) the median service has
+5-8 methods and the spec touches 1 of them:
+
+| Case (micro) | 4.0 | 4.1 | best other arm | lead |
+| --- | ---: | ---: | ---: | ---: |
+| small project — 6 methods, 1 called | — | **1.42 µs** | 6.83 µs hand-written | 4.82x |
+| medium project — 14 methods, 2 called | — | **2.67 µs** | 15.92 µs hand-written | 5.97x |
+| large project — 45 methods, 2 called | — | **5.79 µs** | 52.79 µs hand-written | 9.11x |
+| worst case — all 14 of 14 methods called | 18.92 µs (0.66x, a loss) | **8.17 µs** | 17.92 µs hand-written | 2.19x |
+| worst case — all 45 of 45 methods called | 75.33 µs (0.71x, a loss) | **26.12 µs** | 62.04 µs hand-written | 2.37x |
+| double from a type — 2 / 10 / 40 members | 3.58 / 18.17 / 72.88 µs (a loss) | **1.00 / 4.67 / 18.92 µs** | 2.79 / 13.83 / 56.79 µs vitest-mock-extended | 2.79-3.00x |
+| deep double, 3 levels, leaf called | 8.83 µs (0.61x, a loss) | **2.29 µs** | 5.46 µs vitest-mock-extended | 2.38x |
+| configure a return + 3 calls — class / type | 3.29 / 2.08 µs (type a loss) | **2.21 / 0.71 µs** | 16.38 µs hand-written / 1.58 µs @golevelup | 7.41x / 2.24x |
+| `calledWith` dispatch, 2 configured + 1 miss | 0.54 µs (parity) | **0.17 µs** | 0.54 µs vitest-mock-extended | 3.25x |
+
+Six of those rows were losses and one was parity. What changed is that a method spy is no longer a
+`vi.fn()` — see [The spy engine](#the-spy-engine) — plus one thing that is not the engine: a
+`calledWith(x)` of a single primitive argument used to be rendered into a string key on *every call*
+of that spy, where a `Map` keyed by the value does the same lookup with no allocation.
+
+The three class sizes changed in the same release, from round numbers to measured profiles, so the
+first two columns are the same operation on a slightly different class where the row says so. Part
+of the lead is that this library no longer pays the runner's per-mock cost while every other arm
+still does — a difference in the product rather than in the measurement, and the `hand-written
+vi.fn() per method` arm is in the table precisely so its size stays visible.
+
+**Where it still loses, same weight, same table** (`npm run bench:suite`, re-measured 2026-09-04 on
+the 4.1 build, 20-method class, `isolate: true`, coverage on, 3 rounds per cell after a discarded
+warm-up, medians of the three):
+
+| Comparison | 1 000 tests | 3 000 tests | 10 000 tests |
+| --- | ---: | ---: | ---: |
+| vitest-auto-spy | 1.33 s | 2.86 s | 10.02 s |
+| hand-written `vi.fn()` | 1.31 s (0.99×) | 2.85 s (1.00×) | 9.25 s (0.92×) |
+| @bugsplat/vitest-auto-spies | 2.00 s (1.50×) | 4.61 s (1.61×) | 15.45 s (1.54×) |
+
+Hand-written doubles are still cheaper — **about 3% at the median**, down from 10-15% before 4.1,
+with the nine per-round ratios spread 0.84-1.00 — and that row is the proof that micro-benchmark
+multipliers do not transfer to suite scale: building a double is on the order of 1% of a test's cost,
+so a 10× win on the double shows up as a few per cent on the run, and nearly everything else in a
+suite swamps it.
+
+**Memory, `isolate: false`, 100-method class, 10 000 tests, peak RSS:**
+
+| Arm | Peak RSS |
+| --- | ---: |
+| hand-written `vi.fn()` | 6366 MB |
+| vitest-auto-spy, default | 2103 MB |
+| vitest-auto-spy, `lazySpies: 'proxy'` | 1851 MB |
+
+Hand-written doubles use 3.0x the default's peak RSS here — the difference between finishing and an
+OOM'd worker on a large suite.
+
+That gap traces down to a single double: on the same 100-method class, untouched, `lazySpies:
+'proxy'` retains **4 097 B** per double against a hand-written double's **414 462 B** — the
+per-double number that gets multiplied by every double a file holds alive, and the setting that
+decides whether a large suite survives `isolate: false`. Full retained-memory tables:
+[Performance](https://asdalexey.github.io/vitest-auto-spy/core/performance#retained-memory-per-double).
+
+**Guidance keyed to suite size:** `isolate: false` is worth about 4x on its own — more than any
+library choice measured here — and it makes memory, not wall-clock, the binding constraint. On a
+wide class under `isolate: false`, add `lazySpies: 'proxy'` for roughly another 12% off peak RSS. Do
+not turn `'proxy'` on under normal isolation (`isolate: true`): there it measurably does nothing — a
+median of exactly 1.00× across five rounds.
+
+Full write-up, methodology and the complete suite-scale tables:
+[Performance](https://asdalexey.github.io/vitest-auto-spy/core/performance).
+
+### Reproducing the numbers
+
+Node **>=18** (the project floor); the numbers above were captured on Node v24.19.0. The steps are
+identical on Windows, macOS and Linux — same Node, same npm, same commands, nothing OS-specific to
+call out:
+
+```bash
+git clone https://github.com/ASDAlexey/vitest-auto-spy.git
+cd vitest-auto-spy
+npm ci
+npm ci --prefix bench
+npm run bench:vs
+```
+
+Two installs are intentional: the competitor packages live in `bench/package.json`, kept out of the
+root so it carries nothing it doesn't ship or test with, and `bench/.npmrc` pins
+`legacy-peer-deps=true` so npm doesn't install a second copy of `vitest` beside the root one — two
+copies would mean two mock registries and the run dies out of memory.
+
+`npm run bench:vs` is the micro-benchmark, a single run in about a minute — the right form for
+local iteration. `npm run bench:vs:precise` is what produced the median p75 figures published
+above, about eleven minutes for seven independent runs in seven processes. For the suite-scale tables, see
+`npm run bench:suite --help` — it takes **tens of minutes at 10 000 tests**, so budget for that
+before running it locally.
+
+The same benchmark also runs in CI — on a monthly schedule, on any pull request touching `bench/**`
+or `src/lib/**`, and on demand — so a run you didn't trigger yourself is checkable in
+[Actions → Benchmarks](https://github.com/ASDAlexey/vitest-auto-spy/actions/workflows/bench.yml).
+
 ## Migrating from jest-auto-spies
 
 The public API is intentionally identical. In most projects the migration is a
@@ -1648,9 +1877,9 @@ beforeEach(() => {
 
 > **Lazy by default, everywhere.** Every factory builds each method spy on first access
 > (`lazySpies: true`), since Angular tests typically spy a wide service but call
-> only a few of its methods — roughly **4× faster** spy assembly (≈8× on a
-> 20-method service). Behaviour is unchanged; pass `{ lazySpies: false }` to build
-> every spy eagerly.
+> only a few of its methods — and the margin widens as the class does: **1.4×** on a ten-method
+> class a test calls twice, **1.9×** on a forty-method one it calls three times. Behaviour is
+> unchanged; pass `{ lazySpies: false }` to build every spy eagerly.
 
 #### Signal / readonly property mocking (bonus)
 
@@ -1717,46 +1946,24 @@ const { fixture, component } = renderShallow(TaskListComponent, {
 
 `fixture` is a real `ComponentFixture`; nothing here replaces `@angular/core/testing`.
 
-**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** — the seven untouched files in the same batch moved
-by ±10%, which is this suite's run-to-run noise, so the two wins are outside it and the one
-regression is only just outside.
-
-**Why 1.7× and not more.** That row is a whole spec file's wall clock — imports, the `TestBed`
-module, the assertions — of which rendering is only a part. Isolated to the render itself, the
-saving tracks the size of the subtree removed, measured on 2026-08-26 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× |
-
-`renderShallow` is flat at ~0.5 ms because it never builds the subtree; `createComponent` scales
-linearly with it. So there is no single "renderShallow is N× faster" number — a leaf component has
-nothing to save, and a table or a dashboard is an order of magnitude. Treat the ratios as the
-result, not the absolute times, and pick files to convert with the diagnostics below rather than by
-guessing. `keepTemplate: true` is the middle rung — the component's own template with an empty
-subtree, 1.933 ms → 1.074 ms (1.8×), measured 2026-08-30. Full write-up:
+**What it saves.** The shape is the point: `renderShallow` is flat in the number of children,
+because it never builds the subtree, while `TestBed.createComponent` scales linearly with it. So the
+win is not a fixed percentage and there is no single "renderShallow is N× faster" number — on a leaf
+component with no children there is nothing to remove, and the per-test `overrideComponent` can cost
+more than it saves; on a table or a dashboard the two curves are nowhere near each other. A
+per-render ratio is also the upper bound on what a whole spec file can gain rather than a prediction
+of it: a file's wall clock pays for imports, the `TestBed` module and the assertions too, none of
+which shallow rendering touches.
+
+`keepTemplate: true` is the middle rung — the component's own template with an empty subtree.
+`buildOverride` applies `imports: keepChildren ?? []` whether or not the template is kept, so with
+`keepTemplate: true` the template renders while every child in it resolves to nothing under
+`NO_ERRORS_SCHEMA`. Reach for it when the spec reads something the template creates, and keep
+`keepChildren` for the handful of children it genuinely needs resolvable. Full write-up:
 [Performance](https://asdalexey.github.io/vitest-auto-spy/core/performance#_2-rendering-the-child-subtree).
 
 Use [the diagnostics](#where-a-spec-spends-its-time) to find the files worth converting rather than
-guessing: across those ten files `TestBed` accounted for 820 ms of 3231 ms (25%), but per file the
-share ranged from 13% to 66%.
+guessing.
 
 #### Building a class with auto-spied dependencies
 
@@ -2140,11 +2347,12 @@ Reach for `provideAutoSpy` on Angular and `createSpyFromClass` everywhere else;
 whose members live on the instance) and `createMock<T>(partial)` for a data shape the code only
 reads.
 
-None of it is worth optimising. On a ten-method class: `provideAutoSpy` ~8 µs per call,
-`createSpyFromClass` ~29 µs, `createAutoMock` ~33 µs, a `calledWith` lookup ~0.7 µs — five
-providers across two thousand tests come to under a tenth of a second for the whole suite.
-`provideAutoSpy` leads because it defaults to `lazySpies: true`, and prototype discovery is
-cached per class either way. Full numbers and the two settings that do cost something are in
+None of it is worth optimising. On a ten-method class a test calls two methods of:
+`createSpyFromClass` **2.25 µs** per call, `createAutoMock` plus four accesses **1.79 µs**, a
+`calledWith` dispatch of three configured calls **0.21 µs** — five providers across two thousand
+tests is ten thousand calls, about two hundredths of a second for the whole run. `provideAutoSpy`
+is the same factory with the same lazy default, and prototype discovery is cached per class either
+way. Full numbers and the two settings that do cost something are in
 [Performance](https://asdalexey.github.io/vitest-auto-spy/core/performance).
 
 ## Utilities
@@ -2211,6 +2419,7 @@ single-purpose utility you can pick up independently — they all ride on the sa
 | `restoreTimerGlobals()`                                                                  | `/setup`                      | Put back timer globals that uninstalling the fakes deleted rather than restored                                                                                                                       |
 | `trackMockRegistry()` / `keepMockRegistered(mock)` / `restoreLongLivedImplementations()` | `/setup`                      | Keep @vitest/spy's mock registry to the mocks that outlive a file; mark one the split would miss; put back an implementation a cross-file `vi.resetAllMocks()` dropped ([details](#test-run-hygiene)) |
 | `trackNodeMocks()` / `pruneNodeMocks()` / `countNodeMocks()`                             | `/node`                       | Give this library its own `node:test` `MockTracker` so a dropped spy is freed — 21× less retained heap; sweep by hand, and read the count back                                                        |
+| `setSpyEngine(engine)` / `getSpyEngine()`                                                | `/setup`                      | Build method spies from this library's own mock (`'auto-spy'`, the default) or from `vi.fn()` (`'runner'`) ([details](#the-spy-engine))                                                               |
 | `errorHandler`                                                                           | core                          | The `mustBeCalledWith` argument-mismatch reporter — swap it to customize failure output                                                                                                               |
 
 A taste of the DI pair — provide the spy, inject it back fully typed:
@@ -2871,7 +3080,7 @@ as `methodsToSpyOn`, named for callables that live on the instance — `signal()
 `gettersToSpyOn`, `settersToSpyOn`, `autoSpyAccessors` (discover every getter/setter),
 `fillMissing` (answer a name the prototype never carried with a spy — for a **partially** abstract
 class, where `abstract` members are erased and the empty-prototype fallback no longer fires),
-`lazySpies` (materialize method spies on first access — cheaper for wide classes; the `provideAutoSpy` default on Angular. `'proxy'` keeps the laziness and drops the per-method placeholder: 11.8 kB retained against 101.6 kB on a 400-method class, at +30 ns per read — opt-in, and worth it only above ~20 methods)
+`lazySpies` (materialize method spies on first access — cheaper for wide classes; the `provideAutoSpy` default on Angular. `'proxy'` keeps the laziness and drops the per-method placeholder — no memory crossover at any width measured, lighter than the default from 10 methods up (4 097 B vs the default's 25 601 B per double retained, untouched, on a 100-method class); it costs +30 ns per read once a method has materialised, which only pays back in **time** on classes above ~20 methods — see [Performance](https://asdalexey.github.io/vitest-auto-spy/core/performance#retained-memory-per-double))
 
 `ValueConfig` (for `nextWithValues`): `{ value, delay? }` | `{ errorValue, delay? }` | `{ complete?, delay? }`.