Unit and Integration Testing

Relevant source files

• .github/docker-compose.yml
• .github/scripts/bump-versions.mjs
• .github/scripts/package.json
• .github/scripts/update-changelog.mjs
• .github/workflows/ci-master.yml
• .github/workflows/ci-pull-requests.yml
• .github/workflows/release-create-pr.yml
• .github/workflows/release-publish.yml
• .github/workflows/release-push-to-channel.yml
• CONTRIBUTING.md
• packages/@n8n/api-types/src/dto/executions/execution-redaction-query.dto.ts
• packages/@n8n/backend-common/src/modules/__tests__/module-registry.test.ts
• packages/@n8n/backend-common/src/modules/module-registry.ts
• packages/@n8n/backend-common/src/modules/modules.config.ts
• packages/@n8n/db/src/repositories/__tests__/execution.repository.test.ts
• packages/@n8n/db/src/repositories/__tests__/workflow.repository.test.ts
• packages/@n8n/db/src/repositories/execution.repository.ts
• packages/@n8n/db/src/repositories/workflow.repository.ts
• packages/@n8n/decorators/src/__tests__/redactable.test.ts
• packages/@n8n/decorators/src/controller/__tests__/args.test.ts
• packages/@n8n/decorators/src/controller/__tests__/license.test.ts
• packages/@n8n/decorators/src/controller/__tests__/scoped.test.ts
• packages/@n8n/decorators/src/module/__tests__/module.test.ts
• packages/@n8n/decorators/src/module/index.ts
• packages/@n8n/decorators/src/module/module-metadata.ts
• packages/@n8n/decorators/src/module/module.ts
• packages/cli/src/controllers/third-party-licenses.controller.ts
• packages/cli/src/errors/aborted-execution-retry.error.ts
• packages/cli/src/errors/missing-execution-stop.error.ts
• packages/cli/src/executions/__tests__/execution-redaction-proxy.service.test.ts
• packages/cli/src/executions/__tests__/execution.service.test.ts
• packages/cli/src/executions/execution-redaction-proxy.service.ts
• packages/cli/src/executions/execution-redaction.ts
• packages/cli/src/executions/execution.service.ee.ts
• packages/cli/src/executions/execution.service.ts
• packages/cli/src/executions/execution.types.ts
• packages/cli/src/middlewares/list-query/dtos/workflow.filter.dto.ts
• packages/cli/src/middlewares/list-query/dtos/workflow.select.dto.ts
• packages/cli/src/modules/community-packages/community-packages.module.ts
• packages/cli/src/public-api/v1/handlers/workflows/workflows.handler.ts
• packages/cli/src/public-api/v1/handlers/workflows/workflows.service.ts
• packages/cli/src/workflows/__tests__/workflow-execution.service.test.ts
• packages/cli/src/workflows/__tests__/workflow.service.test.ts
• packages/cli/src/workflows/__tests__/workflows.controller.test.ts
• packages/cli/src/workflows/workflow-execution.service.ts
• packages/cli/src/workflows/workflow.request.ts
• packages/cli/src/workflows/workflow.service.ee.ts
• packages/cli/src/workflows/workflow.service.ts
• packages/cli/src/workflows/workflows.controller.ts
• packages/cli/test/integration/controllers/third-party-licenses.controller.test.ts
• packages/cli/test/integration/database/repositories/execution.repository.test.ts
• packages/cli/test/integration/database/repositories/workflow.repository.test.ts
• packages/cli/test/integration/execution-context-propagation.test.ts
• packages/cli/test/integration/execution.repository.test.ts
• packages/cli/test/integration/execution.service.integration.test.ts
• packages/cli/test/integration/public-api/workflows.test.ts
• packages/cli/test/integration/shared/db/executions.ts
• packages/cli/test/integration/workflows/workflow.service.test.ts
• packages/cli/test/integration/workflows/workflows.controller.ee.test.ts
• packages/cli/test/integration/workflows/workflows.controller.test.ts
• packages/frontend/@n8n/rest-api-client/src/api/third-party-licenses.ts
• packages/frontend/editor-ui/src/app/composables/useRunWorkflow.test.ts
• packages/frontend/editor-ui/src/app/composables/useRunWorkflow.ts
• packages/node-dev/commands/new.ts
• packages/node-dev/src/Create.ts
• packages/nodes-base/nodes/EditImage/EditImage.node.ts
• packages/testing/playwright/currents.config.ts
• packages/testing/playwright/pages/ExecutionsPage.ts
• packages/testing/playwright/scripts/coverage-workflow.md
• packages/testing/playwright/scripts/generate-coverage-report.js
• packages/testing/playwright/tests/e2e/settings/users/users.spec.ts
• packages/testing/playwright/tests/e2e/workflows/executions/list.spec.ts

