Testing Strategies & E2E Testing
Relevant source files
The following files were used as context for generating this wiki page:
Testing within the nx-extend ecosystem ensures the reliability of production-ready Nx plugins. The project employs a multi-layered testing approach, primarily focusing on end-to-end (E2E) verification of plugin generators and executors. This strategy validates that plugins correctly modify workspace configurations, generate the expected file structures, and execute build or deployment commands successfully.
The core of this capability is the @nx-extend/e2e-runner package, which manages the lifecycle of services required during E2E test execution. It handles automatic service startup, URL health checks, and environment synchronization across different testing frameworks like Playwright and Cypress.
E2E Runner Architecture
The e2e-runner package provides an executor that coordinates the execution of testing tools by ensuring all dependent services are live before tests begin.
The diagram shows the lifecycle of an E2E test run where the runner manages target dependencies and environment readiness.
Sources: packages/e2e-runner/CHANGELOG.md, packages/e2e-runner/project.json
Key Runner Features
The runner automates several critical tasks for reliable E2E testing:
- Target Management: Starts multiple Nx targets (like API servers or frontend dev servers) before running tests.
- Health Checking: Utilizes the
is-api-liveutility with configurable timeouts to verify service availability. - Environment Injection: Supports injecting environment variables into health check URLs.
- Lifecycle Hooks: Automatically tears down all started services if a target fails to start or after tests complete.
Sources: packages/e2e-runner/CHANGELOG.md:120-135, packages/e2e-runner/CHANGELOG.md:215-220
Plugin Verification Strategies
Individual plugins are tested by simulating real-world usage within a temporary Nx workspace. These tests verify the three main phases of a plugin's lifecycle: Initialization, Generation, and Execution.
Verification Flow
The sequence diagram illustrates how E2E tests isolate the plugin, initialize a project, and verify the resulting file system state.
Sources: e2e/gcp-functions-e2e/tests/gcp-functions.spec.ts:6-25, e2e/shadcn-ui-e2e/tests/shadcn-ui.spec.ts:8-20
Common Test Targets
| Target Category | Verified Behavior | Example Plugins |
|---|---|---|
| Generators | Validates project.json updates, tsconfig path aliases, and boilerplate file creation. | shadcn-ui, translations, strapi |
| Executors | Validates dist folder contents, production optimizations, and lock file generation. | gcp-functions, docusaurus, react-email |
| Integrations | Validates external tool interaction, such as npm publish or Tailwind config merging. | core, github-pages |
Sources: e2e/shadcn-ui-e2e/tests/shadcn-ui.spec.ts, e2e/translations-e2e/tests/translations.spec.ts, e2e/gcp-functions-e2e/tests/gcp-functions.spec.ts
Configuration and Utilities
Testing relies on shared utilities and specific project configurations to maintain consistency across the repository.
E2E Utilities
The workspace provides helper functions to interact with the Nx CLI asynchronously and verify the state of the virtual filesystem:
ensureNxProject: Sets up the testing environment with the compiled versions of local plugins.runNxCommandAsync: Executes Nx commands and allows environment overrides (e.g., settingNX_EXTEND_COMMAND_USE_NPX).checkFilesExist: Asserts that specific files or directories were created by the plugin.
Sources: e2e/gcp-functions-e2e/tests/gcp-functions.spec.ts:1-15, e2e/translations-e2e/tests/translations.spec.ts:70-75
Workspace Tags and Metadata
Projects are categorized and isolated using Nx tags and project types to ensure that E2E tests only run on relevant changes.
| Property | Value | Description |
|---|---|---|
projectType | library | Most e2e-runner and project core components are defined as libraries. |
tags | [] | Used for task planning and affected command analysis in CI. |
sourceRoot | packages/{name}/src | Defines where test coverage is tracked. |
Sources: packages/e2e-runner/project.json:4-7, packages/github-pages/project.json:4-7
Summary of Testing Operations
E2E testing in nx-extend is an automated process that spans from workspace initialization to artifact verification. By using the @nx-extend/e2e-runner, the project ensures that complex infrastructure and deployment plugins work correctly across different versions of Nx, maintaining compatibility through major upgrades like Nx 22.
Sources: README.md, packages/core/CHANGELOG.md, packages/e2e-runner/CHANGELOG.md