Testing Workflows

Workflow tests describe a scenario: prepare fixtures, trigger an event, then assert the externally visible result. Tests are especially useful for workflows that save resources, enforce access, send responses, or coordinate asynchronous work.

Test file shape

Workflow tests live with the system and reference the workflow under test.

{
    "identifier": "create_task_from_project",
    "description": "Creates an open task for a project",
    "priority": "medium",
    "fixtures": [],
    "trigger": {},
    "assertions": [],
    "workflow": "CreateProjectTask"
}

Use clear identifiers that describe behavior. The test does not need to repeat implementation details.

Fixtures

Fixtures create the records needed by the scenario.

{
    "type": "entity",
    "module": "projects",
    "alias": "project",
    "fields": {
        "name": "Example Project",
        "status": "active"
    }
}

Use aliases so the trigger and assertions can refer to the fixture without hard-coding generated IDs.

Triggers

A webhook trigger can bind the current resource and provide input data.

{
    "type": "webhook",
    "entry": "createProjectTask",
    "event": "createProjectTask",
    "module": "projects",
    "bindings": {
        "default": "fixture:project"
    },
    "data": {
        "title": "Prepare report"
    },
    "request": [],
    "fields": [],
    "where": []
}

Model the trigger from the user’s point of view: which event fired, which resource was selected, and which input was submitted.

Assertions

Assertions should check outcomes, not every internal step.

{
    "type": "field_equals",
    "module": "tasks",
    "field": "status",
    "value": "open",
    "where": {
        "title": "Prepare report"
    },
    "selector": []
}

Good assertions include:

• A resource was created with expected fields.
• A status changed.
• A response contains expected data.
• A file record exists.
• A policy allows or filters records as expected.
• An async launcher marked a job as queued.

Testing async workflows

For long-running jobs, test the smallest stable boundary:

• The sync launcher validates input and starts the worker.
• The worker changes a durable field or creates a durable result.
• Failure paths save or log a neutral error state.

Avoid asserting implementation-only progress steps unless the progress output is part of the feature contract.

Test checklist

• The fixture data is generic and contains no real company, domain, customer, or infrastructure values.
• The trigger matches the workflow’s public event.
• Assertions cover the business result.
• Failure or empty paths are tested when they change behavior.
• Policy workflows are tested for both privileged and restricted roles.