API Reference: Deterministic Testing (`@siglo/testing`)

The @siglo/testing package provides a zero-flake, deterministic test harness for Siglo workflows. It eliminates reliance on flaky timers, live databases, and manual mocking setups by providing virtual clocks (FakeClock), step spies, deterministic step mocking, event injection for durable waits, execution tracing, and replay tooling.

Overview and Installation
Workflow Test Harness
Harness Assertions
Virtual Clock (FakeClock)
In-Memory Storage Fake (InMemoryStorageFake)
Execution Fixtures and Replay
Full Test Suite Example

Overview and Installation

npm install --save-dev @siglo/testing

Workflow Test Harness

`createWorkflowHarness(flow, options?)`

Factory creating an isolated WorkflowHarness with virtual clocks, storage, step mocking, and execution telemetry.

Signatures

export interface HarnessOptions {
    services?: Record<string, any>;
    clock?: FakeClock;
    storage?: InMemoryStorageFake;
    recordTrace?: boolean;
}

export function createWorkflowHarness(workflow: any, options?: HarnessOptions): WorkflowHarness;

Example

import { createWorkflowHarness, FakeClock } from '@siglo/testing';
import { orderWorkflow } from './order.workflow';

const clock = new FakeClock();
const harness = createWorkflowHarness(orderWorkflow, { clock });

`harness.run and harness.execute`

Executes the workflow through the instrumented harness, automatically recording step trace records, timings, and outputs.

Signature

harness.run(input: any = {}, execOptions: any = {}): Promise<any>;
harness.execute(input: any = {}, execOptions: any = {}): Promise<any>;

`harness.mockStep(stepName, mockImpl)`

Overrides a step’s action with a deterministic mock implementation. Useful for third-party HTTP requests, credit card processors, or slow I/O.

Signature

harness.mockStep(stepName: string, mockImpl: (param: any) => any): this;

Example

harness.mockStep('chargeCreditCard', async () => {
    return { transactionId: 'txn_mock_123', status: 'SUCCESS' };
});

`harness.spyStep(stepName)`

Attaches a StepSpy tracking invocation count, inputs, outputs, errors, and timestamps without overriding the step’s implementation.

Signature

export class StepSpy {
    readonly name: string;
    readonly calls: Array<{ input: any; output?: any; error?: any; timestamp: number }>;
    readonly called: boolean;
    readonly callCount: number;

    firstCall(): { input: any; output?: any; error?: any; timestamp: number } | undefined;
    lastCall(): { input: any; output?: any; error?: any; timestamp: number } | undefined;
}

harness.spyStep(stepName: string): StepSpy;

Example

const spy = harness.spyStep('calculateDiscount');

await harness.run({ cartTotal: 100 });

expect(spy.called).to.be.true;
expect(spy.callCount).to.equal(1);
expect(spy.firstCall()?.input.cartTotal).to.equal(100);

`harness.injectEvent(eventName, correlationKey, payload?)`

Simulates the arrival of an external event to resume a durable waiting workflow in test scenarios without requiring network infrastructure.

Signature

harness.injectEvent(
    eventName: string,
    correlationKey: string,
    payload?: any
): Promise<any>;

Example

// 1. Run durable workflow until it suspends at waitForEvent
await harness.run({ orderId: 'ord_123' }, { durable: true });

// 2. Inject event to resume execution
const result = await harness.injectEvent('paymentWebhook', 'ord_123', {
    paymentStatus: 'PAID',
});

expect(result.orderStatus).to.equal('COMPLETED');

`harness.getTrace()`

Returns the recorded chronological execution trace across all steps and phases.

Signature

export interface StepTraceRecord {
    stepName: string;
    phase: 'start' | 'retry' | 'complete' | 'fail' | 'skip';
    timestamp: number;
    input: any;
    output?: any;
    error?: any;
    attempt?: number;
}

harness.getTrace(): StepTraceRecord[];

Harness Properties: `clock` and `storage`

The harness directly exposes its configured virtual clock and storage fake:

harness.clock: The active FakeClock instance used for timestamp tracking.
harness.storage: The active InMemoryStorageFake adapter used to store checkpoints during durable test runs.

Harness Assertions

The harness provides high-level assertion helpers:

`harness.assertStepExecuted(stepName, times?)`

Asserts that a step executed and completed successfully a specific number of times (or at least once if times is omitted).

harness.assertStepExecuted('validateCart', 1);

`harness.assertStepRetried(stepName, minAttempts?)`

Asserts that a step failed and executed retries, verifying that total attempts met or exceeded minAttempts (default: 2).

harness.assertStepRetried('flakyService', 3);

`harness.assertStepFailed(stepName, errorPattern?)`

Asserts that a step failed, optionally matching against an error string substring or regular expression pattern.

harness.assertStepFailed('unauthorizedStep', /access denied/i);

Virtual Clock (`FakeClock`)

FakeClock controls timestamps recorded in harness execution traces deterministically. Note that FakeClock advances its own timestamp counter and tick() waits for setImmediate; it does not mock Node’s global Date.now, setTimeout, or runtime sleep loops:

export class FakeClock {
    constructor(initialTime: number = Date.now());
    now(): number;
    advanceTime(ms: number): number;
    tick(ms?: number): Promise<void>;
    reset(toTime?: number): void;
}

Example

const clock = new FakeClock();
const harness = createWorkflowHarness(flowWithDelay, { clock });

// Advance virtual time by 5 minutes
clock.advanceTime(5 * 60 * 1000);

In-Memory Storage Fake (`InMemoryStorageFake`)

Implements StorageAdapter completely in memory for fast, zero-dependency unit and integration tests.

