durable-testing

name	durable-testing
description	Unit-test @dudousxd/nestjs-durable workflows with @dudousxd/nestjs-durable-testing — createTestEngine gives an in-memory engine/store/transport + a controllable clock. Register a workflow body with engine.register, serve its dispatched ctx.step calls with transport.handle, start runs with engine.start + waitForRun, advance durable sleeps with tick(ms), inject failures with failOnce/failTimes to drive retries, and assert with assertRunStatus, assertOutput, assertStepsRan, assertStepAttempts, recordedSteps. No Postgres, no Redis, no real time.
license	MIT
metadata	{"type":"core","library":"@dudousxd/nestjs-durable","library_version":"0.22.0","framework":"nestjs"}

Testing durable workflows

@dudousxd/nestjs-durable-testing runs a whole workflow in a unit test against an in-memory store and transport, with a clock you control and assertions that read the recorded state back. No external infrastructure, no real waiting.

Every ctx.step is dispatched — even in a test — so a step needs a fake worker handler registered on the test transport before the run reaches it.

Setup

pnpm add -D @dudousxd/nestjs-durable-testing

import {
  createTestEngine,
  assertRunStatus,
  assertOutput,
} from '@dudousxd/nestjs-durable-testing';

const t = createTestEngine(); // { engine, store, transport, clock, tick, run }

t.transport.handle('reserve', async () => ({ reserved: true })); // fake worker for the dispatched step
t.transport.handle('ship', async () => ({ shipped: true }));

t.engine.register('checkout', '1', async (ctx) => {
  await ctx.step('reserve', { id: 'o1' });
  return ctx.step('ship', { id: 'o1' });
});

const { runId } = await t.engine.start('checkout', { id: 'o1' }, 'run1'); // enqueues → pending
const result = await settle(t, runId);                                   // see "Settling a run" below
await assertRunStatus(t.store, 'run1', 'completed');
await assertOutput(t.store, 'run1', { shipped: true });

createTestEngine() returns { engine, store, transport, clock, tick, run }. Use the raw engine.register(name, version, body) to register a workflow body directly (no NestJS DI needed in a unit test) and transport.handle(name, (input, log) => output) to serve each ctx.step it dispatches by name — or wire real @Workflow/@Step providers via a Nest testing module when you want DI.

Core patterns

Settling a run — a dispatched ctx.step suspends between hops

Because every step is dispatched (even against the in-memory transport), a run legitimately goes suspended after EACH step and resumes asynchronously once its fake handler resolves — so a single waitForRun call after start often returns mid-chain, not at the run's actual resting point. Poll until the status stops changing:

import type { RunResult } from '@dudousxd/nestjs-durable-core';
import type { TestEngine } from '@dudousxd/nestjs-durable-testing';

async function settle(t: TestEngine, runId: string, max = 20): Promise<RunResult> {
  let last: RunResult = { runId, status: 'pending' } as RunResult;
  for (let i = 0; i < max; i += 1) {
    await new Promise((r) => setImmediate(r)); // let a pending transport.handle result land
    last = await t.engine.waitForRun(runId);
    if (last.status !== 'suspended') return last;
  }
  return last; // still suspended after `max` hops — a real wait (sleep/signal), not more dispatch
}

A workflow whose OWN resting point is suspended (a durable sleep, waitForSignal) returns that status from settle too — assert on it directly, same as the non-dispatched case.

Control durable time with tick(ms)

tick(ms) advances the clock and resumes any durable sleep now due — a 7-day sleep is tested instantly.

t.transport.handle('draft', async () => undefined);
t.transport.handle('send', async () => undefined);
t.engine.register('digest', '1', async (ctx) => {
  await ctx.step('draft', {});
  await ctx.sleep('7 days');
  await ctx.step('send', {});
});

const { runId } = await t.engine.start('digest', {}, 'run1');
await settle(t, runId);                           // rests on the durable sleep → suspended
await assertRunStatus(t.store, 'run1', 'suspended');
await t.tick(7 * 24 * 60 * 60 * 1000);             // the sleep is now due → resumes
await settle(t, runId);
await assertRunStatus(t.store, 'run1', 'completed');

