Testing Infrastructure
Relevant source files
The following files were used as context for generating this wiki page:
- packages/testing/README.md
- packages/testing/playwright/README.md
- packages/testing/playwright/AGENTS.md
- packages/testing/playwright/CONTRIBUTING.md
- packages/testing/janitor/README.md
- packages/nodes-base/TESTING_PROMPT.md
- packages/nodes-base/TESTING_PROMPT_WORKFLOW.md
- packages/testing/playwright/tests/cli-workflows/README.md
- CONTRIBUTING.md
The testing infrastructure in n8n is a multi-layered platform designed to ensure code quality, architectural integrity, and functional correctness across the monorepo. It encompasses unit testing for nodes, end-to-end (E2E) UI testing, workflow schema validation, and specialized static analysis tools to maintain test suite health.
The ecosystem is divided into several specialized packages that handle different concerns, ranging from composable Docker stacks for infrastructure simulation to micro-benchmarking for performance monitoring. This modular approach allows the system to decide what to test, run the appropriate suites, and measure results efficiently.
Sources: packages/testing/README.md:3-5, packages/testing/playwright/CONTRIBUTING.md:21-25
High-Level Architecture
The infrastructure is organized into four main lanes: Static Analysis, Selection, Execution, and Performance. These lanes utilize shared substrates like the rules-engine and test-impact to drive CI and local development workflows.
Component Relationship
This diagram represents how substrates like test-impact feed selection data into execution engines like playwright and analysis tools like janitor.
Sources: packages/testing/README.md:24-34
Core Testing Packages
| Package | Purpose | Primary Tool/Engine |
|---|---|---|
nodes-base/test | Unit testing for integration nodes | Vitest / Jest |
playwright | E2E UI and API-driven testing | Playwright |
janitor | Architecture enforcement & static analysis | ts-morph / rules-engine |
containers | Composable Docker stacks (Postgres, Redis, etc.) | Docker / Testcontainers |
performance | Microbenchmarks for critical code paths | Custom benchmarking |
test-workflows | Workflow execution and schema validation | Playwright |
Sources: packages/testing/README.md:7-22, packages/testing/playwright/tests/cli-workflows/README.md:5-9
E2E Testing Strategy (Playwright)
The E2E testing framework utilizes Playwright to simulate user behavior and verify API responses. It follows a strictly layered approach for UI testing and a streamlined approach for API testing to maximize maintainability.
UI Testing Four-Layer Approach
This diagram illustrates the separation of concerns: tests focus on scenarios, composables on business workflows, and page objects on UI interaction logic.
Sources: packages/testing/playwright/CONTRIBUTING.md:28-40, packages/testing/janitor/README.md:12-25
Test Isolation and Environments
To prevent flaky tests and session bleeding, the infrastructure provides several isolation mechanisms:
- Isolated Browser Contexts: Tests can create distinct user sessions via
n8n.start.withUser(user)to avoid shared state. - Worker Isolation: Using
test.use({ capability: { env: { TEST_ISOLATION: 'name' } } })forces Playwright to create a fresh container with a clean database for a specific worker. - Unique Identifiers: The use of
nanoid()is mandated for credentials and workflows created during tests to ensure parallel safety.
Sources: packages/testing/playwright/AGENTS.md:125-155, packages/testing/playwright/README.md:144-165
Node Unit Testing
Unit tests for n8n nodes are primarily located within packages/nodes-base and utilize vitest-mock-extended for deep mocking of core n8n interfaces.
Mocking Infrastructure
Test suites rely on mocking external dependencies and core interfaces to ensure deterministic results.
- IExecuteFunctions: Mocks the primary execution context for nodes.
- IWebhookFunctions: Mocks webhook lifecycle and request/response objects.
- Nock: Used extensively for intercepting and mocking HTTP requests to external APIs.
Sources: packages/nodes-base/TESTING_PROMPT.md:37-55, packages/nodes-base/TESTING_PROMPT_WORKFLOW.md:95-120
Workflow Test Harness
The NodeTestHarness allows developers to test nodes using real .workflow.json files. This validates how nodes interact within a complete graph, including data flow, credentials, and binary data handling.
Sources: packages/nodes-base/TESTING_PROMPT_WORKFLOW.md:13-35
Static Analysis and Architecture (Janitor)
The janitor tool provides static analysis to prevent "architecture drift" in the test suite. It enforces rules via AST analysis (using ts-morph).
Architecture Rules
| Rule Name | Description | Severity |
|---|---|---|
selector-purity | Prevents raw Playwright locators (e.g., page.locator) in tests/flows. Locators must be in Page Objects. | Error |
no-page-in-flow | Prevents flows/composables from accessing the page object directly. | Warning |
boundary-protection | Prevents Page Objects from importing other Page Objects to avoid coupling. | Error |
dead-code | Identifies and can auto-fix unused methods in Page Objects. | Warning |
no-raw-editor-navigation | Blocks raw page.goto() to editor routes; mandates use of entry composers. | Error |
Sources: packages/testing/playwright/AGENTS.md:65-85, packages/testing/janitor/README.md:118-200
Impact Analysis and TCR
Janitor includes a TCR (Test && Commit || Revert) workflow. It analyzes changed files, determines the "impact" (which tests are affected), runs only those tests, and automatically commits if they pass or reverts if they fail.
Sources: packages/testing/janitor/README.md:315-345
Composable Infrastructure (Containers)
The n8n-containers package provides a Docker-based environment for running tests against various infrastructure configurations.
Infrastructure Stacks
Developers can spin up specific "stacks" to match test requirements:
- SQLite: Standard single-instance setup.
- Postgres: Multi-instance setup testing PostgreSQL-specific migrations.
- Queue Mode: Testing distributed execution using Redis and multiple workers.
- Multi-Main: HA (High Availability) setup testing load balancing and shared state.
Sources: packages/testing/playwright/README.md:78-95, CONTRIBUTING.md:275-300
Capability Tags
Tests are tagged to indicate infrastructure requirements. The test runner uses these tags to filter and group tests.
@capability:email: Requires a Mailpit container for SMTP testing.@capability:proxy: Requires a MockServer container for outbound HTTP proxy testing.@licensed: Requires a container started with an enterprise license key.
Sources: packages/testing/playwright/README.md:118-140
Workflow Testing Framework (Schema Validation)
Located in tests/cli-workflows, this framework focuses on the structural integrity of node outputs.
Schema Validation Logic
Unlike traditional value-based snapshots which are brittle to timestamps and IDs, this framework generates a JSON schema from the node output.
- Workflow Execution: The workflow is executed via the CLI.
- Schema Generation: A schema is derived from the resulting JSON.
- Snapshot Comparison: The current schema is compared against a saved
.snapfile. - Failure Detection: If properties are renamed or types change (e.g.,
fullNamevsname), the test fails.
Sources: packages/testing/playwright/tests/cli-workflows/README.md:40-65
Summary
The n8n testing infrastructure is a comprehensive system that balances speed and reliability through modularity. By combining standard unit tests with a strictly layered E2E framework, containerized infrastructure stacks, and schema-based workflow validation, it ensures that changes to the core engine or individual nodes are verified across all supported environments. The inclusion of the Janitor tool further ensures that the testing code itself remains maintainable and follows established architectural patterns.
Sources: packages/testing/README.md:36-42, packages/testing/playwright/AGENTS.md:225-240