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

Validate spec - Has file, behavior, pattern reference?
Read existing code - Understand current patterns in the file
Identify helpers needed - Check pages/, services/, composables/
Add helpers first if missing
Write test following 4-layer architecture
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

3.7 KiB Raw Blame History