This page documents the unit and integration testing infrastructure in n8n, covering test frameworks, organization patterns, execution strategies, and coverage reporting. For end-to-end testing with Playwright, see E2E Testing. For information about the overall testing strategy and test suite organization, see Testing Strategy and Tools.

Purpose and Scope

This document covers:

• Unit testing with Jest (backend) and Vitest (frontend)
• Integration testing with Testcontainers for database and service integration
• Test organization and file structure patterns
• Code coverage collection, reporting, and CI/CD integration
• Mocking strategies for isolating units of code
• Test execution locally and in CI environments

Testing Architecture Overview

Diagram: Testing Architecture Components

Sources: .github/workflows/ci-pull-requests.yml turbo.json1-50 codecov.yml1-87 CONTRIBUTING.md451-482

Unit Testing Framework

Backend Unit Tests with Jest

Backend packages use Jest as the primary test framework. Jest is configured at the package level with specific setup for TypeORM, database connections, and mocking.

Diagram: Jest Test Execution Flow

The primary backend test suite is located in packages/cli/test/, with TypeScript path aliases configured for test utilities:

Sources: packages/cli/tsconfig.json1-40 CONTRIBUTING.md453-463

Frontend Unit Tests with Vitest

Frontend packages use Vitest, which provides better integration with Vite's build system and faster execution through ESM support.

Diagram: Vitest Frontend Testing Structure

Sources: CONTRIBUTING.md453-470 turbo.json29-36

Integration Testing with Testcontainers

Integration tests use Testcontainers to spin up real database instances and other services, ensuring tests run against actual dependencies rather than mocks.

Diagram: Testcontainers Integration Test Architecture

The Testcontainers system is documented in detail at packages/testing/containers/README.md and provides stack orchestration commands:

Sources: CONTRIBUTING.md315-377 .github/docker-compose.yml1-13

Test Organization Patterns

Directory Structure

packages/
├── cli/
│   └── test/
│       ├── integration/          # Integration tests
│       │   ├── shared/           # @test-integration/* alias
│       │   └── controllers/      # API endpoint tests
│       ├── unit/                 # Unit tests
│       └── shared/               # @test/* alias
│           ├── db/               # Database test utilities
│           ├── types.ts          # Test type definitions
│           └── utils/            # Test helper functions
├── nodes-base/
│   └── nodes/
│       └── */
│           └── test/             # Node-specific tests
│               └── *.test.ts
├── frontend/
│   └── editor-ui/
│       └── src/
│           └── **/__tests__/     # Co-located tests
└── testing/
    ├── containers/               # Testcontainers utilities
    └── playwright/               # E2E tests (separate)

Sources: packages/cli/tsconfig.json10-14 CONTRIBUTING.md44-62

Test File Naming Conventions

Test files follow consistent naming patterns:

