({ id: '1', header: { title: '', subtitle: 'none' }, tags: [], publishedAt: new Date(0), }); // in a spec — name only what this test is about const draft = anArticle({ header: { title: 'Draft' } }); // header.subtitle survives ``` `defaults` is a **complete** `T`, and that is the point rather than a chore: a field the model dropped six months ago fails in one place instead of in eight copies nobody re-checks. `Partial` and `as T` both delete that diagnostic. Overrides are deep-partial-checked and merge leaf by leaf; an overridden array replaces the default one outright. Every call returns a **new object**, and the defaults are copied when the factory is built — a fixture shared by reference is the most common way one test's mutation decides another's outcome, and under `isolate: false` that reaches across files. The copy is deep through plain objects and arrays and stops there: a `Date`, a `Map` or a class instance is carried across by reference rather than rebuilt without its prototype. For defaults that _are_ a class instance with getters, snapshot them with `withOverrides()` first. ## 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(); ``` **The first line and the second do not layer.** `mockReturnValue` and its family (`mockImplementation`, `mockResolvedValue`, `mockRejectedValue`, `mockThrow`, `mockReturnThis`) install an implementation on the host mock, and the dispatch that reads a `calledWith` chain **is** the implementation they replace — so the one written later wins outright and the other decides nothing, in either order, without failing. Both orders are now reported as a misconfiguration (a warning, a throw under the `strict` preset). Where both are wanted, the fallback goes in the spy's own container, which a chain still wins over: the `returns` option where the double is built, or `resolveWith` / `nextWith` / `failWith`. The report comes from this library's own spy engine — so Vitest and Rstest, not Bun or `node:test`, and not under `setSpyEngine('runner')` — and the `Once` family is never reported, because its queue drains back onto the dispatch. The failure prints both sides, because the diagnosis is the comparison rather than either half of it — and every configured call when there is more than one, matchers included, so a config that never matched is visible instead of inferred: ``` The function 'getName' was configured with 'mustBeCalledWith' and expects to be called with specific arguments. Wanted: getName(1) Actual: getName(2) ``` ### Matching order, and re-configuring the same arguments An exact argument list is matched first; the asymmetric configs (`expect.any(Number)`, `expect.objectContaining({ … })`, …) are then tried in the order they were registered, so a narrow config placed before a wide one keeps its calls. Registering the **same** argument list again replaces the answer it gave before — matcher arguments included: ```ts myService.getName.calledWith(expect.anything()).mockReturnValue('first'); myService.getName.calledWith(expect.anything()).mockReturnValue('second'); expect(myService.getName(1)).toBe('second'); ``` Each `expect.anything()` is a new object, so the two are compared by what they accept rather than by identity — same matcher class, same sample, same inversion. A hand-rolled `{ asymmetricMatch }` object is the exception: its verdict lives in a closure nothing can read, so two of them are always two configs and only the very same instance, re-registered, overrides. **A matcher counts wherever it sits.** `calledWith({ id: expect.any(Number) })` and `calledWith([expect.any(String)])` are matched structurally — a matcher nested in an object, an array, a `Map` value or a `Set` member decides that position, where the whole argument used to be serialised as data and matched nothing at all (while `mustBeCalledWith` threw on the _correct_ call). The same comparison settles the rest of the argument: a `Map` and a `Set` compare without regard to order, a `Date` by its time, an `Error` by its `name` and `message`, a function by identity, and symbol keys count like string ones. A graph with a back-edge is a legal argument. That also tells apart things that used to share one key and answer for each other: two anonymous callbacks, two `Error`s of different messages, a `Set` built in a different order, an object whose keys were forged as strings. A suite green for one of those reasons goes red on the upgrade, which is the point. ```ts const found = users.load.calledWith(1); // each call hands back its OWN handle users.load.calledWith(2).mockReturnValue(undefined); found.mockReturnValue({ id: 1 }); // configures 1 — it used to configure 2 ``` `new` works on a method spy as well, so `new sdk.Client()` — the shape `createAutoMock` and `mockDeep` produce — hands back the instance instead of `… is not a constructor`. ## Promise-returning methods ```ts myService.getProducts.resolveWith([{ name: 'Product 1' }]); await expect(myService.getProducts()).resolves.toEqual([{ name: 'Product 1' }]); myService.getProducts.rejectWith('FAKE ERROR'); await expect(myService.getProducts()).rejects.toBe('FAKE ERROR'); // per-call values, and conditional-by-args myService.getProducts.resolveWithPerCall([{ value: ['a'] }, { value: ['b'] }]); myService.getProducts.calledWith(1).resolveWith(['one']); ``` ## Observable-returning methods & Observable properties Both spied **methods** that return an `Observable` and spied **properties** of type `Observable` get the same control surface. Enable them by importing the rxjs layer once: ```ts import 'vitest-auto-spy/rxjs'; ``` ```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(); subject.next([{ name: 'manual' }]); ``` `returnSubject()` and `nextWithPerCall()` are typed `SubjectOf`: rxjs's own `Subject` wherever `import 'vitest-auto-spy/rxjs'` is in the TypeScript program, and the structural `SubjectLike` (`next` / `error` / `complete` / `asObservable` / `closed`) where it is not. That is how the published declarations name no rxjs type while a suite that has rxjs keeps the exact type it had. The seam is one augmentable interface, `AutoSpyRxjsTypes`, which the `/rxjs` entry fills in; what decides that a member _is_ an observable is the other new type, `ObservableLike` — `subscribe` plus a promise-returning `forEach(next)`. `calledWith(...)` / `mustBeCalledWith(...)` also chain into the observable helpers: ```ts myService.getProducts$.calledWith(1).nextWith([{ name: 'Product 1' }]); ``` ### 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 }); ``` ## Getters & setters ```ts const spy = createSpyFromClass(MyService, { gettersToSpyOn: ['userName'], settersToSpyOn: ['userName'], }); // configure / assert the getter spy.accessorSpies.getters.userName.mockReturnValue('Fake Name'); expect(spy.userName).toBe('Fake Name'); // assert the setter was called spy.userName = 'New Name'; expect(spy.accessorSpies.setters.userName).toHaveBeenCalledWith('New Name'); ``` ## Resetting — `using`, `resetAutoSpy`, `clearAutoSpy` ```ts import { clearAutoSpy, resetAutoSpy } from 'vitest-auto-spy'; clearAutoSpy(service); // recorded calls only — configured returns survive resetAutoSpy(service); // calls AND configuration (calledWith / resolveWith / mockReturnValue) ``` Both cover method spies **and** accessor spies, on `createSpyFromClass` spies and `createAutoMock` proxies alike — reach for them instead of looping over methods calling `mockClear`. `resetAutoSpy` is `vi.resetAllMocks()` for one double, and two things it used to leave behind go with the rest now: a pending `mockReturnValueOnce` queue, which used to answer the first call _after_ the reset — in a later test — and an accessor spy's configuration, which used to hand the next test the previous test's value. A spec relying on a queued `Once` value outliving the reset reads `undefined`. The double stays usable: the library's dispatch is put back, so a fresh `calledWith` configures it as normal. Every double this package builds also carries a `[Symbol.dispose]()` that runs `resetAutoSpy(this)`, so the `afterEach` that existed only to reset one spy can go: ```ts it('loads', () => { using cart = createSpyFromClass(Cart); // reset when the block ends cart.total.calledWith().mockReturnValue(42); expect(cart.total()).toBe(42); }); // calls and configuration both gone ``` `createAutoMock` proxies and **every `mockDeep` node** carry it too, so `using api = mockDeep()` resets the whole tree, children included, and `using` on a sub-tree resets that sub-tree. The key is non-enumerable, so `{ ...spy }` does not carry it into a snapshot, and there is deliberately no `[Symbol.asyncDispose]` — `resetAutoSpy` is synchronous, and `await using` falls back to `@@dispose` anyway. **The method is ours; the `using` declaration is your toolchain's.** esbuild and `tsc` both downlevel the declaration. If your setup does not transpile, call `spy[Symbol.dispose]()` or `resetAutoSpy(spy)` directly. On **Node 22** the package installs the missing `Symbol.dispose` when it loads: the downlevelled form reads the symbol off the global `Symbol`, and Node 22 patches it in only on its main realm — under Vitest's `jsdom` environment, whose globals come from a `vm` context, it is absent and `using` throws `TypeError: Symbol.dispose is not defined.`. The shim is `Symbol.for('nodejs.dispose')`, the same registry symbol Node uses, so the key is identical across realms; a runtime that already has the symbol (Node 24+, Bun) is left untouched. A standalone `createFunctionSpy` is **not** covered: it is a host-runner mock, and Vitest puts its own `[Symbol.dispose]` on those, which restores the original implementation rather than reverting this library's configuration. ## Framework adapters The core is framework-agnostic — `createSpyFromClass` / `createAutoMock` work in any test. The subpaths below add a natural import and, where the framework has class DI, a tiny `provide*` helper. None of them pull the framework into this package; they're recipes over the same core. > The **Angular**, **NestJS**, **React**, **Vue/Pinia** and **Svelte** entry points are all published > ([Availability](#availability)). Each is a thin recipe over the same core, so you can equally copy it > using the core `vitest-auto-spy` import directly. ### Angular

