Workflow Test Run Execution#

A workflow test run ("draft run") is the full-workflow execution triggered from the Dify console before a workflow is published. It differs from production invocations in three key ways: it operates on the draft Workflow record, sets InvokeFrom.DEBUGGER, and always streams its response.

API Entry Points#

Three console endpoints initiate draft runs (all defined in api/controllers/console/app/workflow.py):

All three parse their payload into a typed Pydantic model (DraftWorkflowRunPayload / AdvancedChatWorkflowRunPayload) and delegate to AppGenerateService.generate(..., invoke_from=InvokeFrom.DEBUGGER, streaming=True) 1.

Trigger-based runs additionally poll for an external trigger event and may supply a root_node_id to start execution from a specific trigger node 2.

Sub-node debug runs are also supported: single-node runs via DraftWorkflowNodeRunApi, and single-iteration/single-loop runs via WorkflowDraftRunIterationNodeApi and WorkflowDraftRunLoopNodeApi.

Workflow Resolution: Draft vs. Published#

AppGenerateService._get_workflow() is the single decision point 3:

• invoke_from == InvokeFrom.DEBUGGER → WorkflowService.get_draft_workflow()
• Any other invoke_from → WorkflowService.get_published_workflow()

If no draft exists, the call raises ValueError("Workflow not initialized").

App Generation and Entity Construction#

AppGenerateService._dispatch_generate() routes on app_model.mode 4. For debug runs (always streaming=True):

• AppMode.WORKFLOW → WorkflowAppGenerator().generate(...)
• AppMode.ADVANCED_CHAT → AdvancedChatAppGenerator().generate(...)

Inside WorkflowAppGenerator.generate(), the sequence is:

1. File access scope — _bind_file_access_scope() scopes all file lookups to the tenant
2. User input preparation — The generator resolves the entry node (via root_node_id or the default root) and checks its type. For Start entry nodes, _prepare_user_inputs() validates inputs against the app's variable schema, applies defaults, and handles file uploads. For webhook, schedule, and plugin entry nodes, the generator preserves the event inputs without modification, as they are already adapted event data 5
3. Generate entity — a WorkflowAppGenerateEntity is built with invoke_from=DEBUGGER
4. Triggered-from tagging — invoke_from == DEBUGGER maps to WorkflowRunTriggeredFrom.DEBUGGING 6, stamped on the run record
5. Repository creation — fresh WorkflowExecutionRepository and WorkflowNodeExecutionRepository instances are created with a dedicated sessionmaker 7

Worker Thread and Graph Initialization#

WorkflowAppGenerator._generate() spawns a threading.Thread that runs WorkflowAppRunner. The worker:

1. Re-fetches the Workflow record inside its own DB session (the main thread releases the connection before spawning) 8
2. Instantiates WorkflowAppRunner with the generate entity, queue manager, and repositories
3. Calls WorkflowAppRunner._init_graph(), which builds a DifyGraphInitContext and calls Graph.init() via DifyNodeFactory

For full draft runs, graph_config is the complete workflow.graph_dict — every node and every edge. For single-iteration or single-loop debug runs (single_iteration_generate, single_loop_generate), the runner pre-filters graph_config inside _get_graph_and_variable_pool_for_single_node_run() to the target container node and its internal nodes, and passes skip_validation=True.

Graph Topology: Reachable vs. All Nodes#

WorkflowGraphTopology (api/core/workflow/graph_topology.py) provides static graph analysis. It is not invoked during execution — it is used at validation time (draft-save and publish).

• from_graph(graph) — builds an incoming-edge adjacency map from graph_dict
• upstream_node_ids(target_node_id) — BFS returning all nodes reachable upstream of a target; edges referencing non-existent node IDs (half-deleted graphs) are silently skipped
• is_upstream(source, target) — point check used by Agent v2 validation

The draft vs. publish distinction in validation (WorkflowAgentNodeValidator):

• validate_draft_workflow() — validate_previous_node_topology=False: all Agent v2 nodes are checked regardless of graph position
• validate_published_workflow() — validate_previous_node_topology=True: previous_node_output_refs are confirmed against topologically reachable upstream nodes

During a draft test run, nodes that are unreachable from the start node (e.g., disconnected canvas nodes) exist in graph_dict but are never visited by the graph engine's traversal.

Key Files#