Pattern	Purpose	Example
*.test.ts	Unit tests	workflow.service.test.ts
*.integration.test.ts	Integration tests	workflow.controller.integration.test.ts
*.spec.ts	Component specs	WorkflowCanvas.spec.ts
test/*.ts	Test utilities	test/shared/db/users.ts

Sources: codecov.yml81-86

Running Tests

Command Reference

Diagram: Test Command Execution Flow

From the monorepo root:

Sources: CONTRIBUTING.md453-463 turbo.json25-36

Turborepo Test Configuration

Tests are orchestrated through Turborepo with dependency management:

This configuration ensures:

• Tests run only after successful builds
• Coverage artifacts are cached
• Parallel test execution across packages
• Cache invalidation on source changes

Sources: turbo.json25-36

Code Coverage

Coverage Collection

Diagram: Coverage Collection and Reporting Pipeline

Coverage is enabled through environment variables:

Sources: CONTRIBUTING.md467-470 turbo.json3 packages/testing/playwright/currents.config.ts1-15

Codecov Configuration

Coverage thresholds and component tracking are configured in codecov.yml:

Component-based coverage tracking:

Component	Paths	Threshold
Backend	packages/@n8n/*, packages/workflow, packages/core, packages/cli	Default: 0.5%
Frontend	packages/@n8n/codemirror-lang, packages/frontend	Default: 0.5%
Nodes	packages/nodes-base, packages/@n8n/nodes-langchain	0% (no decrease)

Coverage flags for carryforward:

• backend-unit - Backend unit test coverage
• backend-integration - Backend integration test coverage
• nodes-unit - Node package test coverage
• frontend - Frontend unit test coverage
• frontend-e2e - Frontend E2E test coverage

Sources: codecov.yml1-87

Viewing Coverage Locally

For VSCode integration, use the Coverage Gutters extension to visualize coverage inline.

Sources: CONTRIBUTING.md467-470 packages/testing/playwright/scripts/coverage-workflow.md1-195

CI/CD Integration

Pull Request Testing

Diagram: Pull Request CI Test Pipeline

The CI filter determines which tests to run based on file changes:

Sources: .github/workflows/ci-pull-requests.yml1-133

Master Branch Testing

The master branch runs tests with multiple Node.js versions:

This ensures compatibility across Node.js versions while collecting coverage only once to avoid redundant uploads.

Sources: .github/workflows/ci-master.yml1-61

Test Example: Integration Test Structure

Here's how integration tests are typically structured in the CLI package:

Diagram: Integration Test Structure Pattern

Example from the third-party licenses controller test:

Sources: packages/cli/test/integration/controllers/third-party-licenses.controller.test.ts1-96

Mocking Strategies

Jest Mocking

Common mocking patterns in backend tests:

Mock Type	Implementation	Use Case
Module Mock	jest.mock('module')	Replace entire module
Partial Mock	jest.mock('module', () => ({ ...actual, fn: jest.fn() }))	Mock specific exports
Function Mock	jest.fn()	Track calls and control return values
Spy	jest.spyOn(object, 'method')	Monitor real implementations
Timer Mock	jest.useFakeTimers()	Control time-based logic

Example from third-party licenses test:

Sources: packages/cli/test/integration/controllers/third-party-licenses.controller.test.ts5-10

Test Utilities and Factories

The CLI package provides shared test utilities:

packages/cli/test/shared/
├── db/
│   ├── users.ts              # createOwner(), createMember(), etc.
│   ├── workflows.ts          # workflow test fixtures
│   └── credentials.ts        # credential test fixtures
├── types.ts                  # SuperAgentTest, test interfaces
└── utils/
    ├── testDb.ts             # database test utilities
    └── testServer.ts         # setupTestServer()

These utilities are imported via TypeScript path aliases:

Sources: packages/cli/tsconfig.json10-14 packages/cli/test/integration/controllers/third-party-licenses.controller.test.ts1-96

Best Practices

Test Independence

Each test should be independent and able to run in isolation:

Descriptive Test Names

Follow the pattern: "should [expected behavior] when [condition]"

Coverage Guidelines

From the contributing guide and codecov configuration:

• Backend packages: Maintain or improve coverage
• Nodes packages: Enforce no coverage decrease (threshold: 0%)
• Frontend packages: Track coverage trends
• Critical paths: Aim for high coverage on user-facing features
• Overall threshold: 0.5% minimum to prevent significant drops

Tests must be included in PRs per community guidelines:

PRs must include tests:

• Unit tests
• Workflow tests for nodes
• UI tests (if applicable)

Sources: CONTRIBUTING.md424-428 codecov.yml13-80

Test Performance

For faster test execution:

1. Use in-memory SQLite for unit tests instead of containers
2. Mock external services rather than making real HTTP calls
3. Run tests in parallel with Turbo's parallelization
4. Use test filtering to run only affected tests during development
5. Leverage Turbo cache to skip unchanged packages

Sources: CONTRIBUTING.md383-405 turbo.json25-36

Summary

The n8n testing infrastructure provides comprehensive coverage through:

• Jest for backend unit and integration tests
• Vitest for frontend unit tests
• Testcontainers for integration testing with real services
• Turborepo for parallel test execution and caching
• Codecov for coverage tracking and enforcement
• GitHub Actions for automated CI/CD testing

Tests are organized with clear separation between unit and integration tests, use TypeScript path aliases for test utilities, and follow consistent patterns for setup, execution, and teardown. The CI pipeline conditionally runs tests based on file changes to optimize build times while maintaining quality standards.

Sources: .github/workflows/ci-pull-requests.yml1-133 .github/workflows/ci-master.yml1-61 CONTRIBUTING.md451-482 turbo.json1-50 codecov.yml1-87