Test a Workflow
How do you prove a workflow works? Test its development version with inputs whose answers you know. Inspect the resolved values, then check the outputs and the effects. A development test is a real run. Messages send, records change, and usage is spent.
Use Invoice intake → Check invoice from Your First Workflow. Its example rule is that amounts over 1000 need review:
| Invoice ID | Amount | Expected invoice_id | Expected review_needed |
|---|---|---|---|
| INV-104 | 120 | INV-104 | false |
| INV-105 | 1500 | INV-105 | true |
Decide separately how your flow handles missing IDs and invalid amounts.
Choose what the test can change
Section titled “Choose what the test can change”In the app: open Workflows → Invoice intake → Dev → Check invoice. The header’s Test button has the tooltip Test current flow. Start with this pure calculation. Before testing a provider action, inspect its connection and choose a test record or audience.
With an assistant: every workflow-scoped tool call carries an explicit workflowId. List your workflows with workflow_list:
{ "limit": 100 }Note Invoice intake’s data.items[].id as <workflowId> and check data.hasMore. The default limit is 25 and the maximum is 100. There is no next-page cursor. If the workflow is absent while hasMore is true, use app search and copy its ID from /workflows/<workflowId>/versions/....
List its flows with flow_list:
{ "workflowId": "<workflowId>" }Note Check invoice’s data.items[].id as <flowId>.
Assistant node, development-flow, and discovery tests (run_node, run_flow and run_discover) share one cap per workflow, counted over a UTC day. The default is 200, and a configured 0 means unlimited. At the cap no run starts, and the error begins Agent test-run daily cap reached for this workflow. App tests and API-key runs do not count against it.
Supply the inputs this flow reads
Section titled “Supply the inputs this flow reads”In the app: click Test, enter values, then click Test flow. Those values update the saved development test values and autosave. Test flow saves outstanding edits before dispatch. Later development tests can reuse them. The panel shows the inputs the flow references. Without inputs or required runtime context, Test starts directly.
With an assistant: read the inputs this flow accepts with run_inputs:
{ "workflowId": "<workflowId>", "nodeIdOrFlowId": "<flowId>", "flow": true }data.flowInputs lists id, name, displayName, dataType, isList, testValue, and used. An unused input has no effect. For a custom type with schema fields, testValueShape names the expected keys and whether to send an object or a list of objects. Keep this object as <invoiceLowInputs>, replacing these keys with the Invoice ID and Amount input IDs:
{ "<invoiceIdInputId>": "INV-104", "<amountInputId>": 120}Exact IDs avoid alias collisions. The run tools also accept unambiguous names and display labels. If any input in a development input list lacks both displayName and name, it disables those aliases across that list. Unknown or ambiguous keys reject before dispatch. If you leave a flow input out, the run uses its saved test value. An explicit null, "", false, or 0 overrides it.
Check one node, then the wiring
Section titled “Check one node, then the wiring”Check invoice contains only Return response, which has no app Test action, so use Test current flow. For another eligible node, open its menu and choose Test action. Trigger nodes and Return response are excluded.
For an isolated test, find the changed node with flow_get:
{ "workflowId": "<workflowId>", "flowId": "<flowId>" }Note the node’s data.nodes[].id as <nodeId>. Then read the values it accepts with run_inputs:
{ "workflowId": "<workflowId>", "nodeIdOrFlowId": "<nodeId>" }Prepare <nodeValues>, an object keyed by data.flowInputs[].id and data.nodeInputs[].id. Every referenced flow input needs an explicit value. If you omit one, the call fails with ISOLATED_FLOW_CONTEXT_REQUIRED before execution. Those flow inputs preserve explicit null and empty values. An ordinary node input given null reuses its saved test value.
Run the node alone with run_node, then its containing flow with run_flow:
{ "workflowId": "<workflowId>", "nodeId": "<nodeId>", "inputs": <nodeValues> }{ "workflowId": "<workflowId>", "flowId": "<flowId>", "inputs": <invoiceLowInputs>, "target": "dev" }A node test does not execute upstream nodes. runScope.endToEndValidationRequired reports incoming wiring, not whether your values passed. Inspect configValueProcessed, hasError, and resolutionWarnings on every resolvedConfigs entry. An empty [] means no warning was recorded. Then test the containing flow and repeat with INV-105/1500.
A successful assistant development test also attempts output-type adoption, persisting changed metadata to development. Inspect data.outputTypeAdoption for a node, or data.outputTypeAdoptions and its adoptedNodeIds for a flow. Live runs do not adopt types.
run_discover calls the real action too. It normally deletes its scratch node and keeps the reusable scratch flow. It does not verify another node’s output type.
Follow the run you already started
Section titled “Follow the run you already started”waitSeconds defaults to 60, maximum 120. It bounds waiting, not execution. On success, note data.workflowExecutionId as <workflowExecutionId>. If waiting ends first, the response returns finished: false with the same execution ID. Run tools can also return a successful tool response containing a paused or failed execution. Inspect that execution’s status with execution_get instead of repeating its effects:
{ "workflowId": "<workflowId>", "workflowExecutionId": "<workflowExecutionId>" }If the request reports a builder_approval event, note its approvalId as <id>. After the person handles the approval, resume the run with approval_resume:
{ "approvalId": "<id>" }Check values and effects
Section titled “Check values and effects”In Run history, inspect Inputs, Process → Configurations / Result, and Outputs. Compare both invoice results above. A completed run can still contain unintended null mappings. A loop that collects failed or handled-error iterations produces completed_with_error, not full success. Inspect each iteration.
If you later add invoice storage, identify its collection before testing. Afterwards open Dev → Data tables → invoice, or read the same store with data_record_query:
{ "workflowId": "<workflowId>", "type": "custom.invoice", "env": "dev", "limit": 50 }Check data.items and data.totalCount. Inspect provider destinations too. Keep the execution IDs, expected and actual results, and untested paths.
Next: Debug a Run or Publish a Workflow.