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
npx skills add proffesor-for-testing/agentic-qe --skill n8n-workflow-testing-fundamentals -a claude-codeWhat 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-onboardingworkflow in n8n — does it have a trigger, are all nodes connected, credentials in place - Run test scenarios for the
email-campaignworkflow: valid customer data, missing email, invalid email format - Trace data flow through the
order-processingworkflow — 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-code2Manually: put the files in place
~/.claude/skills/n8n-workflow-testing-fundamentals/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/n8n-workflow-testing-fundamentals/
1Skills CLI (Vercel)
npx skills add proffesor-for-testing/agentic-qe --skill n8n-workflow-testing-fundamentals -a codex2Manually: put the files in place
.agents/skills/n8n-workflow-testing-fundamentals/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add proffesor-for-testing/agentic-qe --skill n8n-workflow-testing-fundamentals -a cursor2Manually: put the files in place
.cursor/skills/n8n-workflow-testing-fundamentals/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install proffesor-for-testing/agentic-qe assets/skills/n8n-workflow-testing-fundamentals2Manually: put the files in place
.github/skills/n8n-workflow-testing-fundamentals/SKILL.md1Skills CLI (Vercel)
npx skills add proffesor-for-testing/agentic-qe --skill n8n-workflow-testing-fundamentals -a gemini-cli2Platform CLI
gemini skills install https://github.com/proffesor-for-testing/agentic-qe --path assets/skills/n8n-workflow-testing-fundamentalsManually: put the files in place
.devin/skills/n8n-workflow-testing-fundamentals/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add proffesor-for-testing/agentic-qe --skill n8n-workflow-testing-fundamentals -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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