Angular TestBed recipe: provideAutoSpy registers a typed spy provider and injectSpy returns Spy<ApiService> — no manual { provide, useValue }, no TestBed.inject<any> cast

`provideAutoSpy` is the shorthand for providing an auto-spy in a `TestBed`: ```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; 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 only need the usual Vitest + Angular wiring: > [`@analogjs/vite-plugin-angular`](https://www.npmjs.com/package/@analogjs/vite-plugin-angular) > plus a TestBed setup file (e.g. `@analogjs/vitest-angular`'s `setupTestBed()`). > **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 — 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) ```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 mockAccessorsProp(input, 'valueAsNumber', { get, set }); // …with real implementations behind them ``` Each helper also returns the undo for _its own_ patch, for a stub that has to come off inside a single test: ```ts const restoreNavigator = mockValueProp(globalThis, 'navigator', undefined); try { // … } finally { restoreNavigator(); } ``` Every one of them records the descriptor it overwrote, so a single `restoreMockedProps()` puts them all back. 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`: ```ts // test setup afterEach(() => restoreMockedProps()); ``` Members the public type does not describe (`#private` fields, ad-hoc keys) are accepted too — the helpers take a `PropertyKey` overload, so no `as never` dance. #### 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; resolved exactly as `setInputs` resolves them | | `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`. **`inputs` here and `setInputs` mid-test resolve a name the same way**, which they did not before. Both read the compiled definition, so an input renamed with an alias is set by its **class-field** name as well as its public one, and an input a `hostDirectives` entry exposes is accepted rather than refused with "It declares no inputs at all". A name the component does not declare is refused at the call, listing the ones it does — Angular's own answer to an undeclared name is an `NG0303` on the console and no change at all, so the spec used to fail several assertions later on state nothing moved. (`createComponentStub` does **not** copy `hostDirectives`, so an input exposed through one is not on a stub of that component.) **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. The override keeps the component's own `imports` minus the child _components_, so the template renders with its own pipes and directives working while every child component in it resolves to nothing under `NO_ERRORS_SCHEMA`. (Before 5.4.0 the whole scope was dropped, which made a pipe in a kept template throw `NG0302` and an attribute directive silently never apply.) Those imports are read off `ɵcmp`, where the compiler leaves them in one of three shapes — the flat array, a factory returning it, or `null` for a component that imports nothing — and which one is not decided by JIT against AOT: JIT always emits the factory, AOT emits the array unless a cycle between two components forces it to defer the read. All three are handled; calling the array unconditionally was a `TypeError: dependencies is not a function` on an AOT-compiled component with no cycle in its imports. A child re-exported by an imported `NgModule` still renders **under JIT**, where the module is in that list and is kept whole. Under AOT it is not: ngtsc resolves the module at compile time and flattens its exported declarations into the list, so a `standalone: false` pipe or directive is what arrives, and Angular takes only standalone declarations and `NgModule`s in `imports`. That scope cannot be rebuilt from what the definition holds, so `renderShallow` refuses it by name instead of letting Angular answer `The "X" pipe … is not standalone` — a message aimed at the pipe's author, about a pipe that is fine and that works under JIT. Drop `keepTemplate` when the spec reads TypeScript state only, or build the component with `TestBed` directly and keep its compiled scope. 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. #### Building a class with auto-spied dependencies ```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); ``` 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`, 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 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` is `TestBed.tick()`, run inside the `NgZone`. **Both work under zone.js, and the zone is why the tick is wrapped.** The name says zoneless and the helpers are written for it, but nothing in them is — `stable` and `setInputs` are the same two lines in a zone-based suite. `TestBed.createComponent` builds the component inside `ngZone.run(…)`, so an `effect()` its constructor registers records the zone's inner zone; a tick started from a test body runs in the runner's zone, hops back to run a **dirty** effect, and leaving that hop reports the zone stable mid-tick. `provideZoneChangeDetection()` — which the Angular CLI's unit-test builder installs for every suite that loads zone.js — answers that with `ApplicationRef._tick()`, guarded against its own scheduler but not against the tick already on the stack, which is `NG0101: ApplicationRef.tick is called recursively`. Running the tick inside the zone removes the hop. Measured on an Angular 22 suite of 1771 spec files: 451 `componentRef.setInput` calls rewritten to `setInputs` turned **57 green files red** on `NG0101`, and none of them after the fix. Under zoneless `NgZone` is a `NoopNgZone` whose `run` is a straight call, so it costs nothing there. The wait is bounded: `stable` gives the fixture **2000 ms** and then throws the cause, instead of letting the runner report a 5 s file-level timeout that names neither the helper nor the fixture. Pass `{ timeout, label }` to change either; `{ timeout: 0 }` waits indefinitely. The watchdog runs on a timer captured at import, and on zone.js's unpatched `setTimeout` where there is one, so neither `vi.useFakeTimers()` nor a `tick()` inside `fakeAsync` can reach it. #### Settling a `resource()` or `httpResource()` ```ts import { flushEffects, settleResource } from 'vitest-auto-spy/angular'; const products = TestBed.runInInjectionContext(() => httpResource(() => '/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]); ``` Angular's resource primitives need a **different wait each** — measured on 21.2.17, an `httpResource` settles one tick + one microtask after its flush, a plain `resource()` takes two rounds of the same, and neither has made a request at all until something ticks. Getting it wrong asserts against the resource's _default_ value, which is a green test proving nothing. `settleResource` is the loop both converge under, with a turn budget and a failure that names the resource and the flush it is missing. `flushEventLoopUntil` cannot do this: it takes real event-loop turns and never ticks, so a resource awaited through it finishes the budget having issued zero requests. #### Driving a resource with no HTTP at all ```ts import { mockResourceProp } from 'vitest-auto-spy/angular'; import { registerResourceMatchers } from 'vitest-auto-spy/angular/matchers'; const products = mockResourceProp(service, 'products', []); products.set([product]); // 'resolved' products.loading(); // back in flight products.fail('offline'); // 'error' — value() now THROWS, as a real resource does expect(products.reload).toHaveBeenCalled(); // reload is spied and re-issues nothing ``` Everything above is the answer when the request _is_ the point. Often it is not — the spec is about the component's own logic and the value was chosen in advance. `mockResourceProp` replaces the property with a double the spec moves directly, so nothing is ever in flight: no tick, no `HttpTestingController`, no budget. It is built from real `signal()`s, so a `computed()` reading `products.value()` still recomputes and an `effect()` still runs. Undone by `restoreMockedProps()`. **The double is no more forgiving than the real thing**, in two places where it used to hide a defect. `value()` read after `fail(reason)` throws a `ResourceValueError` carrying the reason on `cause` and naming the property — branch on `hasValue()` / `status()` first, or assert with `toHaveResourceError()`. And `reload()` answers `false` while the resource is `'idle'` or `'loading'`, as Angular's does, rather than a constant `true`. And `registerResourceMatchers()` adds `toBeLoading` / `toHaveResourceValue` / `toHaveResourceError`, which read the value **and** the status. `toHaveResourceValue` is the one that earns its place: it fails an unresolved resource **even when its default value matches**, which is exactly the assertion `expect(products.value()).toEqual([])` lets through. These matchers — and `toHaveFocus`, and `toHaveDirectiveApplied` — **throw** on an argument of the wrong type instead of reporting a failure. A reported failure is a pass under `.not`, so `expect(products.value()).not.toBeLoading()` (the value, not the resource), `expect(missingEl).not.toHaveFocus()` (a query that found nothing) and `expect(undefined).not.toHaveDirectiveApplied(X)` were three green assertions about nothing. #### Asserting a signal's value ```ts import { registerSignalMatchers } from 'vitest-auto-spy/angular/matchers'; 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, and rejects anything that is not a zero-argument getter, so the missing-parentheses mistake fails instead of quietly passing. #### Where a spec spends its time ```ts // vitest.setup.ts import { enableTestBedDiagnostics } from 'vitest-auto-spy/angular/diagnostics'; 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. Pass `report` to collect the timings yourself, `minTestBedMs` to stay quiet about cheap files, and call `disableTestBedDiagnostics()` to put 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. #### A provider the component declares for itself A testing-module provider **loses** to one the component declares in its own `@Component({ providers: [...] })` — a route-scoped service, a per-component store, a `provideX()` helper — and it loses silently. `overrideComponentProvider` queues the component with the TestBed compiler (as an `imports` entry when it is standalone, `declarations` otherwise), overrides the provider, and hands the spy back: ```ts import { overrideComponentProvider } from 'vitest-auto-spy/angular'; const menu = overrideComponentProvider(CatalogPageComponent, NavigationBuilderService); // → Spy<…> menu.build.mockReturnValue([]); const fixture = TestBed.createComponent(HostComponent); // ← the override is verified here ``` Queuing the component removes the _usual_ cause of a silent no-op; it does not prove the override landed, so the helper checks. On the next `TestBed.createComponent` the component's **own** injector is asked for the token, and a mismatch throws naming the component, the token and what was resolved instead. The check is always on, not a diagnostics flag: it cannot fire in a spec that never called the helper, and it stays silent when the component was not rendered. It covers the **first** `createComponent` only — the wrapper unhooks itself after one fixture — and a later competing `TestBed.overrideProvider` still wins, which it reports but cannot prevent. [Details](https://asdalexey.github.io/vitest-auto-spy/adapters/angular-overrides). #### Diagnostics — five silent failures made loud ```ts // vitest.setup.ts — AFTER getTestBed().initTestEnvironment(…) import { enableAngularDiagnostics } from 'vitest-auto-spy/angular/diagnostics'; enableAngularDiagnostics(); // all five enableAngularDiagnostics({ pendingRequests: false }); // or pick ``` | Member | Fails when | | ------------------- | ------------------------------------------------------------------------------------------------------ | | `ngModuleScopes` | a testing module imports an NgModule that contributes nothing at all at runtime | | `deadSchemas` | `schemas` sit next to a standalone component, where they can never apply | | `unspiedProviders` | `injectSpy` gets a real instance — a `console.warn` on its own, a throw in the group | | `shadowedProviders` | a double on the testing module loses to the component's own `providers` — the test runs the real thing | | `pendingRequests` | a test ends with unflushed `HttpTestingController` requests | Each has the same shape: something the spec wrote does nothing, nothing says so, and the test passes for a reason its author did not intend. Every member defaults to `true`; a second call **replaces** the previous selection, and `disableAngularDiagnostics()` turns the group off. `assertNoPendingRequests()` is the HTTP check on its own, for use mid-test, and `assertNoShadowedProviders(component, fixture)` is the shadow check on its own — a no-op when the fixture never rendered that component, and when everything it resolved is a double. Order matters: Vitest runs `afterEach` in reverse registration order, so the group has to be registered _after_ the Angular test environment whose teardown it inspects. `@angular/common/http/testing` is never imported — the token is read out of your own `provideHttpClientTesting()` / `HttpClientTestingModule` configuration, so a project that configures neither is silently inert. [Details, and what each check deliberately misses](https://asdalexey.github.io/vitest-auto-spy/adapters/angular-diagnostics). #### Which collaborators the code asked for ```ts import { trackInjections } from 'vitest-auto-spy/angular'; // same function on /nestjs const collaborators = trackInjections([FeatureFlagService, ANALYTICS_TOKEN]); TestBed.configureTestingModule({ providers: [CheckoutFacade, ...collaborators.providers] }); collaborators.get(FeatureFlagService).isOn.mockReturnValue(true); TestBed.inject(CheckoutFacade).start(); expect(collaborators.names()).toEqual(['FeatureFlagService']); // analytics was never asked for ``` The assertion behind most `vi.mock('@app/services')` calls is not "this module was replaced" — it is _which collaborators did this entry point ask for_, and a provider factory runs exactly when something injects its token. DI is a seam the build has to keep, where a barrel a bundler already inlined is not. The log also carries the doubles (`get(token)` → `Spy`, built eagerly so a spec can stub one first), `injectedTokens()` in the order the factories ran, `wasInjected(token)` and `reset()` for the record alone. [Details](https://asdalexey.github.io/vitest-auto-spy/utilities/track-injections). #### An `ActivatedRoute` whose halves agree — `vitest-auto-spy/angular-router` ```ts import { injectActivatedRoute, provideActivatedRoute } from 'vitest-auto-spy/angular-router'; TestBed.configureTestingModule({ providers: [provideActivatedRoute({ params: { id: '7' }, queryParams: { tab: 'reviews' } })], }); const fixture = TestBed.createComponent(ProductPage); // reads snapshot.params, paramMap, queryParams — all agree injectActivatedRoute().setParams({ id: '8' }); // params and paramMap emit; snapshot.params is already { id: '8' } ``` `ActivatedRoute` keeps its streams and its snapshot in instance fields, so `provideAutoSpy(ActivatedRoute)` has neither, and a hand-written `useValue` usually has one half — the component that reads the other gets `undefined`, or a spec tests a route no navigation can produce. The double here is Angular's own `ActivatedRoute` over one record: `params`, `queryParams`, `data`, `fragment`, `url`, both `ParamMap`s and `snapshot` come from the same values, and each setter (`setParams`, `setQueryParams`, `setData`, `setFragment`, `setUrl`, or `set({ … })` for several at once) rebuilds the snapshot first and then emits what changed, in the router's order and with its equality. It is a real route to the real `Router` too: `relativeTo` resolves against its `url`. `createActivatedRoute()` builds one without a `TestBed`. `@angular/router` is an **optional** peer, reached by this entry only. [Details](https://asdalexey.github.io/vitest-auto-spy/adapters/angular-router). ### NestJS Use `provideAutoSpy` to register a fully-mocked service in a `TestingModule`, then `injectSpy` to pull it back out already typed as `Spy`. `@nestjs/common` / `@nestjs/testing` are your own (optional) peers — the helper imports neither: ```ts import { Test, type TestingModule } from '@nestjs/testing'; import { beforeEach, expect, it } from 'vitest'; import { injectSpy, provideAutoSpy } from 'vitest-auto-spy/nestjs'; import { AuthService } from './auth.service'; import { UserService } from './user.service'; let moduleRef: TestingModule; let userServiceSpy: Spy; beforeEach(async () => { moduleRef = await Test.createTestingModule({ providers: [AuthService, provideAutoSpy(UserService)], }).compile(); userServiceSpy = injectSpy(moduleRef, UserService); }); it('logs in a known user', () => { userServiceSpy.findByEmail.mockReturnValue({ id: 1, name: 'Ada' }); const auth = moduleRef.get(AuthService); expect(auth.login('ada@example.com')).toBeTruthy(); expect(userServiceSpy.findByEmail).toHaveBeenCalledWith('ada@example.com'); }); ``` When the class under test does not need a `TestingModule` at all, build it from its own metadata — the provider list is derived, so a constructor change does not touch the spec: #### `httpResource()` and `HttpClient` — `vitest-auto-spy/angular-http` ```ts import { expectRequest, provideHttpTesting } from 'vitest-auto-spy/angular-http'; beforeEach(() => { TestBed.configureTestingModule({ providers: [...provideHttpTesting()] }); }); it('loads the products', async () => { const products = TestBed.runInInjectionContext(() => httpResource(() => '/api/products')); await expectRequest('/api/products').flush([product]); expect(products.value()).toEqual([product]); // no tick, no microtask, no detectChanges }); ``` `expectRequest` ticks before it looks — an `httpResource()` has issued nothing until something does — and `flush()` / `error()` settle before they resolve, which is why the value reads on the next line. Match by URL (either `url` or `urlWithParams`), by `RegExp`, or by a predicate over the request, with `{ method }` to tell a read from a write. `provideHttpTesting()` fails, by default, any test that ends holding a request nothing answered; `provideHttpTesting({ verifyOnTeardown: false })` turns that off, and `verifyNoPendingRequests()` runs the same check by hand. It is a separate entry because it is the only part of the package that imports `@angular/common` — an **optional** peer, so `vitest-auto-spy/angular` keeps loading in a project that does not have it. Like `/angular-router` and unlike every other subpath, it does not re-export the core; it is a companion to `vitest-auto-spy/angular`, not a replacement. ### React (Testing Library) React has no DI container, so there's no `provide*` helper — the recipe is: **spy the classes you own** (services, stores, API clients, hook deps), then pass the spy into a Context provider or hook. The spy is a plain object of spied functions, so it drops straight into `value={...}`: ```tsx import { render, screen } from '@testing-library/react'; import { createSpyFromClass, type Spy } from 'vitest-auto-spy/react'; import { CartContext, Cart } from './cart'; class CartStore { getItemCount(): number { return 0; } checkout(token: string): Promise<{ orderId: string }> { /* ... */ } } let cart: Spy; beforeEach(() => { cart = createSpyFromClass(CartStore); // every method is now a spy }); it('shows the item count from the injected store', () => { cart.getItemCount.mockReturnValue(3); render( , ); expect(screen.getByText('3 items')).toBeInTheDocument(); }); it('drives async deps and asserts the component called them', async () => { cart.checkout.resolveWith({ orderId: 'ord_42' }); // ...trigger checkout in the UI... expect(cart.checkout).toHaveBeenCalledWith('tok_abc'); }); ``` ### Vue / Pinia `provideAutoSpy(token, Class)` returns a `{ [token]: Spy }` map you can spread into `@vue/test-utils`' `global.provide`; for a class-based Pinia store, spy it directly: ```ts // (a) class-based service injected via provide / global.provide import { UserService, UserServiceKey } from '@/services/user.service'; // (b) class-based Pinia store — every action becomes a spy import { CartStore } from '@/stores/cart.store'; import { mount } from '@vue/test-utils'; import { createSpyFromClass, provideAutoSpy } from 'vitest-auto-spy/vue'; const provide = provideAutoSpy(UserServiceKey, UserService); // { [UserServiceKey]: Spy } provide[UserServiceKey].getName.mockReturnValue('Fake Name'); const wrapper = mount(UserBadge, { global: { provide } }); expect(provide[UserServiceKey].getName).toHaveBeenCalled(); const store = createSpyFromClass(CartStore); store.itemCount.mockReturnValue(3); // sync action/getter store.checkout.resolveWith({ orderId: 'ord_42' }); // async action (Promise) await store.checkout('tok_abc'); expect(store.checkout).toHaveBeenCalledWith('tok_abc'); ``` ### Svelte Svelte has no class-based DI, so it's a recipe: keep your logic in plain class-based services/stores, spy the class, and hand the spy to the component the same way it receives the real one (props, context, or a mocked module): ```ts import { render } from '@testing-library/svelte'; import { createSpyFromClass } from 'vitest-auto-spy/svelte'; import Cart from './Cart.svelte'; import { CartStore } from './cart-store'; it('shows the cart total from the store', () => { const cartStore = createSpyFromClass(CartStore); // every method is a spy cartStore.total.mockReturnValue(42); cartStore.priceOf.calledWith('apple').mockReturnValue(7); render(Cart, { props: { store: cartStore } }); expect(cartStore.total).toHaveBeenCalled(); }); ``` ### Which factory, and what it costs Reach for `provideAutoSpy` on Angular and `createSpyFromClass` everywhere else; use `createAutoMock()` when there is no class at runtime (an interface, an ngrx `signalStore()` whose members live on the instance) and `createMock(partial)` for a data shape the code only reads. 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 Beyond the spy factories, the package ships a set of small standalone helpers. Each one is a single-purpose utility you can pick up independently — they all ride on the same core: | Utility | Entry point | What it's for | | ----------------------------------------------------------------------------------------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `injectSpy(token)` / `injectSpy(moduleRef, token)` | `/angular`, `/nestjs` | Pull a provided spy out of the DI container, already typed as `Spy` — no casting | | `provideAutoSpy(Class, config?)` | `/angular`, `/nestjs`, `/vue` | One-liner `{ provide, useValue }` (or Vue `global.provide`) that builds the spy for you | | `createFunctionSpy(name)` | core | A single standalone function spy with the full helper set (`calledWith`, `resolveWith`, `nextWith`, …) — no class needed | | `adoptMock(mock, opts?)` | core | A runner mock a `vi.mock` factory built, taken over **in place** as a typed function spy (`calledWith`, `resolveWith`, …); the calls it recorded stay, an unconfigured call answers what it answered before | | `createAutoMock(overrides?)` | core | Proxy-based spy from a **type/interface** alone ([details](#auto-mock-by-type-no-class-needed)) | | `createMock(partial?)` | core | A plain, spy-free `T` built from the fields a test seeds — for data shapes, not collaborators | | `createFixture(defaults, overrides?)` | core | One `T` from a complete, checked default plus what this test changes — a fresh copy every call | | `createFixtureFactory(defaults)` | core | Somewhere to put that default: returns `(overrides?) => T`, with the defaults pinned at build time | | `createObservableWithValues(configs, opts?)` | `/rxjs` | Build a fake `Observable` emitting a precise sequence of values / errors / completion | | `consoleInfoSpy` / `consoleWarnSpy` / … | `/console` | Silent typed spies over the global `console`, installed on import ([details](#console-spies--vitest-auto-spyconsole)) | | `mockReadonlyProp(obj, prop, value)` | `/angular` | Overwrite a `readonly` property (incl. Angular signals) with a static value | | `mockReadonlyPropGetter(obj, prop, getter)` | `/angular` | Same, but backed by a dynamic getter | | `mockValueProp(obj, prop, value)` | `/angular` | Overwrite a property with a plain **writable** value | | `mockAccessorsProp(obj, prop, accessors?)` | `/angular` | Redefine a property with spied `get` + `set`, optionally backed by real implementations | | `restoreMockedProps()` | `/angular` | Undo every patch the `mock*Prop` helpers applied — one call in `afterEach` (each helper also returns the undo for its own patch) | | `setupFakeTimers(config?, opts?)` | `/setup` | `vi.useFakeTimers()` / `vi.useRealTimers()` as one paired `beforeEach` + `afterEach`; `{ betweenTests: true }` between them ([details](#fake-timers)) | | `advanceTimers(ms?)` | `/setup` | Advance the fake clock **and** settle the microtasks the callbacks queued ([details](#fake-timers)) | | `stubIntersectionObserver()` / `stubResizeObserver()` / `stubMutationObserver()` | `/dom-stubs` | Replace an observer global with one the spec drives, restored automatically ([details](#observer-stubs)) | | `intersectionEntry(target, isIntersecting, overrides?)` | `/dom-stubs` | Build one `IntersectionObserverEntry` without the fields nothing reads | | `mutationRecord(target, init?)` / `resizeEntry(target, rect?)` | `/dom-stubs` | Build one `MutationRecord` (with a real `NodeList`) / one `ResizeObserverEntry` | | `mockConstructor(factory, name?)` / `stubConstructor(obj, key, factory)` | core | A runner mock that can be called with `new` — see [How to mock](#how-to-mock-a-class-the-code-under-test-builds-with-new) | | `stubAbortController()` | `/dom-stubs` | A realm-consistent `AbortController`, so `addEventListener(…, { signal })` works under jsdom + zone.js | | `stubWebStorage(key?, opts?)` | `/dom-stubs` | An in-memory `localStorage` / `sessionStorage` for this test, with `snapshot()` to assert on ([details](#how-to-mock-localstorage-and-sessionstorage)) | | `flushEventLoop(turns?)` / `settleDynamicImport(load, turns?)` | core | Real event-loop turns while the timers are faked — for a dynamic `import()` or native `async` in a dependency | | `flushEventLoopUntil(isDone, opts?)` | core | Real turns until a condition holds — a `resource()` leaving `loading` — with a budget instead of a hang | | `stubMediaElement(opts?)` | `/dom-stubs` | A `