Testing Flows

fyrn provides several ways to test flows before and after deployment — local transform testing, preview mode, message traces, and live log streaming.

Local testing with the CLI

Test a flow’s transform locally without deploying or making any API calls:

fyrn flow test flows/my-flow.yaml --sample-data test-payload.json

This:

Parses the YAML
Compiles the flow
Applies the mapping to your sample data
Outputs the transformed result

Create test payloads

{
  "id": "ORD-001",
  "customer": {
    "name": "Alice Johnson",
    "email": "alice@example.com"
  },
  "total_price": 149.50,
  "currency": "usd",
  "line_items": [
    {"sku": "WIDGET-A", "quantity": 2, "price": 29.99},
    {"sku": "WIDGET-B", "quantity": 1, "price": 89.52}
  ]
}

AI-generated test payloads

The CLI can generate realistic test payloads using AI, based on the flow’s source connector schema and event type:

fyrn flow test flows/my-flow.yaml --generate-payload

This inspects the flow’s source connector (e.g., Shopify orders/create) and generates a payload that matches the expected schema, including nested objects, realistic field values, and edge cases like null fields or empty arrays.

In interactive mode, you can iterate on the generated payload before running the test:

fyrn flow test flows/my-flow.yaml --generate-payload --interactive

Interactive mode lets you tweak individual fields, add edge-case values, or request variations (e.g., “generate one with multiple line items and a discount code”). The AI preserves the connector’s schema constraints while incorporating your modifications.

You can also generate payloads via MCP:

{
  "name": "generate_test_payload",
  "arguments": {
    "flow_id": "...",
    "event_type": "orders/create",
    "variations": 3
  }
}

This returns multiple payload variations suitable for covering common and edge-case scenarios.

Preview mode (MCP)

Preview how a deployed flow transforms data without actually delivering:

{
  "name": "preview_flow",
  "arguments": {
    "flow_id": "...",
    "sample_payload": {
      "id": "ORD-TEST",
      "customer": {"name": "Test User", "email": "test@example.com"},
      "total_price": 99.99
    }
  }
}

Returns the transformed output and execution trace without side effects.

Message traces

After deployment, every processed message has a detailed trace showing step-by-step execution:

Every message includes a traceSteps array that records what happened at each stage of the pipeline. Each entry contains the step name, its input and output payloads, execution duration, and a status (success, skipped, or error).

Example trace (from the API or web UI):

{
  "message_id": "msg_abc123",
  "flow_id": "flow_xyz",
  "status": "delivered",
  "traceSteps": [
    {
      "step": "receive",
      "status": "success",
      "duration_ms": 2,
      "output": { "id": "ORD-001", "total_price": 149.50 }
    },
    {
      "step": "dedup",
      "status": "skipped",
      "duration_ms": 1,
      "reason": "dedup not configured"
    },
    {
      "step": "transform",
      "status": "success",
      "duration_ms": 12,
      "input": { "id": "ORD-001", "total_price": 149.50 },
      "output": { "order_id": "ORD-001", "amount": 14950 }
    },
    {
      "step": "deliver",
      "status": "success",
      "duration_ms": 134,
      "output": { "response_code": 200 }
    }
  ]
}

In the web UI, open a flow and click Messages to see the message list. Select any message to expand its trace — each step is shown as a collapsible panel with input/output diffs and timing.

Via the API, fetch traces with:

curl -H "Authorization: Bearer $FYRN_TOKEN" \
  https://api.fyrn.ai/v1/flows/<flow-id>/messages/<message-id>/trace

Failed steps include an error field with the error message and stack context, making it straightforward to pinpoint where a pipeline broke.

Via CLI

# Search for specific messages
fyrn logs search <flow-id> --status failed --since 1h

# Replay a failed message through the pipeline
fyrn logs replay <message-id>

Via MCP

{
  "name": "get_messages",
  "arguments": {
    "flow_id": "...",
    "status": "failed",
    "limit": 10
  }
}

Pipeline visualizer

The pipeline visualizer in the web UI renders your flow’s execution plan as a directed graph. Open any flow and click Pipeline to see it.

The graph displays each stage as a node in execution order:

receive → dedup → ordering → aggregate → transform → deliver

Stages that are not configured for the flow appear greyed out and labeled “skipped.” Active stages show:

Avg. duration — mean execution time over the selected time window
P99 duration — worst-case latency
Error rate — percentage of messages that failed at that stage
Throughput — messages per second

Click any node to drill into its recent message traces. Edges between nodes are color-coded: green for healthy throughput, yellow when error rates exceed your alert threshold, and red when a stage is failing consistently.

The visualizer updates in near real-time for deployed flows, making it useful for monitoring during rollouts or load tests.

Dry-run mode

Dry-run mode lets you validate a flow against real production data without delivering anything to the target system. Enable it in your flow config:

flow:
  name: shopify-to-netsuite
  dryRun: true
  source:
    connector: shopify
    event: orders/create
  # ... rest of config

With dryRun: true, the flow executes the full pipeline — receive, dedup, ordering, aggregation, and transform — but skips the actual delivery step. Messages are logged with delivery_status: dry_run so you can inspect the transformed output without side effects.

# View dry-run results
fyrn logs search <flow-id> --delivery-status dry_run

Each dry-run message trace includes the complete traceSteps array, including what the delivery payload would have been. This makes it straightforward to verify that transforms produce the correct output before switching to live delivery.

When you are satisfied with the results, set dryRun: false (or remove the field) and redeploy:

fyrn flow deploy flows/my-flow.yaml

Dry-run mode is particularly useful when onboarding a new connector, changing transform logic on an active flow, or validating self-healing repairs before they go live.

Live log streaming

Stream messages in real-time for a deployed flow:

fyrn logs tail <flow-id>
fyrn logs tail <flow-id> --status failed

Press Ctrl+C to stop.

Testing checklist

Step	Tool	What it validates
Parse YAML	`fyrn flow test`	Syntax, schema, expressions
Transform sample data	`fyrn flow test --sample-data`	Mapping correctness
Preview with real flow	`preview_flow` (MCP)	End-to-end transform
Dry-run with real data	Deploy with `dryRun`	Full pipeline without delivery
Live smoke test	`curl` + `fyrn logs tail`	End-to-end with delivery

What’s next

Creating Flows — Build and validate flows
CLI Usage — All testing commands
Alerting — Get notified when things go wrong