E2E Runner Plugin
Relevant source files
The following files were used as context for generating this wiki page:
The E2E Runner Plugin is an Nx extension that coordinates end-to-end testing by automating service startup. It starts backend APIs or frontend applications and ensures they are healthy before executing test suites using frameworks like Cypress or Playwright.
The plugin provides a unified executor that manages the lifecycle of multiple dependencies. It eliminates the need for manual service management during development and CI/CD pipelines by handling parallel startup, health monitoring, and automatic teardown upon test completion.
Sources: packages/e2e-runner/README.md:1-14, README.md:82-85
Core Features
The plugin offers several key capabilities to streamline testing workflows:
- Multi-Target Orchestration: Starts multiple Nx targets simultaneously before running tests.
- Health Monitoring: Uses specific URLs to verify that services are ready to receive requests.
- Runner Flexibility: Supports Cypress, Playwright,
@nx/playwright, and custom command runners. - Lifecycle Management: Automatically terminates all started services after the test process exits.
- Logging Control: Forwards logs from background targets to the main console, optionally triggered by verbose flags.
Sources: packages/e2e-runner/README.md:9-15, packages/e2e-runner/CHANGELOG.md:167-171
Execution Workflow
The E2E runner follows a strict sequence to ensure test stability. It prioritizes service availability over immediate execution.
The diagram shows how the executor manages background services. If a target fails to start or pass health checks, the system triggers a teardown to prevent orphaned processes.
Sources: packages/e2e-runner/README.md:86-91, packages/e2e-runner/CHANGELOG.md:200-205
Configuration
The plugin uses a targets array within the executor options. Each entry defines a specific service dependency.
Target Options
| Option | Type | Description |
|---|---|---|
target | string | The Nx target to execute (e.g., app:serve). |
checkUrl | string | URL to probe for a 200-range status code. |
checkMaxTries | number | Maximum attempts to check the URL before failing (2s delay). |
env | object | Key-value pairs of environment variables for the target. |
reuseExistingServer | boolean | Allows the runner to skip starting a target if it is already running. |
rejectUnauthorized | boolean | Set to false to permit self-signed SSL certificates. |
logging | boolean | Enables or disables log forwarding for the specific target. |
| Sources: packages/e2e-runner/README.md:33-43, packages/e2e-runner/CHANGELOG.md:144-148, packages/e2e-runner/CHANGELOG.md:152-156 |
Configuration Example
{
"e2e": {
"executor": "@nx-extend/e2e-runner:run",
"options": {
"runner": "playwright",
"targets": [
{
"target": "api:serve",
"checkUrl": "http://localhost:9000/health",
"checkMaxTries": 50,
"logging": false
}
]
}
}
}
Sources: packages/e2e-runner/README.md:47-68
Supported Runners
The E2E runner delegates the actual test execution to specialized underlying runners. It passes all additional options directly to these executors.
- @nx/playwright: The current recommended runner for Playwright tests.
- @nrwl/cypress:cypress: Used for Cypress-based test suites.
- run-commands: Executes arbitrary shell commands for custom testing logic.
- playwright: Supported via the legacy
@nx-extend/playwright:testexecutor.
Sources: packages/e2e-runner/README.md:23-30, packages/e2e-runner/CHANGELOG.md:126-130
Integration with Other Plugins
The E2E runner is often used in conjunction with other nx-extend generators to test cloud-native components. For example, when testing Google Cloud Functions, the plugin coordinates the gcp-functions local runner.
The sequence illustrates the interaction during a typical GCP function test run, where the E2E runner acts as the parent process.
Sources: e2e/gcp-functions-e2e/tests/gcp-functions.spec.ts:1-49, packages/gcp-functions/README.md:71-91
Summary
The E2E Runner Plugin provides essential orchestration for complex Nx workspaces requiring multiple live services during testing. By managing checkUrl health probes and parallel target execution, it ensures that tests only run when the environment is ready and cleans up resources automatically.
Sources: packages/e2e-runner/README.md:1-15, packages/e2e-runner/project.json:1-100