n8n Test Framework

Zero-knowledge testing framework for n8n workflows using YAML.

Quick Start

# Install dependencies
npm install

# Run tests
./n8n-test run

# Generate test from workflow
./n8n-test generate workflow.json

Features

• ✅ Zero Knowledge - Write tests without knowing n8n internals
• ✅ YAML Format - Simple, readable test definitions
• ✅ Auto-Mocking - External services mocked automatically
• ✅ No Build Steps - Runs directly from TypeScript
• ✅ Coverage Tracking - See which nodes are tested
• ✅ Multiple Triggers - Webhooks, schedules, emails
• ✅ Wildcard Matching - Use * for dynamic values

Test Format

Minimal Test

test: My Workflow Test
workflow: ./my-workflow.json
cases:
  - name: Happy path
    input:
      email: [email protected]
    expect:
      success: true
      userId: "*"

With Mocks (Optional)

test: User Registration
workflow: ./registration.json
cases:
  - name: New user
    input:
      email: [email protected]
      name: New User
    expect:
      created: true
      emailSent: true
    mocks:
      "User API":
        status: 201
        body: { id: "user-123" }

Commands

# Analyze workflow structure
./n8n-test analyze workflow.json

# Generate test from workflow
./n8n-test generate workflow.json

# Generate default mocks
./n8n-test generate-mocks workflow.json

# Run all tests
./n8n-test run

# Run specific pattern
./n8n-test run -p "**/*user*.test.yaml"

# With coverage
./n8n-test run --coverage

How It Works

1. Workflow Analysis - Automatically detects inputs, outputs, and external services
2. Smart Defaults - Generates sensible mocks for common services
3. Autogeneration - Mock returns whatever you expect in the test

Convention-Based Testing

Create workflow.examples.json:

[
  {
    "scenario": "Success",
    "email": "[email protected]",
    "expect": { "success": true }
  }
]

Then generate tests:

./n8n-test generate workflow.json

Documentation

• Architecture - Framework design and components
• Zero-Knowledge Testing - Write tests without n8n knowledge
• Coverage - Test coverage tracking (shows 0% by design)
• Node Type Tests - Comprehensive node type coverage
• Sub-Workflow Testing - Testing workflows that call other workflows
• Multi-Workflow Orchestration - Complex workflow chains and orchestration patterns
• Enterprise Workflows - Production-grade workflow patterns
• Test Summary - Complete overview of all 95 tests
• n8n Best Practices - Production patterns and recommendations

Examples

See examples directory:

• Test Suites - YAML test examples
• Workflows - Sample workflows

License

MIT