vitest-auto-spy 3.5.0 → 3.7.0

package/AGENTS.md

@@ -12,6 +12,12 @@ node_modules/vitest-auto-spy/AGENTS.md
 
 Working on the library's own source instead? Read `CONTRIBUTING.md` in the repository.
 
+Setting this up for a team? The README section
+[Using this library with an AI agent](https://github.com/ASDAlexey/vitest-auto-spy#using-this-library-with-an-ai-agent)
+names the instruction file each agent reads — `AGENTS.md` for OpenAI Codex, Cursor, Copilot and most
+of the field, `CLAUDE.md` for Claude Code and for GLM (z.ai) or Kimi running inside it, `GEMINI.md`
+for Gemini CLI — and gives the two commands that install this pointer for all of them.
+
 | Resource                | Where                                                                |
 | ----------------------- | -------------------------------------------------------------------- |
 | Spec patterns at scale  | <https://asdalexey.github.io/vitest-auto-spy/recipes>                |
@@ -1061,6 +1067,7 @@ mechanisms, and a test that waits on the wrong one fails with a message that nam
 | effects + `afterNextRender` + CD              | `await stable(fixture)` (`…/angular`)              | `detectChanges()` alone                   |
 | timers, debounces, polling                    | `await advanceTimers(ms)` (`…/setup`)              | `await Promise.resolve()`                 |
 | a dynamic `import()`, native `async` in a dep | `await flushEventLoop()` / `settleDynamicImport()` | `tick()`, `flushMicrotasks()`, microtasks |
+| an `httpResource()` / `resource()` / `rxResource` | `await settleResource(r)` (`…/angular`) | `flushEventLoopUntil` — it never ticks |
 
 ```ts
 import { flushEventLoop, settleDynamicImport } from 'vitest-auto-spy';
@@ -1082,9 +1089,14 @@ Three rules worth stating outright, because each of them cost a day somewhere:
   and a non-zero exit code.
 
 `flushEventLoopUntil(isDone, { turns, label })` is the same thing with a condition and a budget —
-for a `resource()` leaving `loading`, a chunk becoming reachable, an SDK reporting itself ready. Use
-it instead of a hand-tuned turn count: the count depends on the dependency, not on the spec, and a
-condition that never holds fails naming the `label` rather than hanging until the runner's timeout.
+for a chunk becoming reachable, an SDK reporting itself ready, a queue draining. Use it instead of a
+hand-tuned turn count: the count depends on the dependency, not on the spec, and a condition that
+never holds fails naming the `label` rather than hanging until the runner's timeout.
+
+**Not for an Angular `resource()` / `httpResource()`.** Those need a change-detection _tick_, and
+this helper only takes event-loop turns — a resource awaited through it finishes the whole budget
+having issued zero requests. `settleResource(resource, { turns, label })` from
+`vitest-auto-spy/angular` is that wait.
 
 `flushEventLoop(turns?)` takes real event-loop turns even while the timers are faked, without
 touching the clock. It is the honest name for the `await vi.advanceTimersByTimeAsync(0)` trick,
@@ -1468,9 +1480,15 @@ spies.get(PricingService).total.mockReturnValue(100);
 // NOTE: Injector.create() — it does NOT accept EnvironmentProviders (provideHttpClient() etc.)
 
 // zoneless waiting
-await stable(fixture); // flush effects, then await the fixture
+await stable(fixture); // flush effects, then await the fixture; fails at 2000 ms naming the cause
+await stable(fixture, { timeout: 5000, label: 'the products fixture' });
 flushEffects(); // the no-fixture half: services, stores, runInInjectionContext
 
+// resources — one wait for httpResource(), resource() and rxResource()
+flushEffects(); // an httpResource issues NO request until something ticks
+httpTesting.expectOne('/api/products').flush([product]);
+await settleResource(products, { label: 'the product resource' });
+
 // signal assertions
 registerSignalMatchers(); // once, in the setup file
 expect(component.total).toHaveSignalValue(3);
@@ -1483,6 +1501,12 @@ Two zoneless traps:
 - `expect(someSignal).toBeTruthy()` passes for **every** signal ever created — a signal is a
   function. Use `toHaveSignalValue`, which also rejects the missing-parentheses mistake.
 
+And one resource trap, which is the same shape one level up: an `httpResource()` reports `loading`
+with its **default** value until a tick _and_ a microtask after its response is flushed, so a spec
+that asserts too early asserts the default and passes. `settleResource` fails instead of passing
+emptily. Note the order — `flushEffects()` first (the request is issued there, not on creation),
+then the flush, then the wait.
+
 Per-file timing, to find which specs actually pay for `TestBed`:
 
 ```ts
@@ -1663,12 +1687,13 @@ export default [{ files: ['**/*.spec.ts'], ...autoSpy.configs.recommended }];
 | `prefer-inject-spy`            | `warn`  | suggest   | `vi.spyOn(TestBed.inject(X), 'm')`, inline or via a `const` → `injectSpy(X).m` |
 | `no-shared-module-level-mock`  | `error` | —         | an **exported** value holding `vi.fn()`s → export a factory instead      |
 | `no-mocked-for-spy`            | `warn`  | `--fix`   | `Mocked<T>` in any type position → `Spy<T>`, import and all              |
+| `prefer-as-spy`                | `warn`  | `--fix`   | `TestBed.inject(X) as Spy<X>` → `asSpy<X>(TestBed.inject(X))`, import and all |
 | `no-done-callback`             | `error` | —         | `it('x', (done) => …)` → `async` + an awaited assertion                  |
 | `no-floating-assertion`        | `error` | —         | `expect()` in a `.then()` nobody awaits → `expect(await promise)`        |
 | `no-overridden-provider`       | `error` | —         | two providers for one token in one array → the earlier one never runs   |
 | `no-inject-before-override`    | `warn`  | —         | `TestBed.inject()` in a hook, in a suite that still calls `override*`    |
 
-Eleven rules; one fixes on its own, three offer suggestions. `no-mocked-for-spy` only ever touches a
+Twelve rules; two fix on their own, three offer suggestions. `no-mocked-for-spy` only ever touches a
 **type position**, where a wrong rewrite is a compile error rather than a test that quietly changed
 meaning — so `--fix` renames the type, adds `import type { Spy } from 'vitest-auto-spy'` and drops
 the orphaned `Mocked` import. Every type position, not only a `let`: a factory's return type, a
@@ -1677,6 +1702,17 @@ in all eight reports — fix one and leave the other and the file says both. It
 cannot prove the rename (a `Mocked` the file declares itself, a `Spy` that is already something
 else, `Mocked<{ a: Mock }>` rather than a named type) and reports without a fix.
 
+`prefer-as-spy` is the same licence from the other end, and the one a migration meets in bulk: a
+`jest-auto-spies` suite writes `TestBed.inject(X) as Spy<X>` once per injected double, and that cast
+fails here with `TS2352` — `Spy<T>` adds `accessorSpies` and the per-method helpers, so neither type
+sufficiently overlaps the other. `asSpy` is a typed identity function, so `--fix` keeps the
+assertion the developer already made, carries the type arguments across (inference answers
+`Spy<Service<any>>` for a generic class), adds the `asSpy` import and removes a `Spy` import the
+rewrite orphans. A cast that hops through `unknown` is left alone — the hop says the value is not a
+`T` — except after `TestBed.inject(X)`, where the container returns `X` by construction and the hop
+was only silencing `TS2352`. Neither rule is for the object under test: a service the spec
+exercises is not a double, and typing it as the class is the repair there.
+
 `no-expect-in-subscribe` reports one shape and **three different edits**, and says which: the
 subscription is the last thing the test does (invert it into `await firstValueFrom`); something
 after it is what makes the stream emit (hold the promise — `const p = expectEmission(src$)`, fire
@@ -1784,7 +1820,9 @@ packages, which a subpath export can never be.
 | a stub that works in the first test of the file and in no other                      | installed at `describe` level or in `beforeAll`, then restored away    | install it in `beforeEach`, or `installPerTest(() => stub…())`                              |
 | a third-party library failing every other run, no test named                         | a test sealed a global with `Object.defineProperty` (non-configurable) | `setupAutoSpy({ guardGlobals: 'throw' })` names the file; then `mockValueProp`              |
 | `expected [ { at: 1, …(5) }, …(8) ] to deeply equal [ { …(6) }, … ]`                 | one field moved in every element — usually a frozen clock or an id     | `expect(diffByField(actual, expected)).toBeUndefined()`                                     |
-| a hand-tuned number of turns waiting for a `resource()` to load                      | the hand-off count depends on the dependency, not on the spec          | `await flushEventLoopUntil(() => r.status() !== 'loading', { label })`                      |
+| a hand-tuned number of turns waiting for a `resource()` to load | a resource needs a change-detection **tick**, not event-loop turns; `flushEventLoopUntil` never ticks and the resource never even issues its request | `flushEffects()`, flush the request, then `await settleResource(r, { label })` |
+| a `resource()` assertion that passes but reads the **default** value | the spec asserted before the resource left `loading` | `await settleResource(r, { label })` — it fails loudly instead |
+| a spec dying on the runner's 5 s file timeout right after `await stable(fixture)` | the fixture never stabilised — an unflushed request, a real `setInterval` | `stable` now fails at 2000 ms naming the cause; raise `{ timeout }` only once neither is true |
 | `flushEventLoopUntil` timing out on the **first** such test only, the rest green | a cold dynamic `import()` outran the turn budget; later tests hit the module cache | `await settleDynamicImport(() => import('…'))` — await the module, do not count turns |
 | a template error in a `describe` that never patched anything                          | a spec `afterEach` threw and skipped `setupAutoSpy`'s, so a `mock*Prop` patch travelled | upgrade — an `onTestFinished` net restores it and names the cause (§10)                    |
 | `Property 'mockReturnValue' does not exist on type 'never'`                          | a generic method with a conditional return type; the spy collapsed     | upgrade — fixed in the types; the member now keeps its sync helper bundle                   |