Skip to main content
skill CX Codex

n8n-workflow-testing-fundamentals — Claude Code skill

n8n-workflow-testing-fundamentals — a skill for testing n8n workflows: validates structure, nodes, data flows, error handling, and execution performance of automation workflows.

MIT 176 installs ★ 533 updated 2026-10-25

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add proffesor-for-testing/agentic-qe --skill n8n-workflow-testing-fundamentals -a claude-code
Open on GitHub

What n8n-workflow-testing-fundamentals does

The skill teaches the agent to validate n8n workflows before and during execution. It checks structure (trigger presence, node connections, credentials), runs test scenarios with different inputs, traces data through the node chain, and verifies how workflows handle errors — API timeouts, invalid fields, missing credentials.

Inside are TypeScript functions for workflow structure validation, test case execution, data tracing across nodes, and error scenario checks. The skill includes a quick validation checklist (connected nodes, trigger setup, data mapping, error workflow definition, credential references) and execution state tables.

Without access to a deployed n8n instance and its API, the skill cannot retrieve workflow data or run tests. Example functions call getWorkflow, executeWorkflow, getExecution — these must be actual n8n API or SDK calls.

What it helps with

  • validate workflow structure before execution — trigger, node connections, credentials
  • test workflow execution with different input data and error scenarios
  • trace data flow between nodes and verify transformations
  • check handling of API timeouts, invalid fields, missing credentials

Example prompts for the agent

  • Check the structure of the customer-onboarding workflow in n8n — does it have a trigger, are all nodes connected, credentials in place
  • Run test scenarios for the email-campaign workflow: valid customer data, missing email, invalid email format
  • Trace data flow through the order-processing workflow — show input and output at each step

How to install n8n-workflow-testing-fundamentals

1Skills CLI (Vercel)

npx skills add proffesor-for-testing/agentic-qe --skill n8n-workflow-testing-fundamentals -a claude-code

2Manually: put the files in place

~/.claude/skills/n8n-workflow-testing-fundamentals/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/n8n-workflow-testing-fundamentals/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about n8n-workflow-testing-fundamentals

How to install n8n-workflow-testing-fundamentals in Claude Code?

Run npx skills add proffesor-for-testing/agentic-qe --skill n8n-workflow-testing-fundamentals -a claude-code, the skill will be placed in ~/.claude/skills/n8n-workflow-testing-fundamentals/SKILL.md.

What does n8n-workflow-testing-fundamentals do?

The skill teaches the agent to test n8n workflows: check structure (triggers, connections, credentials), run test scenarios, trace data through nodes, and validate error handling.

What does n8n-workflow-testing-fundamentals need to work?

It needs access to the n8n API or SDK: the skill uses getWorkflow, executeWorkflow, getExecution functions. Without a deployed n8n instance and its API, it cannot retrieve workflow data or run tests.

Source text

SKILL.md · MIT
---
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

```typescript
// 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

```typescript
// 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 Flow Validation

```typescript
// 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
    validateDataMapping(prev.output, curr.input);
  }

  return dataFlow;
}

// Validate data mapping between nodes
function validateDataMapping(sourceOutput: any, targetInput: any) {
  // Check all required fields are present
  const missingFields: string[] = [];

  for (const [key, value] of Object.entries(targetInput)) {
    if (value === undefined && sourceOutput[key] === undefined) {
      missingFields.push(key);
    }
  }

  if (missingFields.length > 0) {
    console.warn('Missing fields in data mapping:', missingFields);
  }

  return missingFields.length === 0;
}
```

---

## Error Handling Testing

```typescript
// Test error handling paths
async function testErrorHandling(workflowId: string) {
  const errorScenarios = [
    {
      name: 'API timeout',
      inject: { delay: 35000 }, // Trigger timeout
      expectedError: 'timeout'
    },
    {
      name: 'Invalid data',
      inject: { invalidField: true },
      expectedError: 'validation'
    },
    {
      name: 'Missing credentials',
      inject: { removeCredentials: true },
      expectedError: 'authentication'
    }
  ];

  const results: ErrorTestResult[] = [];

  for (const scenario of errorScenarios) {
    // Execute with error injection
    const execution = await executeWithErrorInjection(workflowId, scenario.inject);

    // Check error was caught
    const result = await waitForCompletion(execution.id);

    // Validate error handling
    results.push({
      scenario: scenario.name,
      errorCaught: result.status === 'failed',
      errorType: result.data?.resultData?.error?.type,
      expectedError: scenario.expectedError,
      errorWorkflowTriggered: await checkErrorWorkflowTriggered(execution.id),
      alertSent: await checkAlertSent(execution.id)
    });
  }

  return results;
}

// Verify error workflow was triggered
async function checkErrorWorkflowTriggered(executionId: string): Promise<boolean> {
  const errorExecutions = await getExecutions({
    filter: {
      metadata: { errorTriggeredBy: executionId }
    }
  });

  return errorExecutions.length > 0;
}
```

---

## Node Connection Patterns

### Linear Flow
```
Trigger → Process → Transform → Output
```
**Testing:** Execute once, validate each node output

### Branching Flow
```
Trigger → IF → [Branch A] → Merge → Output
              → [Branch B] →
```
**Testing:** Test both branches separately, verify merge behavior

### Parallel Flow
```
Trigger → Split → [Process A] → Merge → Output
                → [Process B] →
```
**Testing:** Validate parallel execution, check merge timing

