n8n-workflow-testing-fundamentals

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: '[email protected]' },
    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