Testing Workflows

Use WorkflowTestHarness so tests drive the same replay and command model as the production runtime.

Basic Flow

final test = WorkflowTestHarness(modules: [ordersModule]);
final run = await test.start(orderWorkflow, order);

await run.drain();
expect(await run.openWorkItems(), hasLength(1));

await run.respond(approveOrder, Approval.approved());

final completed = await run.run;
expect(completed.status, WorkflowRunStatus.completed);
expect(orderHandler.exitOf(completed).isSuccess, isTrue);

What to Test

• success and every expected failure;
• restart after each operation, work request, event, and timer;
• operation retry followed by success and exhaustion;
• duplicate event delivery and work response;
• cancellation while commands are pending or claimed;
• parallel, race, quorum, and bounded forEach behavior;
• saga compensation order;
• immutable digest conflicts;
• payload validation at start and completion boundaries.

PostgreSQL Conformance

In-memory tests prove orchestration behavior. PostgreSQL tests additionally prove row locking, atomic commits, leases, fencing, and schema/RPC parity. Keep both levels; one does not replace the other.

Avoid Test-Only APIs

Do not invoke handler functions directly. Start the definition reference, drive durable commands, and inspect the terminal WorkflowExit.