Testing Strategies

Testing Utilities

Use our testing utilities to validate workflow behavior with ease.

Dependency Mocking

Mock external services for reliable and isolated testing.

Workflow Assertions

Comprehensive assertions for workflow states and outcomes.

Testing Utilities

Basic Test

import { useWorkflowEngine } from '@identity-flow/sdk/testing';
import { describe } from 'vitest';

describe.concurrent('Workflows', () => {
const test = useWorkflowEngine({
workflows: { path: new URL('./workflows', import.meta.url).href },
});

test('starts and runs a workflow', async ({ engine, expect, task, waitFor }) => {
const workflow = await engine.defineWorkflow(task.id, async (flow) => {
const { params } = flow;

      const result = await flow.do('First step', async () => {
        await scheduler.wait(50); // Wait shortly before continuing
        return { output: 'First step result' };
      });

      await flow.sleep('Wait', '0.1 seconds');

      const result2 = await flow.do('Second step', () => {
        return { output: 'Second step result' };
      });

      return [result, result2, flow.instance.createdAt, params];
    });

    const instance = await engine.start(workflow.id, { params: undefined });

    await waitFor(instance).toHaveStep({ name: 'Wait', status: 'SLEEPING' });
    await waitFor(instance).toHaveStep({ name: 'Second step', status: 'COMPLETED' });

    await waitFor(instance).toMatch({
      status: 'COMPLETED',
      data: [
        { output: 'First step result' },
        { output: 'Second step result' },
        expect.any(Date),
        undefined,
      ],
    });

});
});

Mocking Dependencies

Learn more about dependency injection in Integrations.

test('mocks external service', async ({ engine, expect }) => {
  const mockClient = {
    request: vi.fn().mockResolvedValue({ data: { user: { id: 1 } } })
  };

  const workflow = await engine.defineWorkflow('test', {
    bindings: {
      GraphqlClient: () => mockClient
    }
  }, async (flow) => {
    const client = flow.use(GraphqlClient);
    return await client.request('query { user { id } }');
  });

  const instance = await engine.start(workflow.id);
  await expect(instance).toComplete();
  expect(mockClient.request).toHaveBeenCalled();
});

Testing Features

Pure Function Design

Test workflows like pure functions with predictable outcomes.

Injectable Dependencies

Easy mocking of external services for isolated testing.

Async Support

Test asynchronous flows with built-in async/await support.

Step Validation

Validate step-by-step execution with detailed assertions.

Common Test Scenarios

Step Completion

await waitFor(instance).toHaveStep({
  name: 'process payment',
  status: 'COMPLETED'
});

Error Handling

See Error Handling for strategies.

await expect(instance).toError({
  step: 'validate input',
  error: expect.stringContaining('Invalid input')
});

Timeout Behavior

See Complex State Management for timeout patterns.

await waitFor(instance).toHaveStep({
  name: 'long operation',
  status: 'timeout'
});

State Transitions

await waitFor(instance).toMatch({
  status: 'COMPLETED',
  data: expect.objectContaining({
    processed: true
  })
});

Best Practices

Isolate Tests

Use fresh engine instances and mock dependencies for each test.

Test Edge Cases

Verify error handling, timeouts, and retry behavior.

Maintain Clarity

Use descriptive test names and document complex scenarios.

Testing Utilities Reference

useWorkflowEngine

Creates an isolated test environment for workflows.

waitFor

Async assertions for workflow states and transitions.

expect

Extended assertions for workflow testing.

task

Test-specific context and utilities.