Inject crashes and drive retries

failOnce(value) / failTimes(n, value) build a fake handler that throws before finally returning value — hand it straight to transport.handle to exercise retries and resume. A zero/omitted backoffMs still needs a timer sweep to notice the retry is due, so tick(0) after the failure.

import { failOnce, assertStepAttempts } from '@dudousxd/nestjs-durable-testing';

t.transport.handle('charge', failOnce({ ok: true }));
t.engine.register('wf', '1', async (ctx) => ctx.step('charge', {}, { retries: 3 }));

const { runId } = await t.engine.start('wf', {}, 'run1');
await settle(t, runId);
await t.tick(0); // due retries (even a zero backoff) resume on the next timer sweep
await settle(t, runId);
await assertStepAttempts(t.store, 'run1', 'charge', 2); // failed once, then succeeded

Assertions

All assertions read the store, so they work against any run the engine produced:

• assertRunStatus(store, runId, status) — terminal/suspended status.
• assertOutput(store, runId, expected) — the run's final output.
• assertStepsRan(store, runId, names) — which steps recorded checkpoints.
• assertStepAttempts(store, runId, stepName, attempts) — attempt count for retries.
• recordedSteps(store, runId) — the list of recorded step names.

Common mistakes

1. Forgetting to register a transport.handle for a dispatched step

// ✗ Wrong — no fake worker for 'reserve'; the step fails with "no handler for reserve"
t.engine.register('checkout', '1', async (ctx) => ctx.step('reserve', {}));
await t.engine.start('checkout', {}, 'run1');

// ✓ Correct — every ctx.step name the body dispatches needs a matching transport.handle
t.transport.handle('reserve', async () => ({ reserved: true }));
t.engine.register('checkout', '1', async (ctx) => ctx.step('reserve', {}));

ctx.step is always dispatched — even in a test against the in-memory transport — so there is no "local" step that just runs inline. Source: packages/core/src/testing/in-memory-transport.ts (handle).

2. Expecting one waitForRun to reach a multi-step run's terminal state

// ✗ Wrong — resolves on the FIRST dispatched step's pending suspend, not the run's end state
const { runId } = await t.engine.start('checkout', input, 'run1');
await t.engine.waitForRun(runId);
await assertRunStatus(t.store, 'run1', 'completed'); // often fails — still 'suspended' mid-chain

// ✓ Correct — poll until the status stops changing (see "Settling a run" above)
const { runId } = await t.engine.start('checkout', input, 'run1');
await settle(t, runId);
await assertRunStatus(t.store, 'run1', 'completed');

waitForRun resolves on the FIRST settled event, and a dispatch-pending suspend counts as settled — a run with several dispatched steps in sequence settles once per step. Source: packages/core/src/engine.ts (waitForRun).

3. Using real time instead of tick() for a durable sleep

// ✗ Wrong — the durable sleep is suspended; real time never advances the engine's clock
await t.engine.start('digest', {}, 'run1');
await new Promise((r) => setTimeout(r, 1000)); // run stays suspended forever

// ✓ Correct — advance the controllable clock so the sleep becomes due
await t.engine.start('digest', {}, 'run1');
await settle(t, 'run1'); // suspends on the sleep
await t.tick(7 * 24 * 60 * 60 * 1000);

The test engine uses a MutableClock; only tick(ms) advances it and resumes due timers. Source: packages/testing/src/harness.ts (tick, MutableClock).

4. Reusing the same runId across cases expecting a fresh run

// ✗ Wrong — start is idempotent by runId; reusing 'run1' returns the existing run, not a new one
await t.engine.start('wf', a, 'run1');
await t.engine.start('wf', b, 'run1'); // same run — input b is ignored

// ✓ Correct — give each logical run a distinct id (or omit it for a random one)
await t.engine.start('wf', a, 'run1');
await t.engine.start('wf', b, 'run2');

A runId makes start idempotent (a redelivery returns the existing run), so distinct cases need distinct ids. Source: packages/nestjs/src/workflow.service.ts (start idempotency by runId).