rulvar API reference / @rulvar/testing
@rulvar/testing
Classes
| Class | Description |
|---|---|
| FakeAdapter | @rulvar/testing tier 1 (M1-T14): FakeAdapter and createTestEngine for fast, fully typed, zero-network unit tests through the real engine. Matchers live at '@rulvar/testing/matchers'. VCR cassettes and replay-strict arrive with M5/M2. |
| VcrMissError | Typed hermetic-miss error; onMiss: 'throw' raises it on any unrecorded request. |
Interfaces
| Interface | Description |
|---|---|
| CassetteFixture | One cassette fixture file: id, provenance note, and the journal. |
| CreateTestEngineOptions | - |
| FakeAdapterOptions | - |
| FakeCall | What a responder sees about the call. |
| FakeToolCallsValue | Marker value: the model answers this turn with tool calls (M3). |
| FakeWireErrorValue | Marker value: the stream terminates with this typed wire error (M3). |
| ReplayRunOptions | - |
| TestEngine | - |
| TestRunHandle | A RunHandle that records its own event stream for the matchers. |
| VcrCassette | - |
| VcrRow | One recorded exchange; a cassette is one JSON header line plus rows. |
Type Aliases
| Type Alias | Description |
|---|---|
| FakeResponder | A static string (plain text output), a static value (structured output), or a function of the call. Thrown errors become terminal error events. fakeToolCalls() and fakeWireError() values script tool-calling turns and typed wire failures (M3). |
| RedactFn | - |
Variables
| Variable | Description |
|---|---|
| FAKE_MODEL | @rulvar/testing tier 1 (M1-T14): FakeAdapter and createTestEngine for fast, fully typed, zero-network unit tests through the real engine. Matchers live at '@rulvar/testing/matchers'. VCR cassettes and replay-strict arrive with M5/M2. |
| FAKE_MODEL_REF | @rulvar/testing tier 1 (M1-T14): FakeAdapter and createTestEngine for fast, fully typed, zero-network unit tests through the real engine. Matchers live at '@rulvar/testing/matchers'. VCR cassettes and replay-strict arrive with M5/M2. |
| M6_ORCH_GOAL | - |
| M6_ORCH_PROFILES | - |
| M6_ORCH_RUN_ID | - |
Functions
| Function | Description |
|---|---|
| buildFrozenV1JournalRaw | The frozen v1 journal: a round-1 JSONL file with kinds agent, step, rand, external, approval and the legacy v: 1 field (no hashVersion member). Returned as raw JSON-ready objects, one per line. |
| buildM2CassetteFixtures | - |
| buildV2GoldenIdentity | v2 golden identity fixtures: worked examples per spawn kind (M2-T12). The keys freeze the hashVersion 2 profile; the v1 members freeze the effort-insensitive projection and the incomparable domain. |
| createTestEngine | - |
| defaultRedact | Built-in redaction: authorization material never reaches cassette bytes. Deliberately aggressive; compose a custom hook for payload-specific secrets. |
| fakeToolCalls | Scripts a tool-calling turn from a responder. |
| fakeWireError | Scripts a typed wire failure (e.g. a retryable rate limit). |
| handlesInRequest | Extracts spawn handles from the tool results the model saw. |
| normalizeM6Entries | Fixes wall clock and spans; everything else is deterministic already. |
| readCassette | Parses a cassette file (one header line plus one JSON row per line). |
| record | Wraps live adapters for recording: every completed stream appends one redacted row to the cassette JSONL. The wrapped adapters are drop-in: same ids, providers, caps, and event streams. |
| recordLiveCassettes | - |
| recordOrchestratorCrash | Phase 1: record the pre-crash journal. The transcripts store carries the boundary checkpoint the resume restores from; the recorder keeps it in memory because the cassette pins only journal bytes (checkpoint blobs are engine-internal at-least-once state). |
| replay | Builds replay adapters from a cassette. onMiss: 'throw' is the hermetic CI mode; 'passthrough' forwards unrecorded requests to the matching live adapter in adapters (a development convenience only). |
| replayRun | - |
| requestHash | The cassette key: a hash of the canonical wire-contract request. The engine-populated telemetry namespace is excluded (never identity); everything else the adapter would send keys the row. |