Interfaces
ReplayDivergence
@pyric/cli/repro: replay a repro file that pyric serve repro capture
wrote, so a bug found in a real project becomes a regression test.
import { readFileSync } from 'node:fs';
import { replayRepro } from '@pyric/cli/repro';
const report = await replayRepro(JSON.parse(readFileSync('repro.json', 'utf8')));
assert.ok(report.ok, JSON.stringify(report.planes, null, 2));
The Node plane needs Node 22.15 or later, as the Node host does.
Properties
| Property | Type | Description |
|---|---|---|
actual | unknown | - |
entry | number | Index of the recorded entry in entries. |
expected | unknown | - |
kind | "result" | "event" | - |
operation | ReplayOperation | The operation or listener the frame belongs to. |
reason | "differs" | "missing" | - |
session | string | - |
ReplayOperation
The recorded operation a divergent frame answers.
Properties
ReplayPlaneDifference
@pyric/cli/repro: replay a repro file that pyric serve repro capture
wrote, so a bug found in a real project becomes a regression test.
import { readFileSync } from 'node:fs';
import { replayRepro } from '@pyric/cli/repro';
const report = await replayRepro(JSON.parse(readFileSync('repro.json', 'utf8')));
assert.ok(report.ok, JSON.stringify(report.planes, null, 2));
The Node plane needs Node 22.15 or later, as the Node host does.
Properties
| Property | Type |
|---|---|
entry | number |
kind | "result" | "event" |
node | unknown |
operation | ReplayOperation |
session | string |
worker | unknown |
ReplayPlaneReport
@pyric/cli/repro: replay a repro file that pyric serve repro capture
wrote, so a bug found in a real project becomes a regression test.
import { readFileSync } from 'node:fs';
import { replayRepro } from '@pyric/cli/repro';
const report = await replayRepro(JSON.parse(readFileSync('repro.json', 'utf8')));
assert.ok(report.ok, JSON.stringify(report.planes, null, 2));
The Node plane needs Node 22.15 or later, as the Node host does.
Properties
| Property | Type | Description |
|---|---|---|
checked | number | Recorded results and events compared. |
divergences | ReplayDivergence[] | At most MAX_REPORTED divergences, in recorded order. |
firstDivergence | ReplayDivergence | - |
ok | boolean | - |
plane | ReplayPlaneName | - |
ReplayReproOptions
@pyric/cli/repro: replay a repro file that pyric serve repro capture
wrote, so a bug found in a real project becomes a regression test.
import { readFileSync } from 'node:fs';
import { replayRepro } from '@pyric/cli/repro';
const report = await replayRepro(JSON.parse(readFileSync('repro.json', 'utf8')));
assert.ok(report.ok, JSON.stringify(report.planes, null, 2));
The Node plane needs Node 22.15 or later, as the Node host does.
Properties
| Property | Type | Description |
|---|---|---|
frameTimeoutMs? | number | How long to wait for one recorded result or event, in milliseconds. |
planes? | ReplayPlaneName[] | Planes to replay on. Defaults to both. |
ReproBase
Everything the host held when the recorded log starts.
Properties
| Property | Type | Description |
|---|---|---|
appOptions | Record<string, unknown> | The Firebase options the first app port sent, when one had. |
at | number | When the starting state was read, in milliseconds since the epoch. |
checkpoint | Checkpoint | Firestore, the default RTDB instance, Storage, Auth, rules and clock. |
databaseInstances | Record<string, unknown> | Each named RTDB instance’s tree; the default instance is in the checkpoint. |
defaultInstance | string | The instance getDatabase(app) selects. |
messaging? | boolean | Whether the host served Messaging operations. Files written before this was recorded leave it out, and replay keeps Messaging off for them. |
permissive | boolean | Whether instances without rules allow every request (--permissive). |
rules | { database: ReproDatabaseRules; firestore: string; storage: string; } | - |
rules.database | ReproDatabaseRules | Keyed by instance name; defaultInstance names the default one. |
rules.firestore | string | - |
rules.storage | string | - |
sessions | Record<string, ReproPortSession> | Ports signed in when the log starts, keyed by client session id. |
subscriptions | Record<string, InboundMessage[]> | Listener registrations still open when the log starts, by client session id. |
ReproFile
Properties
| Property | Type | Description |
|---|---|---|
base | ReproBase | - |
createdAt | string | - |
entries | ReproEntry[] | - |
recordedBy | string | The @pyric/cli version that recorded it. |
schema | "pyric.repro.v1" | - |
truncated | boolean | True when older entries were dropped to keep the log bounded. |
ReproReplayReport
@pyric/cli/repro: replay a repro file that pyric serve repro capture
wrote, so a bug found in a real project becomes a regression test.
import { readFileSync } from 'node:fs';
import { replayRepro } from '@pyric/cli/repro';
const report = await replayRepro(JSON.parse(readFileSync('repro.json', 'utf8')));
assert.ok(report.ok, JSON.stringify(report.planes, null, 2));
The Node plane needs Node 22.15 or later, as the Node host does.
Properties
| Property | Type | Description |
|---|---|---|
ok | boolean | - |
planeDifferences | ReplayPlaneDifference[] | Frames where the planes produced different results. Empty with one plane. |
planes | Partial<Record<ReplayPlaneName, ReplayPlaneReport>> | - |
warnings | string[] | Recorded changes replay cannot reproduce, such as a command that wrote state. |
Type Aliases
ReplayPlaneName
type ReplayPlaneName = "node" | "worker";
@pyric/cli/repro: replay a repro file that pyric serve repro capture
wrote, so a bug found in a real project becomes a regression test.
import { readFileSync } from 'node:fs';
import { replayRepro } from '@pyric/cli/repro';
const report = await replayRepro(JSON.parse(readFileSync('repro.json', 'utf8')));
assert.ok(report.ok, JSON.stringify(report.planes, null, 2));
The Node plane needs Node 22.15 or later, as the Node host does.
ReproEntry
type ReproEntry =
| {
at: number;
frame: InboundMessage;
kind: "in";
session: string;
}
| {
at: number;
frame: OutboundMessage;
kind: "out";
session: string;
}
| {
at: number;
event: "disconnect" | "interrupted";
kind: "client";
session: string;
}
| {
at: number;
dataB64: string;
kind: "upload";
offset: number;
partIndex: number;
uploadId: string;
}
| {
at: number;
instance?: string;
kind: "rules";
service: "firestore" | "database" | "storage";
source: unknown;
}
| {
at: number;
kind: "external";
name: string;
source: "command";
};
One record in the operation log.
Type Declaration
{
at: number;
frame: InboundMessage;
kind: "in";
session: string;
}
at
at: number;
frame
frame: InboundMessage;
kind
kind: "in";
session
session: string;
A frame a port sent: an operation, a listener registration, an unsubscribe.
{
at: number;
frame: OutboundMessage;
kind: "out";
session: string;
}
at
at: number;
frame
frame: OutboundMessage;
kind
kind: "out";
session
session: string;
A frame the host sent a port: an operation result or a listener event.
{
at: number;
event: "disconnect" | "interrupted";
kind: "client";
session: string;
}
at
at: number;
event
event: "disconnect" | "interrupted";
kind
kind: "client";
session
session: string;
A transport disconnect or interruption for a client session.
{
at: number;
dataB64: string;
kind: "upload";
offset: number;
partIndex: number;
uploadId: string;
}
at
at: number;
dataB64
dataB64: string;
kind
kind: "upload";
offset
offset: number;
partIndex
partIndex: number;
uploadId
uploadId: string;
Staged bytes written to a pending Storage upload over the HTTP byte route.
{
at: number;
instance?: string;
kind: "rules";
service: "firestore" | "database" | "storage";
source: unknown;
}
at
at: number;
instance?
optional instance: string;
kind
kind: "rules";
service
service: "firestore" | "database" | "storage";
source
source: unknown;
A rules deploy from the project’s rules files.
{
at: number;
kind: "external";
name: string;
source: "command";
}
at
at: number;
kind
kind: "external";
name
name: string;
source
source: "command";
A command or MCP method call that changed state outside any port. Replay cannot run it.
Variables
REPRO_SCHEMA
const REPRO_SCHEMA: "pyric.repro.v1";
Functions
parseRepro()
function parseRepro(value: unknown): ReproFile;
Read a repro file’s JSON value, refusing one this version cannot replay.
Parameters
| Parameter | Type |
|---|---|
value | unknown |
Returns
replayRepro()
function replayRepro(repro: unknown, options?: ReplayReproOptions): Promise<ReproReplayReport>;
Replay a repro file on a fresh Node host and a fresh worker host, and report the first divergence from the recording on each and every difference between them. Accepts a parsed file or its JSON value.
Parameters
| Parameter | Type |
|---|---|
repro | unknown |
options? | ReplayReproOptions |
Returns
Promise<ReproReplayReport>