Testing Workflows

Test your workflows before deployment to ensure they work correctly and handle edge cases. Workflow testing creates real executions with results tracked per node.

Test Run Overview

Test runs execute your workflow through the same pipeline as production executions. There is no separate "test environment" -- testing creates a real execution record and processes each node. Runs of an undeployed workflow are tagged as development runs (and are not billed as production executions); runs of a deployed workflow count as production.

Starting a Test Run (Batch Workflows)

1. Save the workflow (the Run button is disabled until the workflow is saved and has nodes)
2. Click the Run button in the workflow builder toolbar
3. The builder validates node configuration first; errors open the validation sidebar and block the run
4. The workflow is auto-saved and the execution is submitted for processing
5. Watch real-time node status updates on the canvas
6. Review execution traces and output data

A builder Run starts the workflow with empty trigger inputs. To test with a realistic payload, trigger the workflow with data instead:

• REST API: POST /api/v1/workflows/{workflowId}/execute with a triggerInputs object in the body. Both draft and deployed workflows can be executed this way.
• Webhook trigger: call the workflow's webhook endpoint (/api/v1/webhooks/{workflowId}) with the payload your external system would send.

Starting a Test Session (Streaming Workflows)

For streaming workflows, the toolbar Run button opens the live test panel instead:

1. Click Run ("Run with live mic / text") -- the test panel opens on the right
2. Click Start Test Session to connect
3. Interact with the workflow using your microphone or by typing text; the conversation transcript streams into the panel
4. The live session doubles as the execution for tracing -- clicking a node on the canvas during or after the session shows that session's spans

What Happens During a Test

1. Execution record created with status pending
2. STRONGLY_SERVICES generated dynamically based on the workflow's node dependencies (add-ons, data sources, AI models)
3. Execution submitted for processing; a submission failure marks the execution failed and queues an automatic retry
4. Nodes processed through the workflow graph
5. Traces recorded for each node execution
6. Execution status updated to completed or failed with an end timestamp

Real-Time Execution Visualization

During test runs, the workflow builder canvas shows live node status updates.

Node States

State	Appearance	Meaning
Idle	Gray	Not yet reached by execution
Running	Orange	Currently executing
Complete	Green	Finished successfully
Error	Red	Encountered an error

Execution Flow

• Nodes update their visual state as execution progresses through the graph
• Parallel branches (via parallel-branch node) show multiple nodes executing simultaneously
• Conditional branches (switch-case, conditional) show which path was taken

Node Tracing

Every node execution produces a span that provides detailed tracing for each step.

Span Types

Type	Description
WORKFLOW	Root span covering the entire execution
NODE	Individual node execution
LLM	AI Gateway / LLM call within a node
TOOL	Tool call (MCP or native)
RETRIEVAL	RAG or knowledge base retrieval
AGENT	Agent reasoning loop
CHAIN	Chain of operations
EMBEDDING	Embedding generation
PARSER	Parsing operation
DISTRIBUTED	Distributed (fan-out) work item
SYNTHETIC	Synthetic span filled in for gaps in a trace
SESSION	Streaming: root span for a streaming session
TURN	Streaming: one span per conversational turn
OPERATION	Streaming: STT/TTS API call within a node

Span Data

Each span records:

Field	Description
execution_id	Parent execution ID
span_type	One of the types above
parent_span_id	ID of parent span (for tree structure)
start_time	When the span started
end_time	When the span completed
status	running, completed, failed
inputs	Data received by the node
outputs	Data produced by the node
error	Error message if failed
metadata	Additional context (model used, token count, etc.)

Viewing Spans

Click any node on the canvas to open the node debug panel for the current execution:

• Output data: The JSON output produced by the node
• Input data: What the node received from upstream nodes
• Timing: Start time, end time, and duration
• Errors: Error message and details if the node failed
• Nested spans: For agent nodes, sub-spans for each LLM call and tool invocation

For past runs, open Workflow Monitor, select the workflow's execution history, and open an execution's trace to see the full span tree.

Span Tree

Spans form a hierarchical tree:

WORKFLOW (root)
  ├── NODE: webhook (trigger)
  ├── NODE: ai-gateway
  │   └── LLM: model call
  ├── NODE: react-agent
  │   ├── AGENT: reasoning loop
  │   ├── LLM: tool selection
  │   ├── TOOL: web-search call
  │   └── LLM: final response
  └── NODE: webhook-response

