vitest-auto-spy 4.0.0 → 4.1.0

package/AGENTS.md

@@ -261,9 +261,10 @@ 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
+Building a spy is not a thing to optimise. On a ten-method class, Node 24, `npm run bench`:
+`createSpyFromClass` plus two methods called ~2.3 µs, plus all ten ~6 µs, `createAutoMock` plus four
+members ~1.7 µs, a `calledWith` lookup ~0.2 µs — five providers across two thousand tests is a
+hundredth 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.
@@ -1053,6 +1054,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
@@ -2072,6 +2115,14 @@ stubbed a since-renamed method was passing over nothing and will now fail. Full
   `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 +2572,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)
@@ -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)
@@ -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,175 @@ 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 varies **15-20% between invocations** of the identical configuration —
+the same cell measured 1.56 s and 1.33 s at 1 000 tests, 10.94 s and 12.51 s at 10 000. 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 canonical run, a median of **±1.1%** and at
+worst **±3.8%**. 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-03 on
+the 4.1 build, 20-method class, `isolate: true`, coverage on, two runs of 3 rounds each, medians of
+all six):
+
+| Comparison | 1 000 tests | 3 000 tests | 10 000 tests |
+| --- | ---: | ---: | ---: |
+| vitest-auto-spy | 1.33 s | 3.19 s | 10.66 s |
+| hand-written `vi.fn()` | 1.33 s (0.99×) | 3.08 s (0.97×) | 10.07 s (0.94×) |
+| @bugsplat/vitest-auto-spies | 2.21 s (1.66×) | 5.50 s (1.72×) | 17.40 s (1.63×) |
+
+Hand-written doubles are still cheaper — **about 5% at the median**, down from 10-15% before 4.1,
+with the 18 per-round ratios spread 0.81-1.01 — 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()` | 6733 MB |
+| vitest-auto-spy, default | 2475 MB |
+| vitest-auto-spy, `lazySpies: 'proxy'` | 2109 MB |
+
+Hand-written doubles use 2.7x 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 3x 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 about 15% less peak RSS. Do not turn
+`'proxy'` on under normal isolation (`isolate: true`): there it measurably does nothing (5/7 rounds
+either side of parity).
+
+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 55 seconds — the right form for
+local iteration. `npm run bench:vs -- --repeat 5` is what produced the median p75 figures published
+above, about 4.5 minutes for five independent runs in five 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
@@ -2211,6 +2437,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 +3098,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? }`.