/n8n-workflow-testing-fundamentals

name: n8n-workflow-testing-fundamentals
description: "Comprehensive n8n workflow testing including execution lifecycle, node connection patterns, data flow validation, and error handling strategies. Use when testing n8n workflow automation applications."
category: n8n-testing
priority: high
tokenEstimate: 1200
agents: [n8n-workflow-executor, n8n-node-validator, n8n-trigger-test]
implementation_status: production
optimization_version: 1.0
last_optimized: 2025-12-15
dependencies: []
quick_reference_card: true
tags: [n8n, workflow, automation, testing, data-flow, nodes, triggers]
trust_tier: 3
validation:
  schema_path: schemas/output.json
  validator_path: scripts/validate-config.json
  eval_path: evals/n8n-workflow-testing-fundamentals.yaml

n8n Workflow Testing Fundamentals

<default_to_action> When testing n8n workflows: 1. VALIDATE workflow structure before execution 2. TEST with realistic test data 3. VERIFY node-to-node data flow 4. CHECK error handling paths 5. MEASURE execution performance

**Quick n8n Testing Checklist:**

• All nodes properly connected (no orphans)
• Trigger node correctly configured
• Data mappings between nodes valid
• Error workflows defined
• Credentials properly referenced

**Critical Success Factors:**

• Test each execution path separately
• Validate data transformations at each node
• Check retry and error handling behavior
• Verify integrations with external services

</default_to_action>

Quick Reference Card

When to Use

• Testing new n8n workflows
• Validating workflow changes
• Debugging failed executions
• Performance optimization
• Pre-deployment validation

n8n Workflow Components

| Component | Purpose | Testing Focus | |-----------|---------|---------------| | **Trigger** | Starts workflow | Reliable activation, payload handling | | **Action Nodes** | Process data | Configuration, data mapping | | **Logic Nodes** | Control flow | Conditional routing, branches | | **Integration Nodes** | External APIs | Auth, rate limits, errors | | **Error Workflow** | Handle failures | Recovery, notifications |

Workflow Execution States

| State | Meaning | Test Action | |-------|---------|-------------| | `running` | Currently executing | Monitor progress | | `success` | Completed successfully | Validate outputs | | `failed` | Execution failed | Analyze error | | `waiting` | Waiting for trigger | Test trigger mechanism |

---

Workflow Structure Validation

// Validate workflow structure before execution
async function validateWorkflowStructure(workflowId: string) {
  const workflow = await getWorkflow(workflowId);

  // Check for trigger node
  const triggerNode = workflow.nodes.find(n =>
    n.type.includes('trigger') || n.type.includes('webhook')
  );
  if (!triggerNode) {
    throw new Error('Workflow must have a trigger node');
  }

  // Check for orphan nodes (no connections)
  const connectedNodes = new Set();
  for (const [source, targets] of Object.entries(workflow.connections)) {
    connectedNodes.add(source);
    for (const outputs of Object.values(targets)) {
      for (const connections of outputs) {
        for (const conn of connections) {
          connectedNodes.add(conn.node);
        }
      }
    }
  }

  const orphans = workflow.nodes.filter(n => !connectedNodes.has(n.name));
  if (orphans.length > 0) {
    console.warn('Orphan nodes detected:', orphans.map(n => n.name));
  }

  // Validate credentials
  for (const node of workflow.nodes) {
    if (node.credentials) {
      for (const [type, ref] of Object.entries(node.credentials)) {
        if (!await credentialExists(ref.id)) {
          throw new Error(`Missing credential: ${type} for node ${node.name}`);
        }
      }
    }
  }

  return { valid: true, orphans, triggerNode };
}

---

Execution Testing

// Test workflow execution with various inputs
async function testWorkflowExecution(workflowId: string, testCases: TestCase[]) {
  const results: TestResult[] = [];

  for (const testCase of testCases) {
    const startTime = Date.now();

    // Execute workflow
    const execution = await executeWorkflow(workflowId, testCase.input);

    // Wait for completion
    const result = await waitForCompletion(execution.id, testCase.timeout || 30000);

    // Validate output
    const outputValid = validateOutput(result.data, testCase.expected);

    results.push({
      testCase: testCase.name,
      success: result.status === 'success' && outputValid,
      duration: Date.now() - startTime,
      actualOutput: result.data,
      expectedOutput: testCase.expected
    });
  }

  return results;
}

// Example test cases
const testCases = [
  {
    name: 'Valid customer data',
    input: { name: 'John Doe', email: 'john@example.com' },
    expected: { processed: true, customerId: /^cust_/ },
    timeout: 10000
  },
  {
    name: 'Missing email',
    input: { name: 'Jane Doe' },
    expected: { error: 'Email required' },
    timeout: 5000
  },
  {
    name: 'Invalid email format',
    input: { name: 'Bob', email: 'not-an-email' },
    expected: { error: 'Invalid email' },
    timeout: 5000
  }
];

---

Data Flow Validation

// Trace data through workflow nodes
async function validateDataFlow(executionId: string) {
  const execution = await getExecution(executionId);
  const nodeResults = execution.data.resultData.runData;

  const dataFlow: DataFlowStep[] = [];

  for (const [nodeName, runs] of Object.entries(nodeResults)) {
    for (const run of runs) {
      dataFlow.push({
        node: nodeName,
        input: run.data?.main?.[0]?.[0]?.json || {},
        output: run.data?.main?.[0]?.[0]?.json || {},
        executionTime: run.executionTime,
        status: run.executionStatus
      });
    }
  }

  // Validate data transformations
  for (let i = 1; i < dataFlow.length; i++) {
    const prev = dataFlow[i - 1];
    const curr = dataFlow[i];

    // Check if expected data passed through
    validateDataMappin