n8n/.github/claude-templates/e2e-test.md

E2E Test Task Guide

Required Reading

Before writing any code, read these files:

packages/testing/playwright/AGENTS.md      # Patterns, anti-patterns, entry points
packages/testing/playwright/CONTRIBUTING.md # Detailed architecture (first 200 lines)

Spec Validation

Before starting, verify the spec includes:

Required	Example
File(s) to modify	tests/e2e/credentials/crud.spec.ts
Specific behavior	"Verify credential renaming updates the list"
Pattern reference	"Follow existing tests in same file" or "See AGENTS.md"

If missing, ask for clarification. Don't guess at requirements.

Commands

# Run single test
pnpm --filter=n8n-playwright test:local tests/e2e/your-test.spec.ts --reporter=list 2>&1 | tail -50

# Run with pattern match
pnpm --filter=n8n-playwright test:local --grep "should do something" --reporter=list 2>&1 | tail -50

# Container tests (requires pnpm build:docker first)
pnpm --filter=n8n-playwright test:container:sqlite --grep @capability:email --reporter=list 2>&1 | tail -50

Test Structure

import { test, expect } from '../fixtures/base';
import { nanoid } from 'nanoid';

test('should do something @mode:sqlite', async ({ n8n, api }) => {
  // Setup via API (faster, more reliable)
  const workflow = await api.workflowApi.createWorkflow(workflowJson);

  // UI interaction via entry points
  await n8n.start.fromBlankCanvas();

  // Assertions
  await expect(n8n.workflows.getWorkflowByName(workflow.name)).toBeVisible();
});

Entry Points

Use n8n.start.* methods - see composables/TestEntryComposer.ts:

• fromBlankCanvas() - New workflow
• fromImportedWorkflow(file) - Pre-built workflow
• fromNewProjectBlankCanvas() - Project-scoped
• withUser(user) - Isolated browser context

Multi-User Tests

const member = await api.publicApi.createUser({ role: 'global:member' });
const memberPage = await n8n.start.withUser(member);
await memberPage.navigate.toWorkflows();

Development Process

1. Validate spec - Has file, behavior, pattern reference?
2. Read existing code - Understand current patterns in the file
3. Identify helpers needed - Check pages/, services/, composables/
4. Add helpers first if missing
5. Write test following 4-layer architecture
6. Verify iteratively - Small changes, test frequently

Mandatory Verification

Always run before marking complete:

# 1. Tests pass (check output for failures - piping loses exit code)
pnpm --filter=n8n-playwright test:local <your-test> --reporter=list 2>&1 | tail -50

# 2. Not flaky (required)
pnpm --filter=n8n-playwright test:local <your-test> --repeat-each 3 --reporter=list 2>&1 | tail -50

# 3. Lint passes
pnpm --filter=n8n-playwright lint 2>&1 | tail -30

# 4. Typecheck passes
pnpm --filter=n8n-playwright typecheck 2>&1 | tail -30

Important: Piping through tail loses the exit code. Always check the output for "failed" or error messages rather than relying on exit codes.

If any fail, fix before completing.

Refactoring Existing Tests

Always verify tests pass BEFORE making changes:

pnpm --filter=n8n-playwright test:local tests/e2e/target-file.spec.ts --reporter=list 2>&1 | tail -50

Then make small incremental changes, re-running after each.

Done Checklist

• Spec had clear file, behavior, and pattern reference
• Read AGENTS.md and relevant existing code
• Used n8n.start.* entry points
• Used nanoid() for unique IDs (not Date.now())
• No serial mode, @db:reset, or n8n.api.signin()
• Multi-user tests use n8n.start.withUser()
• Tests pass with --repeat-each 3
• Lint and typecheck pass