@generative-a11y/test
Record normalized lifecycle events, replay versioned fixtures with a ManualClock, and install semantic Vitest assertions.
recordRuntime and replayEvents
Recording captures accepted events sent through the returned dispatch target. Replay validates the full fixture before dispatching any event and advances the supplied ManualClock in recorded order.
import { ManualClock, createGenerativeA11y } from "@generative-a11y/core";
import { recordRuntime, replayEvents } from "@generative-a11y/test";
const clock = new ManualClock(0);
const runtime = createGenerativeA11y({ clock });
const recording = recordRuntime({ runtime, clock });
recording.runtime.dispatch({
type: "response.started",
responseId: "report",
});
const fixture = recording.fixture();
const replayClock = new ManualClock(fixture.startAt);
const replayRuntime = createGenerativeA11y({ clock: replayClock });
replayEvents(replayRuntime, replayClock, fixture);
runtime.dispose();
replayRuntime.dispose();How this code works
- 01Record through the wrapper
Only calls made through recording.runtime become fixture entries.
- 02Freeze a V1 fixture
fixture stores relative non-negative times and preserves array order for ties.
- 03Replay under injected time
replayEvents advances ManualClock before each dispatch and does not run until idle.
Options and return values
recordRuntime({ runtime, clock })RuntimeRecordingFunction
Returns a dispatch target plus immutable events, fixture, and clear methods.
- Default
n/a
RuntimeRecording.events()readonly RecordedEvent[]Method
Returns frozen copies of accepted normalized events with relative timestamps.
- Default
[]
RuntimeRecording.fixture()ReplayFixtureV1Method
Builds a validated frozen fixture from the current recording.
- Default
n/a
RuntimeRecording.clear()voidMethod
Removes recorded events without changing the target runtime or clock.
- Default
n/a
ReplayFixtureV1{ format, version, startAt, events }Type
Defines the versioned JSON envelope and ordered recorded events used by replay.
- Default
n/a
createReplayFixture(events, options?)ReplayFixtureV1Function
Validates and freezes a versioned local replay fixture.
- Default
startAt: 0
replayEvents(runtime, clock, fixture)voidFunction
Validates the fixture, advances ManualClock, and dispatches each copied event.
- Default
n/a
matchesPartial(actual, expected)booleanFunction
Compares expected top-level semantic fields with an announcement or diagnostic object.
- Default
n/a
Opt-in Vitest matchers
Import @generative-a11y/test/vitest only in Vitest setup. The root package entry has no Vitest runtime import.
import { expect } from "vitest";
import { installVitestMatchers } from "@generative-a11y/test/vitest";
installVitestMatchers(expect);
expect(recorder).toHaveAnnounced({
sourceType: "response.completed",
});How this code works
- 01Install once
Register matchers in the Vitest setup file used by the test project.
- 02Assert semantic fields
Partial expectations keep tests focused on the contract under review.
Options and return values
toHaveAnnouncementTranscript(expected)matcherVitest
Checks ordered announcement output with partial semantic fields.
- Default
n/a
toHaveAnnounced(expected)matcherVitest
Checks that at least one announcement matches the expected fields.
- Default
n/a
toHaveDiagnostic(expected)matcherVitest
Checks that at least one runtime diagnostic matches the expected fields.
- Default
n/a
Validation and evidence limits
Replay rejects unsupported formats, versions, event types, backward times, and response or tool events without required IDs before dispatch. A passing transcript confirms deterministic core output. It does not prove browser delivery or screen-reader speech.