vitest-auto-spy 5.63.0 → 5.66.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.
 
@@ -387,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 -->
@@ -448,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
 
@@ -527,6 +536,9 @@ file, and `globals: true`.
 
 In [`agent-docs/adapters.md`](./agent-docs/adapters.md). Read it for NestJS, Vue, React, Svelte, `bun test`, `node:test`, Rstest and the console entry.
 
+Nest HTTP tests: `createHttpExecutionContext` supplies the context; `invokeNestParamDecorator`
+calls a custom parameter factory by index with its recorded data. Both come from `/nestjs` (§15).
+
 <!-- agents-outline: agent-docs/adapters.md -->
 
 - `trackNodeMocks` for `node:test` memory

package/CHANGELOG.md

@@ -10,6 +10,44 @@ The latest released version here must always match the one published on
 
 ## [Unreleased]
 
+## [5.66.0] - 2026-10-28
+
+### Added
+
+- `/nestjs`: `createHttpExecutionContext` supplies an HTTP context for guards, interceptors,
+  exception filters and parameter decorators. Request, response and argument accessors share the
+  same values; missing handler/class metadata and non-HTTP transports produce explicit errors.
+- `/nestjs`: `invokeNestParamDecorator` runs a custom parameter decorator's recorded factory by
+  parameter index and forwards its stored data. It refuses missing or ambiguous factories and
+  parameter pipes or schemas that need Nest's request pipeline.
+- **Bundle size:** `/nestjs` grows from 20.06 kB to 20.85 kB min+gzip (+0.79 kB, +3.9%) for
+  the HTTP context and parameter metadata helpers, without importing NestJS or Vitest. The root
+  entry does not re-export these helpers.
+
+## [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
@@ -6864,7 +6902,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.63.0...HEAD
+[Unreleased]: https://github.com/ASDAlexey/vitest-auto-spy/compare/v5.66.0...HEAD
+[5.66.0]: https://github.com/ASDAlexey/vitest-auto-spy/compare/v5.65.0...v5.66.0
+[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

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.4%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)
@@ -46,6 +46,9 @@ replacement for [`jest-auto-spies`](https://www.npmjs.com/package/jest-auto-spie
 - **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.
+- **Nest HTTP tests without starting the app**: `createHttpExecutionContext` supplies the context;
+  `invokeNestParamDecorator` runs a custom parameter decorator with its recorded data.
 - **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,
@@ -2932,6 +2935,25 @@ Pass `{ expose: [Dependency] }` to keep a collaborator real, and `providers` to
 `vitest`. On `node --test`, Bun or Rstest, import the runtime entry first. `createNestUnit` is also
 exported from `vitest-auto-spy/node` and `vitest-auto-spy/bun`.
 
+Test a custom parameter decorator without starting Nest or reading its metadata by hand.
+Here `ProfileController.profile` has `@CurrentUser('id')` on its first parameter:
+
+```ts
+import 'reflect-metadata';
+
+import { expect } from 'vitest';
+import { createHttpExecutionContext, invokeNestParamDecorator } from 'vitest-auto-spy/nestjs';
+
+import { ProfileController } from './profile.controller';
+
+const context = createHttpExecutionContext({ request: { user: { id: 'user-7' } } });
+expect(invokeNestParamDecorator(ProfileController, 'profile', 0, context)).toBe('user-7');
+```
+
+The parameter index starts at zero. The helper runs the recorded factory with its decorator data;
+pipes and schemas require Nest's validation pipeline and are refused.
+Use the same context helper for guards, interceptors and exception filters.
+
 Full page: [NestJS](https://asdalexey.github.io/vitest-auto-spy/adapters/nestjs).
 
 #### `httpResource()` and `HttpClient` — `vitest-auto-spy/angular-http`
@@ -3082,8 +3104,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                                                                                                                                                                                                                                                                  |
@@ -3112,7 +3155,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                                                                                                                                                                                                                                                                                   |
@@ -3332,6 +3375,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.
 
@@ -3766,7 +3828,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/adapters.md

@@ -28,6 +28,15 @@ mount(Greeting, { global: { provide } });
 import { createSpyFromClass } from 'vitest-auto-spy/react';
 ```
 
+**Nest HTTP tests.** `createHttpExecutionContext({ request, response, handler, class: Controller })`
+from `/nestjs` supplies an HTTP `ExecutionContext` / `ArgumentsHost` without starting Nest. Omit
+the options you do not need; `getClass()` / `getHandler()` throw if their option is missing.
+`invokeNestParamDecorator(Controller, 'method', parameterIndex, context)` runs a custom parameter
+factory by zero-based index and forwards its recorded `data`. Import `reflect-metadata` before
+the controller. The result is `unknown`; async factories return their promise unchanged. Native
+parameter decorators, pipes and schemas require Nest's pipeline and are refused. Examples:
+[Nest HTTP helpers](https://asdalexey.github.io/vitest-auto-spy/adapters/nestjs#createhttpexecutioncontext).
+
 **Types without Vitest.** `/node`, `/bun`, `/bun-angular`, `/rstest`, `/jasmine-compat`,
 `/angular-router`, `/console`, `/nestjs`, `/observer-spy` and `/rxjs` type-check with no Vitest
 installed and `skipLibCheck: false`. `Spy<T>` is one type on every entry: once the program imports an

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/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-OIHOH2RY.js';
+import { failOnUnspiedProvider, onTestBedFileEnd, isLazyDoubleFactory } from './chunk-OXE6FCQX.js';
 import './chunk-T5MQSNRX.js';
-import './chunk-4JY7KIJG.js';
-import './chunk-RQLUH6RE.js';
-import './chunk-BCT7C6DQ.js';
-import './chunk-F7UPX6YV.js';
+import './chunk-XZS56XV5.js';
+import './chunk-5GKIQX65.js';
+import './chunk-XLKBJSYQ.js';
+import './chunk-QATP6Q3G.js';
 import './chunk-PC3FAZT3.js';
-import './chunk-UH2Q7RTQ.js';
-import { isAutoSpyLike } from './chunk-TXC3L3FO.js';
+import './chunk-HIGHZ4BW.js';
+import { isAutoSpyLike } from './chunk-2CWSOIBW.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-7WU53KRS.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 };