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, inject SKIP_PREPARE_USER_INPUTS_KEY = True to bypass normal input validation, 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 — _prepare_user_inputs() validates inputs against the app's variable schema; skipped when SKIP_PREPARE_USER_INPUTS_KEY is set 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#