Skip to main content

Testing and replay

The test environment​

@fluidgrids/workflows/testing runs durable functions in your test runner, with activities mocked and time under your control:

workflows/refund-order.test.ts
import { TestWorkflowEnvironment, replay } from '@fluidgrids/workflows/testing';
import { approve, refundOrder } from './refund-order';
import { nodes as n } from '../.fluidgrids/nodes';

test('refunds once approved', async () => {
const env = await TestWorkflowEnvironment.create();
env.mock(n.stripe.refund, async () => ({ id: 're_1' }));

const handle = await env.start(refundOrder, { input: { id: 'ch_1' } });
await handle.signal(approve, { by: 'ana' });

expect(await handle.result()).toEqual({ refunded: 're_1', approvedBy: 'ana' });
await replay(refundOrder, handle.history()); // throws DeterminismViolation on a mismatch
});
  • env.mock(operation, fn) replaces a node operation; mockChild replaces a child workflow.
  • env.registerActivity(implementation) runs a user activity in the test, and env.mockActivity(name, fn) replaces one.
  • handle.query(name, args), handle.update(name, args) and env.startWithUpdate(...) exercise queries and updates, and handle.reset() tests a reset.
  • Time is simulated, so a two-day ctx.sleep finishes at once.
  • The environment appends exactly the events the service appends, and retries activities with the same policy, so the history it produces is the one a real run would record.

Run the project's tests with fluidgrids test. Python projects have the same environment in fluidgrids_workflows.testing.environment; see Durable functions in Python.

A few things differ from a real run, and are documented with the package: workflow tasks run in the test process without the determinism sandbox unless you pass taskExecutor, a failed workflow task stops the run instead of being retried, and activity timeouts are not timed (a mock can throw a TimeoutFailure instead).

Testing graph-builder workflows​

simulate(definition, { trigger, mocks }) walks a tier-1 graph in process with mocked nodes, which is enough to check routing. It does not evaluate expressions or model retries and waits, so keep end-to-end checks in a test workspace.

Replaying real runs​

A run's event history is a complete record of what the function did. Replaying it against your current code proves the code would make the same decisions, which is exactly what a hotfix or a refactor must guarantee.

fluidgrids history <runId> --out histories/order-7.history.json
fluidgrids replay histories/order-7.history.json --isolate
fluidgrids test --replay histories/
  • replay runs the history against the project's code and fails on the first mismatch.
  • --isolate uses the same sandbox the managed engine uses.
  • test --replay <dir> runs the project's tests, then replays every *.history.json in the directory. Run it in CI to catch non-deterministic changes before they ship.

To find out exactly where a replay diverges, use the replay debugger.

Next steps​