vitest-auto-spy 5.62.0 → 5.65.0

package/AGENTS.md

@@ -154,6 +154,11 @@ In [`agent-docs/factories.md`](./agent-docs/factories.md). Read it before writin
 
 ## 3. The 90% recipe
 
+Direct handler tests: `/dom-stubs` supplies `createDomEvent`, `createInputEvent`, `createPasteEvent`
+and `createDropEvent`. `/angular/doubles` supplies `mockElementRefProp` for an element signal query
+(§12). For synchronous outputs, `expectEmissionSync` / `expectEmissionsSync` from core or `/angular`
+check exact counts around `advance` and unsubscribe (§8). Async work needs the awaited helpers.
+
 In an Angular app the spy almost always arrives through DI: `provideAutoSpy` in the providers,
 `injectSpy` to read it. Write that shape first.
 
@@ -250,6 +255,9 @@ Rules that carry most of the value:
 In [`agent-docs/return-helpers.md`](./agent-docs/return-helpers.md). Read it when stubbing a return value: `calledWith`, `resolveWith`, `nextWith`, `returnSubject` and the rest, by return type.
 
 <!-- agents-outline: agent-docs/return-helpers.md -->
+
+- Keeping an awaited collaborator pending
+
 <!-- /agents-outline -->
 
 ---
@@ -384,6 +392,7 @@ In [`agent-docs/observables.md`](./agent-docs/observables.md). Read it when asse
 
 <!-- agents-outline: agent-docs/observables.md -->
 
+- Synchronous outputs without subscriptions
 - `createLog()` — the order between the spies
 
 <!-- /agents-outline -->
@@ -445,6 +454,9 @@ In [`agent-docs/doubles.md`](./agent-docs/doubles.md). Read it when production c
 - `localStorage` and `sessionStorage`
 - Animation frames and element boxes
 - An element for `ElementRef` — `createElementStub`
+- `mockElementRefProp` — an element for a signal query
+- Events for direct handler calls
+- Text paste and drop events
 - The members the DOM environment leaves out — `fillMissingDomApis`
 - A module mock that did nothing
 

package/CHANGELOG.md

@@ -10,6 +10,38 @@ The latest released version here must always match the one published on
 
 ## [Unreleased]
 
+## [5.65.0] - 2026-10-26
+
+## [5.64.0] - 2026-10-23
+
+### Added
+
+- `createElementStub({ elementClass: HTMLInputElement })` in `/dom-stubs` infers the element type
+  and supports `instanceof` checks without creating a DOM element. Missing members of the selected
+  class keep the stub's named error; supply their implementation in `overrides`.
+- `/dom-stubs`: `createDomEvent` supplies readonly targets for direct handler calls;
+  `createInputEvent` supplies a typed input target and value; `createPasteEvent` and `createDropEvent`
+  supply text transfers and native cancellation without browser transfer constructors.
+- `/angular/doubles`: `mockElementRefProp(component, 'trigger')` installs an inferred element
+  stub on an `ElementRef` signal query and returns the element spies, reference and writable query.
+  These DOM/query helpers add code only to their narrow entries.
+- The root entry and `/angular`: `expectEmissionSync` and `expectEmissionsSync` replace manual
+  subscriptions and arrays with exact synchronous emission counts. They keep listening during
+  `advance` to catch extra emissions and tear down before returning or throwing.
+- **Bundle size:** `/dom-stubs` grows by 491 B min+gzip over 5.63.0 for element prototypes and
+  handler events; `/angular/doubles` grows by 3.77 kB for the typed query/stub composition and its
+  existing signal-patching machinery. Shared bundle modules also change the import graph of
+  `/angular/diagnostics`, `/angular/matchers` and `/angular-http`; the recorded graph and sizes
+  include this reuse.
+
+## [5.63.0] - 2026-10-21
+
+### Added
+
+- `createDeferred<T>()` returns a typed pending promise with detached `resolve` and `reject`
+  functions, for assertions before an awaited collaborator finishes. It defaults to `void` and
+  works on supported runtimes without `Promise.withResolvers`.
+
 ## [5.62.0] - 2026-10-20
 
 ### Fixed