export class InMemoryStorageFake implements StorageAdapter {
    readonly name = 'in-memory-fake';
    contextChanges: any[];

    saveCheckpoint(checkpoint: any): Promise<void>;
    getCheckpoint(key: string): Promise<any>;
    clear(): void;
    getCheckpoints(): Map<string, any>;
}

Execution Fixtures and Replay

`harness.exportExecutionRecord(options?)`

Exports a sanitized execution record fixture containing initial inputs, outputs, errors, and complete trace data. Secret keys (e.g. password, token, secret, cvv) are automatically redacted.

const fixture = harness.exportExecutionRecord({
    excludeKeys: ['internalSessionId'],
});

fs.writeFileSync('fixtures/failed-run.json', JSON.stringify(fixture, null, 2));

`replayExecution(record, flow, options?)`

Replays a recorded test fixture against a workflow to verify output parity, ensuring bug fixes or refactors do not introduce regressions.

Signature

export interface ReplayOptions {
    substituteFixtures?: Record<string, any>;
    excludeKeys?: string[];
}

export interface ReplayResult {
    matched: boolean;
    expectedOutput: any;
    actualOutput: any;
    discrepancies: string[];
}

export function replayExecution(record: ExecutionRecord, workflow: any, options?: ReplayOptions): Promise<ReplayResult>;

Example

import { replayExecution } from '@siglo/testing';
import fixture from './fixtures/order-run.json';
import { orderWorkflow } from './order.workflow';

const result = await replayExecution(fixture, orderWorkflow);
expect(result.matched).to.be.true;

`sanitizeExecutionRecord(record, options?)`

Sanitizes an ExecutionRecord by recursively redacting sensitive keys (e.g. passwords, API keys, tokens, credit card numbers) from input, output, and trace steps.

Signature

export function sanitizeExecutionRecord(record: ExecutionRecord, options?: { excludeKeys?: string[] }): ExecutionRecord;

Example

import { sanitizeExecutionRecord } from '@siglo/testing';

const cleanRecord = sanitizeExecutionRecord(rawRecord, {
    excludeKeys: ['internalSecret', 'customToken'],
});

Full Test Suite Example

import { expect } from 'chai';
import { createWorkflowHarness, FakeClock } from '@siglo/testing';
import { Step, flow } from '@siglo/core';

const fetchUser = Step.create('fetchUser', async (ctx: { userId: string }) => ({
    name: 'Alice',
    tier: 'PRO',
}));

const calculateDiscount = Step.create('calculateDiscount', async (ctx: { tier: string }) => ({
    discount: ctx.tier === 'PRO' ? 0.2 : 0.05,
}));

const checkoutWorkflow = flow(fetchUser, calculateDiscount);

describe('Checkout Workflow Test Suite', () => {
    it('executes successfully with step spies and deterministic assertions', async () => {
        const clock = new FakeClock();
        const harness = createWorkflowHarness(checkoutWorkflow, { clock });

        // Spy on discount step
        const discountSpy = harness.spyStep('calculateDiscount');

        // Mock external user service
        harness.mockStep('fetchUser', () => ({ name: 'MockUser', tier: 'PRO' }));

        const result = await harness.run({ userId: 'u_100' });

        expect(result.discount).to.equal(0.2);
        expect(discountSpy.called).to.be.true;
        expect(discountSpy.firstCall()?.input.tier).to.equal('PRO');

        harness.assertStepExecuted('fetchUser', 1);
        harness.assertStepExecuted('calculateDiscount', 1);
    });
});

​API Reference: Deterministic Testing (@siglo/testing)

​Table of Contents

​Overview and Installation

​Workflow Test Harness

​createWorkflowHarness(flow, options?)

​Signatures

​Example

​harness.run and harness.execute

​Signature

​harness.mockStep(stepName, mockImpl)

​Signature

​Example

​harness.spyStep(stepName)

​Signature

​Example

​harness.injectEvent(eventName, correlationKey, payload?)

​Signature

​Example

​harness.getTrace()

​Signature

​Harness Properties: clock and storage

​Harness Assertions

​harness.assertStepExecuted(stepName, times?)

​harness.assertStepRetried(stepName, minAttempts?)

​harness.assertStepFailed(stepName, errorPattern?)

​Virtual Clock (FakeClock)

​Example

​In-Memory Storage Fake (InMemoryStorageFake)

​Execution Fixtures and Replay

​harness.exportExecutionRecord(options?)

​replayExecution(record, flow, options?)

​Signature

​Example

​sanitizeExecutionRecord(record, options?)

​Signature

​Example

​Full Test Suite Example

​Related Topic Guides

API Reference: Deterministic Testing (`@siglo/testing`)

Table of Contents

Overview and Installation

Workflow Test Harness

`createWorkflowHarness(flow, options?)`

Signatures

Example

`harness.run and harness.execute`

Signature

`harness.mockStep(stepName, mockImpl)`

Signature

Example

`harness.spyStep(stepName)`

Signature

Example

`harness.injectEvent(eventName, correlationKey, payload?)`

Signature

Example

`harness.getTrace()`

Signature

Harness Properties: `clock` and `storage`

Harness Assertions

`harness.assertStepExecuted(stepName, times?)`

`harness.assertStepRetried(stepName, minAttempts?)`

`harness.assertStepFailed(stepName, errorPattern?)`

Virtual Clock (`FakeClock`)

Example

In-Memory Storage Fake (`InMemoryStorageFake`)

Execution Fixtures and Replay

`harness.exportExecutionRecord(options?)`

`replayExecution(record, flow, options?)`

Signature

Example

`sanitizeExecutionRecord(record, options?)`

Signature

Example

Full Test Suite Example

Related Topic Guides