Test Flow (Flow Designer)
test_flowTest a ServiceNow Flow Designer flow in its draft state without publishing. Provide the flow ID and trigger output values to run the test and get a context ID for monitoring.
Instructions
Test a ServiceNow Flow Designer flow without requiring it to be published. This is the PRIMARY tool to use when building and iterating on a flow — it invokes the same API as the 'Test' button in Flow Designer, running the flow in its current saved (draft) state.
Unlike execute_flow (which requires a published flow and uses sn_fd.FlowAPI), test_flow works on unpublished drafts via the ProcessFlow REST API (POST /api/now/processflow/flow/{id}/test).
Provide the flow's sys_id or scoped name in flow_id, and supply trigger output variable values in output_map. For record-triggered flows this is typically { "current": "<record_sys_id>", "table_name": "" }. Check the flow's trigger configuration in Flow Designer to determine the correct variable names.
The tool returns a context ID on success — use get_flow_context_status to poll the execution, then get_flow_outputs or get_flow_error once complete.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| instance | No | The ServiceNow instance auth alias to use. This is the alias configured via `now-sdk auth --add` (e.g., "myinstance", "prod", "test"). The user will typically refer to this by name when saying things like "on my myinstance instance". If not provided, falls back to the SN_AUTH_ALIAS environment variable. | |
| flow_id | Yes | Flow sys_id (32-char hex) or scoped name (e.g., "x_myapp.my_flow"). The flow does not need to be published. | |
| output_map | Yes | Maps trigger output variable names to concrete test values. Keys are the variable names defined in the flow's trigger configuration in Flow Designer. For record-triggered flows: { "current": "<record_sys_id>", "table_name": "<table>" }. Open the flow in Flow Designer and inspect the trigger to see the available variable names. | |
| scope | No | Scope sys_id for the transaction scope query parameter. If omitted, the scope is auto-resolved from the flow definition. | |
| run_on_thread | No | Whether to run the test synchronously on the current thread. Default: true. |