Inspecting Execution Results

Execution Details

Click on a completed execution to view:

• Execution ID and status (completed, failed, pending, running)
• Start time and end time
• Duration calculated from start to end
• Trigger inputs that initiated the execution
• Error message if the execution failed

Node-Level Output

Click any node in a completed execution to view:

• The JSON output produced by that node
• Input data received from upstream connections
• Duration of that specific node
• Error details if the node failed

Data flows between nodes using JSONPath input mappings. For example, a node might reference $.output.text from a previous node's output.

Execution Logs

Each execution also writes log entries:

• info level: execution start, node completions
• error level: failures with error messages and details
• Each log entry records the workflow, execution, user, and timestamp

Testing Best Practices

Test Data Preparation

1. Use realistic data that matches production input formats
2. Test edge cases: empty arrays, null values, missing fields
3. Test error paths: invalid data that should trigger error handling
4. Test conditional branches: provide input that exercises each branch of switch-case and conditional nodes

Iterative Testing

1. Start simple: Test with basic valid input first
2. Review spans: Check each node's input/output in the span data
3. Fix configuration: Update node settings based on span inspection
4. Test edge cases: Gradually add boundary and error conditions
5. Verify full flow: Ensure data passes correctly through all connections

Testing Agent Workflows

Agent nodes (react-agent, supervisor-agent) produce multiple sub-spans:

1. Review the agent's reasoning loop in the span tree
2. Check which tools the agent selected and why
3. Verify LLM call spans for correct prompt and response
4. Test with different inputs to ensure the agent handles varied scenarios

Testing Data Source Connections

When testing nodes that connect to external data sources (databases, APIs):

1. Verify data source credentials are configured correctly
2. Check that the connection type (addon or datasource) and IDs are set
3. Test with a small query first before running full data operations
4. Review the node's span output to confirm data was retrieved correctly

Common Testing Issues

Issue: Execution Stays in Pending Status

Possible causes:

• The workflow already has an execution in flight (workflows run one execution at a time by default)
• The workflow's compute is still starting
• STRONGLY_SERVICES generation failed

Solutions:

• Wait for or cancel the in-flight execution
• Check the workflow's deployment status
• Review execution logs for service configuration errors

Issue: Node Fails with Connection Error

Possible causes:

• Data source credentials are invalid or expired
• Add-on service is not running
• The external service is unreachable

Solutions:

• Verify data source configuration in the Data Sources section
• Check add-on health status
• Review the node's span error message for specific details

Issue: Agent Not Using Tools

Possible causes:

• MCP Tools Provider not connected to the agent's tools connector
• MCP server not enabled or not deployed
• Agent system prompt does not mention available tools

Solutions:

• Verify the tools connector (bottom of agent node) has a connection
• Check the MCP server's status on the Workflow Tools page
• Update the agent's system prompt to reference the available tools

Issue: Incorrect Data Passed Between Nodes

Possible causes:

• Input mapping references wrong field path
• Upstream node output format changed
• JSONPath expression is incorrect

Solutions:

• Inspect span outputs for the upstream node to see actual data structure
• Update input mappings to use correct JSONPath references (e.g., $.output.field)
• Use set-fields node to reshape data between nodes

Execution Resume and Checkpoints

Executions that stop in a resumable state (failed, error, waiting, paused) can be resumed from their last checkpoint:

• The execution retains its ID and accumulated trace data and continues from the checkpoint rather than restarting
• Resume is only available when the execution recorded a resumable checkpoint
• Executions waiting on a human-checkpoint node are resumed the same way, optionally with the approver's input data

Testing Checklist

Before deploying to production, verify:

Functionality

• All nodes execute successfully with valid input
• Data flows correctly through all connections
• Conditional branches route correctly
• Agent nodes select appropriate tools

Error Handling

• Invalid input is handled gracefully
• External service failures produce clear error spans
• Retry logic works for transient failures

Data Validation

• Node outputs match expected format
• Input mappings reference correct JSONPath fields
• Data transformations produce correct results

Performance

• Execution completes within acceptable time
• No unnecessary sequential dependencies
• Large data sets are handled without timeout

Next Steps

Once your workflow is thoroughly tested:

• Deploy to production
• Monitor workflow executions
• Review workflow examples