### Loop Flow
```
Trigger → SplitInBatches → Process → [Loop back until done] → Output
```
**Testing:** Test with varying batch sizes, verify all items processed

---

## Common Testing Patterns

### Test Data Generation

```typescript
// Generate test data for common n8n patterns
const testDataGenerators = {
  webhook: () => ({
    body: { event: 'test', timestamp: new Date().toISOString() },
    headers: { 'Content-Type': 'application/json' },
    query: { source: 'test' }
  }),

  slack: () => ({
    type: 'message',
    channel: 'C123456',
    user: 'U789012',
    text: 'Test message'
  }),

  github: () => ({
    action: 'opened',
    issue: {
      number: 1,
      title: 'Test Issue',
      body: 'Test body'
    },
    repository: {
      full_name: 'test/repo'
    }
  }),

  stripe: () => ({
    type: 'payment_intent.succeeded',
    data: {
      object: {
        id: 'pi_test123',
        amount: 1000,
        currency: 'usd'
      }
    }
  })
};
```

### Execution Assertions

```typescript
// Common assertions for workflow execution
const workflowAssertions = {
  // Assert workflow completed
  assertCompleted: (execution) => {
    expect(execution.finished).toBe(true);
    expect(execution.status).toBe('success');
  },

  // Assert specific node executed
  assertNodeExecuted: (execution, nodeName) => {
    const nodeData = execution.data.resultData.runData[nodeName];
    expect(nodeData).toBeDefined();
    expect(nodeData[0].executionStatus).toBe('success');
  },

  // Assert data transformation
  assertDataTransformed: (execution, nodeName, expectedData) => {
    const nodeOutput = execution.data.resultData.runData[nodeName][0].data.main[0][0].json;
    expect(nodeOutput).toMatchObject(expectedData);
  },

  // Assert execution time
  assertExecutionTime: (execution, maxMs) => {
    const duration = new Date(execution.stoppedAt) - new Date(execution.startedAt);
    expect(duration).toBeLessThan(maxMs);
  }
};
```

---

## Agent Coordination Hints

### Memory Namespace
```
aqe/n8n/
├── workflows/*          - Cached workflow definitions
├── test-results/*       - Test execution results
├── validations/*        - Validation reports
├── patterns/*           - Discovered testing patterns
└── executions/*         - Execution tracking
```

### Fleet Coordination
```typescript
// Comprehensive n8n testing with fleet
const n8nFleet = await FleetManager.coordinate({
  strategy: 'n8n-testing',
  agents: [
    'n8n-workflow-executor',  // Execute and validate
    'n8n-node-validator',     // Validate configurations
    'n8n-trigger-test',       // Test triggers
    'n8n-expression-validator', // Validate expressions
    'n8n-integration-test'    // Test integrations
  ],
  topology: 'parallel'
});
```

---

## Related Skills
- [n8n-expression-testing](../n8n-expression-testing/) - Expression validation
- [n8n-trigger-testing-strategies](../n8n-trigger-testing-strategies/) - Trigger testing
- [n8n-integration-testing-patterns](../n8n-integration-testing-patterns/) - Integration testing
- [n8n-security-testing](../n8n-security-testing/) - Security validation

---

## Remember

**n8n workflows are JSON-based execution flows** that connect 400+ services. Testing requires validating:
- Workflow structure (nodes, connections)
- Trigger reliability (webhooks, schedules)
- Data flow (transformations between nodes)
- Error handling (retry, fallback, notifications)
- Performance (execution time, resource usage)

**With Agents:** Use n8n-workflow-executor for execution testing, n8n-node-validator for configuration validation, and coordinate multiple agents for comprehensive workflow testing.

© proffesor-for-testing · MIT · proffesor-for-testing/agentic-qe

Similar skills

All skills for Testing and QA →

From the same set73

The whole set →
technical-writing Sets rules for technical writing: lead with value, back claims with examples and sourced numbers, cut filler words. Triggers when drafting blog posts, docs, or tutorials. CX Codex +1 209installs test-design-techniques test-design-techniques applies systematic test design: boundary value analysis, equivalence partitioning, decision tables, state transition testing, and combinatorial coverage. CX Codex +1 208installs brutal-honesty-review The brutal-honesty-review skill guides an agent through blunt reviews of code, tests, and technical decisions. It asks what is broken, why it matters, and how to fix it. CX Codex +1 186installs mobile-testing mobile-testing — a skill for testing iOS and Android apps: gestures, sensors, permissions, device fragmentation, and performance. CX Codex +1 177installs n8n-security-testing n8n-security-testing scans n8n workflows for leaked credentials, checks credential encryption, and tests webhook authentication. CX Codex +1 176installs visual-testing-advanced visual-testing-advanced runs pixel-level visual regression suites, responsive viewport checks, and AI diff analysis to catch broken layouts early. CX Codex +1 163installs pr-review The pr-review skill reviews GitHub PRs for scope, trust-tier assignments, code quality, and security. Use it to prepare clear feedback with actionable next steps. CX Codex +1 155installs agentic-quality-engineering The agentic-quality-engineering skill organizes AI agents around testing, risk analysis, and quality checks. It uses PACTS principles to guide coordination and agent selection. CX Codex +1 153installs

More in the catalog

Project sponsors

Companies that keep this analytics open