@@ -6856,7 +6888,10 @@ moved under 1 %: `/angular` +192 B (+1.0 %) for the override queue and the HTTP
 This copy ships with the package and carries 5.x only. Releases before 5.0.0 are in the
 [full changelog](https://github.com/ASDAlexey/vitest-auto-spy/blob/master/CHANGELOG.md).
 
-[Unreleased]: https://github.com/ASDAlexey/vitest-auto-spy/compare/v5.62.0...HEAD
+[Unreleased]: https://github.com/ASDAlexey/vitest-auto-spy/compare/v5.65.0...HEAD
+[5.65.0]: https://github.com/ASDAlexey/vitest-auto-spy/compare/v5.64.0...v5.65.0
+[5.64.0]: https://github.com/ASDAlexey/vitest-auto-spy/compare/v5.63.0...v5.64.0
+[5.63.0]: https://github.com/ASDAlexey/vitest-auto-spy/compare/v5.62.0...v5.63.0
 [5.62.0]: https://github.com/ASDAlexey/vitest-auto-spy/compare/v5.61.0...v5.62.0
 [5.61.0]: https://github.com/ASDAlexey/vitest-auto-spy/compare/v5.60.0...v5.61.0
 [5.60.0]: https://github.com/ASDAlexey/vitest-auto-spy/compare/v5.59.1...v5.60.0

package/README.md

@@ -15,7 +15,7 @@ replacement for [`jest-auto-spies`](https://www.npmjs.com/package/jest-auto-spie
 [![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-30.3%20kB-brightgreen)](#install)
+[![minzipped size](https://img.shields.io/badge/minzip-30.7%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)
@@ -42,9 +42,11 @@ replacement for [`jest-auto-spies`](https://www.npmjs.com/package/jest-auto-spie
 
 - **A spy of every method from a class**, typed, with helpers that match each return type:
   `resolveWith` for a `Promise`, `nextWith` for an `Observable`, `mockReturnValue` for the rest.
+  `createDeferred<T>()` keeps an awaited collaborator pending until the test releases it.
 - **Answers per argument list**: `calledWith(1).mockReturnValue(...)`.
 - **A spy from a type alone**: `createAutoMock<T>()` and `mockDeep<T>()`.
 - **Angular `TestBed` in one line**: `provideAutoSpy(ApiService)`, then `injectSpy(ApiService)`.
+- **Short handler tests**: typed input/paste/drop events, element query stubs, and exact synchronous output assertions.
 - **One API on every runner**: Vitest, Bun, `node:test` and Rstest; helpers for Angular, NestJS,
   React, Vue / Pinia and Svelte.
 - **Checks that make silent tests fail**: strict mode, Observable assertions, cleanup between tests,
@@ -1167,6 +1169,7 @@ that keeps the cut inside; `node scripts/check-readme-npm-cut.mjs --write` resiz
 - [Synchronous methods](#synchronous-methods)
   - [Matching order, and re-configuring the same arguments](#matching-order-and-re-configuring-the-same-arguments)
 - [Promise-returning methods](#promise-returning-methods)
+  - [Keeping a promise pending](#keeping-a-promise-pending--createdeferred)
 - [Observable-returning methods & Observable properties](#observable-returning-methods--observable-properties)
   - [Standalone observable builder](#standalone-observable-builder)
 - [Getters & setters](#getters--setters)
@@ -2360,6 +2363,33 @@ myService.getProducts.resolveWithPerCall([{ value: ['a'] }, { value: ['b'] }]);
 myService.getProducts.calledWith(1).resolveWith(['one']);
 ```
 
+### Keeping a promise pending — `createDeferred`
+
+`createDeferred<T>()` returns `{ promise, resolve, reject }`. Use it to check what happens before
+an awaited collaborator finishes, then release that collaborator without timers.
+
+```ts
+import { expect } from 'vitest';
+import { createDeferred } from 'vitest-auto-spy';
+
+const home = createDeferred<boolean>();
+const events: string[] = [];
+const navigation = home.promise.then((ok) => {
+  events.push('deeplink');
+  return ok;
+});
+expect(events).toEqual([]);
+home.resolve(true);
+await expect(navigation).resolves.toBe(true);
+expect(events).toEqual(['deeplink']);
+```
+
+`resolve` accepts a value or a `PromiseLike<T>`; `reject(reason)` rejects with that reason.
+`createDeferred()` defaults to `void`, so `resolve()` needs no argument. Settle the promise before
+awaiting the operation that depends on it, or the test will wait forever. Each call creates an
+independent native promise; the first settlement wins. No fake timers or `Promise.withResolvers`
+are required. Import from `/bun`, `/node` or `/rstest` when using those runners.
+
 ## Observable-returning methods & Observable properties
 
 Methods that return an `Observable`, and `Observable` properties listed in `observablePropsToSpyOn`,
@@ -3053,8 +3083,29 @@ two thousand tests add about 0.02 s to the run. Numbers:
 Besides the spy factories, the package has small standalone helpers. Each does one job; pick up
 only the ones you need. Every helper, with its signature: [API](https://asdalexey.github.io/vitest-auto-spy/api).
 
+For direct handler calls, replace local event factories and query setup with these helpers:
+
+```ts
+import { mockElementRefProp } from 'vitest-auto-spy/angular/doubles';
+import { createInputEvent } from 'vitest-auto-spy/dom-stubs';
+
+const trigger = mockElementRefProp(component, 'triggerButton');
+component.store.open(0, 0);
+component.onMinutesChange(createInputEvent('15'));
+component.confirm();
+expect(trigger.focus).toHaveBeenCalledOnce();
+```
+
+`mockElementRefProp` infers the element type from the signal query. Set `elementClass` for runtime
+`instanceof` checks. Patch before a live consumer reads the query; `setupAutoSpy()` restores replaced
+properties. Events with supplied targets are for direct handler calls. Paste/drop support text reads
+only. Full contracts: [element and event stubs](https://asdalexey.github.io/vitest-auto-spy/utilities/element-stub).
+
 | Utility                                                                                                     | Entry point                   | What it's for                                                                                                                                                                                                                                                                                                                                                                             |
 | ----------------------------------------------------------------------------------------------------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `createDomEvent(type, init?)` / `createInputEvent(value, init?)`                                            | `/dom-stubs`                  | Native events for direct handlers, with readonly targets or an input value                                                                                                                                                                                                                                                                                                                |
+| `createPasteEvent(text, init?)` / `createDropEvent(text, init?)`                                            | `/dom-stubs`                  | Text transfers with native `defaultPrevented`; `null` represents absent transfer data                                                                                                                                                                                                                                                                                                     |
+| `mockElementRefProp(component, key, opts?)`                                                                 | `/angular/doubles`            | Inferred element spies, `ref` and writable `query`, installed together                                                                                                                                                                                                                                                                                                                    |
 | `injectSpy(token)` / `injectSpy(moduleRef, token)`                                                          | `/angular`, `/nestjs`         | Pull a provided spy out of the DI container, already typed as `Spy<T>` — 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                                                                                                                                                                                                                                                                  |
@@ -3083,7 +3134,7 @@ only the ones you need. Every helper, with its signature: [API](https://asdalexe
 | `stubWorker(opts?)`                                                                                         | `/dom-stubs`                  | A `Worker` whose script is the spec — listeners stack, replies arrive on a microtask, `emit()` / `fail()` from the worker's side ([details](#how-to-mock-a-web-worker))                                                                                                                                                                                                                   |
 | `stubAnimationFrame(opts?)`                                                                                 | `/dom-stubs`                  | `requestAnimationFrame` / `cancelAnimationFrame` run on the spot or on `flush(timestamp?)`; a frame requested inside a frame waits for the next flush; `onError` intercepts a throwing callback; `lastHandle` is the latest handle issued (they start above 2^30)                                                                                                                         |
 | `stubElementRect(el, rect?)`                                                                                | `/dom-stubs`                  | `getBoundingClientRect()` answering a real `DOMRect` built from a partial `DOMRectInit`; returns the undo, plus the installed spy as `.getBoundingClientRect`                                                                                                                                                                                                                             |
-| `createElementStub(opts?)`                                                                                  | `/dom-stubs`                  | A typed `HTMLElement` for `ElementRef` — `classList`, `style`, attributes and listeners on spies that keep state; a member it does not implement throws by name                                                                                                                                                                                                                           |
+| `createElementStub(opts?)`                                                                                  | `/dom-stubs`                  | A typed element for `ElementRef`; `elementClass` enables `instanceof` checks and infers the type. Spies keep state; unconfigured DOM members require `overrides`                                                                                                                                                                                                                          |
 | `fillMissingDomApis(opts?)`                                                                                 | `/dom-stubs`                  | For the setup file: `PointerEvent`, a no-op `ResizeObserver`, no-op scrolling and `document.doctype`, only where missing; `{ cheapComputedStyle: true }`                                                                                                                                                                                                                                  |
 | `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                                                                                                                                                                                                                                                                                   |
@@ -3303,6 +3354,25 @@ Full page: [explainSpy](https://asdalexey.github.io/vitest-auto-spy/utilities/ex
 
 ## Observable assertions
 
+For a synchronous handler, check the exact output count without managing a subscription:
+
+```ts
+import { expectEmissionSync, expectEmissionsSync } from 'vitest-auto-spy';
+
+expect(expectEmissionSync(component.page, { advance: () => component.next() })).toBe(3);
+expect(
+  expectEmissionsSync(component.page, 2, {
+    advance: () => {
+      component.next();
+      component.next();
+    },
+  }),
+).toEqual([4, 5]);
+```
+
+Both helpers unsubscribe before returning and fail on missing or extra synchronous values.
+For timers, promises or other asynchronous work, use the awaited helpers below.
+
 These helpers make the assertion an `await`, so a stream that never emits fails the test. An
 `expect` inside `subscribe()` never runs when the stream stays silent, and the test passes.
 
@@ -3737,7 +3807,7 @@ Every export, one line each. Signatures, options and types: [API](https://asdale
 | `stubWorker(opts?)` _(`/dom-stubs`)_                                                                                                        | A `Worker` a spec drives from the worker's side: `respond` per message, `messages` / `terminated` to assert, `emit()` / `fail()`; returns `WorkerStub<TIn, TOut>`                                                                                                                                                        |
 | `stubAnimationFrame(opts?)` _(`/dom-stubs`)_                                                                                                | Frames on the spec's schedule: `'immediate'` or `'queued'` + `flush()`, `pending`, `lastHandle`, both globals as spies; returns `AnimationFrameStub`                                                                                                                                                                     |
 | `stubElementRect(el, rect?)` _(`/dom-stubs`)_                                                                                               | A box for `getBoundingClientRect()` — missing fields `0`, edges derived; returns `ElementRectRestore` (callable undo plus `.getBoundingClientRect`)                                                                                                                                                                      |
-| `createElementStub(opts?)` / `fillMissingDomApis(opts?)` _(`/dom-stubs`)_                                                                   | A typed stub `HTMLElement` for `ElementRef`; the DOM members jsdom / happy-dom leave out, filled once in the setup file                                                                                                                                                                                                  |
+| `createElementStub(opts?)` / `fillMissingDomApis(opts?)` _(`/dom-stubs`)_                                                                   | A typed stub for `ElementRef`, with optional `elementClass` for `instanceof`; missing DOM APIs filled once in the setup file                                                                                                                                                                                             |
 | `createComponentStub(Class, overrides?, opts?)` _(`/angular`)_                                                                              | A standalone stand-in for a child component, directive or pipe, built from its compiled definition so the selector cannot drift                                                                                                                                                                                          |
 | `flushEventLoop(turns?)` / `settleDynamicImport(load, turns?)`                                                                              | Real event-loop turns under fake timers; wait for a dynamic `import()`                                                                                                                                                                                                                                                   |
 | `autoMocked<T>(overrides?, config?)`                                                                                                        | `createAutoMock` typed as `T & Spy<T>`; `AutoMocked<T>` names it for a `let`                                                                                                                                                                                                                                             |

package/agent-docs/doubles.md

@@ -189,9 +189,109 @@ expect(host.classes()).toEqual(['card', 'highlighted']); // attributes(), styles
 host.emit('mouseleave'); // fires the listeners; records nothing on dispatchEvent
 ```
 
+For `instanceof` checks, pass `elementClass`:
+
+```ts
+const input = createElementStub({ elementClass: HTMLInputElement, tagName: 'input', overrides: { value: '15' } });
+
+expect(input.element).toBeInstanceOf(HTMLInputElement);
+expect(input.element.value).toBe('15'); // inferred as HTMLInputElement
+```
+
+`elementClass?: { readonly prototype: T }` defaults to none and infers `T` from the class.
+It uses the prototype without calling the constructor. `tagName` remains independent and defaults to `'div'`.
+The supplied class adds no implementations. Configure missing properties and methods, such as `value` or `select`, in `overrides`.
+Existing stub methods, such as `focus`, remain usable. Reading an unconfigured class member throws with its name.
+
+### `mockElementRefProp` — an element for a signal query
+
+Replace an optional or required `ElementRef` signal query and get the element spies in one call.
+For example, `component.dateTrigger` has type `Signal<ElementRef<HTMLButtonElement> | undefined>`.
+Its `focusTrigger()` method calls `focus()` on the queried element.
+
+```ts
+import { mockElementRefProp } from 'vitest-auto-spy/angular/doubles';
+
+const trigger = mockElementRefProp(component, 'dateTrigger', {
+  elementClass: HTMLButtonElement,
+  tagName: 'button',
+});
+component.focusTrigger();
+expect(trigger.focus).toHaveBeenCalledExactlyOnceWith();
+```
+
+This replaces a local element factory followed by `mockSignalProp(component, 'dateTrigger', new ElementRef(element))`.
+The query determines the element type. Options are those of `createElementStub` and cannot change that type.
+The handle also returns `ref` (the installed `ElementRef`) and `query` (a writable test signal).
+Use `trigger.query.set(undefined)` to represent a missing optional query; required queries reject `undefined` in TypeScript.
+Queries returning component or directive instances, and `viewChildren`, need `mockSignalProp` instead.
+
+Patch before rendering a template, effect, or `computed` that consumes the original query.
+Patching an already consumed query throws. This helper creates no rendered element and does not resolve Angular queries.
+`setupAutoSpy()` restores the original query after each test. Without it, add cleanup:
+
+```ts
+import { afterEach } from 'vitest';
+import { restoreMockedProps } from 'vitest-auto-spy';
+
+afterEach(() => restoreMockedProps());
+```
+
 Reading an `HTMLElement` member the stub does not implement throws with the member's name — pass it
-in `overrides: { offsetWidth: 120, querySelector: vi.fn() }`. Nothing is patched, so there is nothing
-to restore.
+in `overrides: { offsetWidth: 120, querySelector: vi.fn() }`. `createElementStub` itself patches nothing and needs no cleanup.
+
+### Events for direct handler calls
+
+Use `createDomEvent` to supply readonly targets without a cast or `Object.defineProperty` in each test.
+Here, `component.onBlur()` reads `currentTarget` and removes the `active` class.
+
+```ts
+import { createDomEvent, createElementStub, createInputEvent } from 'vitest-auto-spy/dom-stubs';
+
+const input = createElementStub({ tagName: 'input', classes: ['active'] });
+component.onBlur(createDomEvent('blur', { currentTarget: input.element }));
+expect(input.classes()).toEqual([]);
+
+component.onInput(createInputEvent('15'));
+expect(component.value()).toBe('15');
+```
+
+`createDomEvent(type, init?)` returns a native `Event`. `bubbles` and `cancelable` default to `true`.
+The optional `target` and `currentTarget` stay fixed. For propagation tests, omit them and dispatch on a real DOM element.
+
+`createInputEvent(value, init?)` returns an `Event` of type `'input'` with an input stub as `target`.
+It supports `instanceof HTMLInputElement` when that class exists. The supplied value wins over `init.element.overrides.value`.
+Pass stub options through `element`, for example `{ element: { overrides: { disabled: true } } }`.
+Pass other native event flags directly in `init`.
+
+**Common mistake:** expecting `data`, `inputType`, or a browser input event constructor check to work.
+This helper returns `Event`, not `InputEvent`. Use a native `InputEvent` when testing those browser features.
+
+### Text paste and drop events
+
+Replace local clipboard and drag event factories when a handler only reads plain text.
+Here, `onPaste` and `onDrop` read the text and cancel the event.
+
+```ts
+import { createDropEvent, createPasteEvent } from 'vitest-auto-spy/dom-stubs';
+
+const paste = createPasteEvent('15');
+component.onPaste(paste);
+expect(paste.defaultPrevented).toBe(true);
+
+component.onDrop(createDropEvent('20'));
+expect(component.value()).toBe('20');
+```
+
+Both accept `(text: string | null, init?: EventInit)` and default to bubbling, cancelable events.
+`null` gives `clipboardData: null` or `dataTransfer: null`, so you can test absent data.
+`getData('text')` and `getData('text/plain')` return the supplied text, ignoring case; other formats return `''`.
+`types` is a readonly `['text/plain']` array. These events can also be dispatched on DOM elements.
+
+The transfer supports only `getData()` and `types`. Reading `files`, `items`, `setData`, or any other transfer member throws.
+These are native `Event` instances with the text transfer property added.
+They need no `ClipboardEvent`, `DragEvent`, or `DataTransfer` constructor and do not pass those constructor checks.
+For files, coordinates, transfer writes, or browser drag behavior, supply your own event.
 
 ### The members the DOM environment leaves out — `fillMissingDomApis`
 

package/agent-docs/observables.md

@@ -35,6 +35,43 @@ store.dispatch(noop());
 expectNoEmissionSync(store.saved$, { skip: 1 }); // skip the replayed value
 ```
 
+### Synchronous outputs without subscriptions
+
+Use `expectEmissionSync` for exactly one synchronous emission, or `expectEmissionsSync` for an exact count.
+They return values immediately, so you need no listener spy, collection array, manual unsubscribe, or `await`.
+
+```ts
+import { expectEmissionSync, expectEmissionsSync } from 'vitest-auto-spy';
+
+expect(
+  expectEmissionSync(component.closed, {
+    advance: () => component.close(),
+  }),
+).toBeUndefined();
+
+expect(
+  expectEmissionsSync(component.selected, 2, {
+    advance: () => {
+      component.select(15);
+      component.select(20);
+    },
+  }),
+).toEqual([15, 20]);
+```
+
+The helper subscribes first, runs `advance` once, then unsubscribes before returning or throwing.
+Values emitted during subscription count too. Use `{ skip: 1 }` to ignore a replayed initial value.
+`until` filters accepted values; `label` names the source in failures. These are the only other options: there is no `timeout`.
+Both helpers also come from `vitest-auto-spy/angular` and accept Angular outputs or observable-like sources.
+
+A missing or extra accepted value fails immediately. Unlike `expectEmission`, which stops at the first value,
+`expectEmissionSync` checks everything emitted during subscription and the synchronous action.
+`expectEmissionsSync` requires a positive integer count; use `expectNoEmissionSync` for zero.
+Source errors and thrown callbacks fail the assertion and close the subscription.
+
+**Common mistake:** using this for a timer or microtask emission. The subscription is already closed when that value arrives.
+Use `expectEmission` or `expectEmissions` with `await` for asynchronous work.
+
 A failure that counts emissions also shows the first five values, then `… N more`:
 `the stream completed after 7 emissions (1, 2, 3, 4, 5, … 2 more), expected 9`,
 `did not complete within 20 ms (3 emissions received: 1, 2, 3)`.

package/agent-docs/return-helpers.md

@@ -220,3 +220,11 @@ closures, not on the runner's mock. So when a spy outlives a test — a TestBed
 a spy hoisted to `describe` scope — put `resetAutoSpy(spy)` in `beforeEach`. Inside one test the
 sequence `nextWith(a)` then `throwWith(e)` still means "emit a, then fail"; only a reset or a
 terminal call starts a new stream.
+
+### Keeping an awaited collaborator pending
+
+`createDeferred<T>()` from the core entry returns `{ promise, resolve, reject }`. Return `promise`
+from the spy, start the operation, assert the intermediate state, then `resolve(value)` and await
+the operation. `createDeferred()` defaults to `void`; `resolve()` then needs no argument.
+Do not await the operation before resolving its dependency. No timer or `Promise.withResolvers`
+is required. Use the runner's core entry (`/bun`, `/node`, `/rstest`) outside Vitest.

package/dist/angular-diagnostics.js

@@ -1,16 +1,17 @@
-import { pendingRequestsReport, assertAngularInternals, instrumentTestBed, onTestingModuleConfigured, onComponentCreated, HTTP_TESTING_BRAND, beforeTestBedReset, verifyOnTeardown } from './chunk-JCTHGJTY.js';
-export { disableTestBedDiagnostics, enableTestBedDiagnostics, formatSpecTiming, getTestBedTiming, instrumentTestBed, reportSpecTiming } from './chunk-JCTHGJTY.js';
-import { failOnUnspiedProvider, onTestBedFileEnd, isLazyDoubleFactory } from './chunk-OWZPZBJI.js';
+import { pendingRequestsReport, instrumentTestBed, onTestingModuleConfigured, onComponentCreated, HTTP_TESTING_BRAND, beforeTestBedReset, verifyOnTeardown } from './chunk-C7K75NLS.js';
+export { disableTestBedDiagnostics, enableTestBedDiagnostics, formatSpecTiming, getTestBedTiming, instrumentTestBed, reportSpecTiming } from './chunk-C7K75NLS.js';
+import { assertAngularInternals } from './chunk-LGWVFIIJ.js';
+import { failOnUnspiedProvider, onTestBedFileEnd, isLazyDoubleFactory } from './chunk-TH2H3MSZ.js';
 import './chunk-T5MQSNRX.js';
-import './chunk-4JY7KIJG.js';
-import './chunk-RQLUH6RE.js';
-import './chunk-BCT7C6DQ.js';
-import './chunk-F7UPX6YV.js';
+import './chunk-BRKMJMTO.js';
+import './chunk-LZ64J6OW.js';
+import './chunk-2OYBXIQC.js';
+import './chunk-NGVSSYI4.js';
 import './chunk-PC3FAZT3.js';
-import './chunk-UH2Q7RTQ.js';
-import { isAutoSpyLike } from './chunk-TXC3L3FO.js';
+import './chunk-UON4XYJW.js';
+import { isAutoSpyLike } from './chunk-P6P7UE7C.js';
 import { count, sourceClassName, taskName } from './chunk-DYAS4OK4.js';
-import { angularPendingRequests, angularShadowedProviders, angularDeadSchemas, angularNgModuleScopesAuto } from './chunk-IATDAQMO.js';
+import { angularPendingRequests, angularShadowedProviders, angularDeadSchemas, angularNgModuleScopesAuto } from './chunk-7A4QSHDK.js';
 import { withDocs } from './chunk-ENCEEH23.js';
 import { getTestBed } from '@angular/core/testing';
 import { beforeEach, afterEach } from 'vitest';

package/dist/angular-doubles.d.ts

@@ -1,7 +1,8 @@
 import './vitest-mock-types-B17-xaWt.js';
-import { InjectionToken, AbstractType, Injector, ValueProvider, FactoryProvider, ProviderToken, ChangeDetectorRef } from '@angular/core';
+import { InjectionToken, AbstractType, Injector, ValueProvider, FactoryProvider, ProviderToken, ChangeDetectorRef, ElementRef, WritableSignal, Signal } from '@angular/core';
 import { h as AddSpyMethodsByReturnTypes, S as Spy, F as Func, p as FunctionSpy } from './types-BdYUK_Zv.js';
 import { DomSanitizer } from '@angular/platform-browser';
+import { E as ElementStub, a as ElementStubOptions } from './element-stub-D3kchFNq.js';
 import 'vitest';
 
 /**
@@ -501,4 +502,31 @@ type ValidSelection<T, Selection> = Selection extends readonly unknown[] ? reado
  */
 declare function createWindowSpies<const Selection extends WindowSpySelection>(selection: Selection & ValidSelection<Window, Selection>): WindowSpies<Window, Selection>;
 
-export { type AttachedComponent, type DialogComponent, type DialogDataOf, type DialogRefLike, type DialogResult, type MatDialogRefDouble, type MatDialogRefInit, type OverlayDouble, type OverlayDoubleInit, type OverlayLike, type OverlayRefDouble, type OverlayRefStub, type PlatformFlagTokens, type PlatformName, type PlatformOverrides, type PositionCall, type WindowSpies, type WindowSpySelection, createChangeDetectorRefDouble, createDocumentDouble, createDomSanitizerDouble, createMatDialogRef, createOverlayDouble, createWindowDouble, createWindowSpies, injectMatDialogRef, injectOverlayDouble, provideChangeDetectorRefDouble, provideDocumentDouble, provideDomSanitizerDouble, provideMatDialogData, provideMatDialogRef, provideOverlayDouble, providePlatform, provideWindowDouble };
+type QueryValue<T> = T extends Signal<infer V> ? V : never;
+type QueryElement<T> = [Exclude<QueryValue<T>, undefined>] extends [never] ? never : Exclude<QueryValue<T>, undefined> extends ElementRef<infer E extends HTMLElement> ? E : never;
+type ElementQueryKey<T> = {
+    [K in keyof T]-?: [QueryElement<T[K]>] extends [never] ? never : K;
+}[keyof T];
+/** Element spies together with the reference installed on the query and its writable test handle. */
+type ElementRefPropStub<T extends HTMLElement, V = ElementRef<T> | undefined> = ElementStub<T> & {
+    readonly ref: ElementRef<T>;
+    readonly query: WritableSignal<V>;
+};
+/**
+ * Replace an ElementRef-valued signal query with a DOM stub and return its spies.
+ *
+ * ```ts
+ * const trigger = mockElementRefProp(component, 'dateTrigger');
+ * component.close();
+ * expect(trigger.focus).toHaveBeenCalledExactlyOnceWith();
+ * ```
+ *
+ * The queried element type is inferred from the property. Options are those of `createElementStub`;
+ * they do not infer a different element type. `ref` is the installed `ElementRef`; `query` can drive
+ * a later reference, or `undefined` for an optional query. Patch before rendering a live consumer.
+ * Like `mockSignalProp`, replacement patches are undone by `restoreMockedProps()` / `setupAutoSpy()`.
+ * This does not render a DOM element or cause Angular to resolve a view query.
+ */
+declare function mockElementRefProp<T, K extends ElementQueryKey<T> & keyof T>(object: T, property: K, options?: ElementStubOptions<NoInfer<QueryElement<T[K]>>>): ElementRefPropStub<QueryElement<T[K]>, QueryValue<T[K]>>;
+
+export { type AttachedComponent, type DialogComponent, type DialogDataOf, type DialogRefLike, type DialogResult, type ElementRefPropStub, type MatDialogRefDouble, type MatDialogRefInit, type OverlayDouble, type OverlayDoubleInit, type OverlayLike, type OverlayRefDouble, type OverlayRefStub, type PlatformFlagTokens, type PlatformName, type PlatformOverrides, type PositionCall, type WindowSpies, type WindowSpySelection, createChangeDetectorRefDouble, createDocumentDouble, createDomSanitizerDouble, createMatDialogRef, createOverlayDouble, createWindowDouble, createWindowSpies, injectMatDialogRef, injectOverlayDouble, mockElementRefProp, provideChangeDetectorRefDouble, provideDocumentDouble, provideDomSanitizerDouble, provideMatDialogData, provideMatDialogRef, provideOverlayDouble, providePlatform, provideWindowDouble };