Skip to content
flow8

Testing Flows

Testing Flows

flow8 includes a built-in testing framework that lets you write deterministic tests for flows without making real external calls.

Concepts

Test Suite — a collection of test cases for a specific flow version. Created per flow, versioned with the flow.

Test Case — one test scenario with defined input args and expected outputs per module step.

Baseline Play — a real play execution that you promote as the “golden” reference. Its recorded outputs become the expected values.

Test Fixture — a recording of all external component calls (HTTP requests, AI calls, file reads) made during a baseline play. Replayed during tests so no real calls are made.

Create a Test Suite

Terminal window
POST /api/flows/65flow1/test-suites
{"name": "Invoice Processing Tests", "flowVersion": 1}

Create a Test Case

Terminal window
POST /api/test-suites/65suite1/cases
{
  "name": "Standard invoice with attachment",
  "baselinePlayId": "65play-baseline",
  "flowletInputsByRef": {
    "fetchInvoice": {"invoiceId": "INV-TEST-001"}
  },
  "expectedOutByRef": {
    "extractData": {"invoiceNumber": "INV-TEST-001", "amount": 1250.00},
    "sendNotification": {"messageId": "test-message-id"}
  }
}

Promote a Baseline Play

Run the flow against real data once to create the baseline:

Terminal window
POST /api/flows/65flow1/run
{"args": {"invoiceId": "INV-TEST-001"}, "recordFixture": true}

This records all external calls into a DBTestFixture. Promote the play:

Terminal window
POST /api/plays/65play-baseline/promote-baseline
{"testCaseId": "65case1"}

Run Tests

Terminal window
POST /api/test-suites/65suite1/run

Response:

{
  "suiteId": "65suite1",
  "passed": 4,
  "failed": 1,
  "total": 5,
  "results": [
    {"caseId": "65case1", "name": "Standard invoice", "passed": true},
    {"caseId": "65case2", "name": "Missing attachment", "failed": true, "diffs": [{
      "ref": "extractData",
      "field": "amount",
      "expected": 500.00,
      "actual": 0
    }]}
  ]
}

CI/CD Integration

Terminal window
# In your CI pipeline:
SUITE_ID="65suite1"
RESULT=$(curl -s -H "Authorization: Bearer $FLOW8_TOKEN" \
  -X POST "http://flow8-host:4454/api/test-suites/$SUITE_ID/run")


FAILED=$(echo $RESULT | jq '.failed')
if [ "$FAILED" -gt 0 ]; then
  echo "Flow tests failed: $FAILED failures"
  echo $RESULT | jq '.results[] | select(.passed == false)'
  exit 1
fi
echo "All flow tests passed"