Workflow:Cypress io Cypress E2E Test Execution
| Knowledge Sources | |
|---|---|
| Domains | Testing, E2E_Testing, Browser_Automation |
| Last Updated | 2026-02-12 00:00 GMT |
Overview
End-to-end process for writing, configuring, and executing Cypress E2E tests against a web application, from project initialization through headless or interactive test runs with result reporting.
Description
This workflow covers the complete lifecycle of running end-to-end tests with Cypress. It begins with installing the Cypress npm package and verifying the binary, then proceeds through project configuration, test authoring, and test execution. Cypress launches a real browser, navigates to the application under test, executes commands that simulate user interactions, and asserts on DOM state. Results are collected and reported via the built-in reporter UI or output as JUnit/JSON for CI consumption.
Key outputs:
- Test pass/fail results with detailed command logs
- Screenshots on failure and optional video recordings
- Machine-readable JSON or JUnit XML reports
Usage
Execute this workflow when you need to validate that a web application behaves correctly from the user's perspective. This is appropriate when you have a running application (or can start one) and want to simulate real user journeys such as login flows, form submissions, navigation, and API-driven interactions. Use this for regression testing, acceptance testing, or validating new features before deployment.
Execution Steps
Step 1: Install Cypress
Add the Cypress npm package as a development dependency to the project. The installation process downloads the platform-specific Cypress binary and verifies its integrity. The CLI validates the Node.js version against the supported range before proceeding.
Key considerations:
- Cypress supports npm, yarn, and pnpm package managers
- The binary is cached globally per version to avoid redundant downloads
- Environment variables can override the download URL and cache directory
- Run verification after install to confirm the binary is functional
Step 2: Configure the Project
Create or update the Cypress configuration file at the project root. The configuration system resolves settings from the config file, environment variables, CLI flags, and plugin overrides, merging them in a defined precedence order. E2E testing must be explicitly enabled in the configuration.
Key considerations:
- Configuration supports JavaScript, TypeScript, and MJS file formats
- The config file exports a default object wrapped in the defineConfig helper
- E2E-specific settings include specPattern, baseUrl, supportFile, and setupNodeEvents
- The setupNodeEvents callback enables server-side plugins (task commands, preprocessors)
Step 3: Write Test Specifications
Author test files using Cypress commands within the Mocha-based describe/it structure. Tests use the Cypress command chain API to visit URLs, query the DOM, interact with elements, and make assertions. Each spec file represents a logical grouping of related test cases.
Key considerations:
- Spec files follow the naming pattern configured in specPattern (default: cypress/e2e/**/*.cy.{js,ts})
- Commands are enqueued and executed asynchronously in the browser
- Custom commands can be registered in the support file for reuse
- Fixtures provide static test data loaded via cy.fixture()
Step 4: Launch Test Runner
Start Cypress in either interactive mode (cypress open) or headless mode (cypress run). In interactive mode, the Launchpad UI presents project selection and browser choice before opening the test runner. In headless mode, tests execute immediately in the specified browser without a visible UI.
Key considerations:
- Interactive mode uses Electron to render the Launchpad and App UIs
- Headless mode defaults to the Electron browser but supports Chrome, Firefox, and Edge
- The server process initializes the proxy, configures browser launch arguments, and establishes socket communication
- Browser detection scans for installed browsers on the local machine
Step 5: Execute Tests in Browser
The Cypress driver is injected into an iframe alongside the application under test. The driver dequeues and executes each command, interacting with the AUT through DOM manipulation and event simulation. The proxy intercepts all browser traffic to enable cross-origin testing, request stubbing, and response modification.
Key considerations:
- The proxy handles HTTP and HTTPS traffic with dynamic certificate generation
- Cross-origin navigation is supported via the cy.origin() command
- Network requests can be intercepted and stubbed using cy.intercept()
- The driver communicates test progress to the server via WebSocket
Step 6: Collect and Report Results
After all specs complete, Cypress aggregates results including pass/fail counts, execution times, error details, and screenshots. The reporter UI displays real-time command logs during interactive runs. In headless mode, results are written to stdout and optionally to JSON or JUnit XML files.
Key considerations:
- Screenshots are automatically captured on test failure
- Video recording captures the entire test run (configurable)
- Custom reporters can be configured via the reporter and reporterOptions settings
- The process exits with code 0 for all-pass or a non-zero code indicating failures