Workflow:Cypress io Cypress CI Pipeline Integration
| Knowledge Sources | |
|---|---|
| Domains | Testing, CI_CD, Cloud_Integration |
| Last Updated | 2026-02-12 00:00 GMT |
Overview
End-to-end process for integrating Cypress tests into continuous integration pipelines, including headless execution, result recording to Cypress Cloud, parallelized test runs, and automated failure detection.
Description
This workflow covers running Cypress tests as part of a CI/CD pipeline. Tests execute in headless mode via the cypress run command, with optional recording to Cypress Cloud for centralized result tracking, video/screenshot storage, and parallelization across multiple CI machines. The workflow supports all major CI providers (CircleCI, GitHub Actions, Jenkins, GitLab CI) and includes smart test orchestration features like automatic load balancing and failure-based cancellation.
Key outputs:
- CI pass/fail status with non-zero exit code on test failures
- Recorded test results, videos, and screenshots in Cypress Cloud
- Parallelized test execution across multiple CI containers
- JUnit XML or JSON reports for CI dashboard integration
Usage
Execute this workflow when you need to run Cypress tests automatically on every code change in a CI environment. This is appropriate for pull request validation, deployment gates, nightly regression suites, and release qualification. Use this when you want centralized test result tracking, parallelized execution for faster feedback, or automated failure notification.
Execution Steps
Step 1: Install Dependencies in CI
Set up the CI environment with the correct Node.js version and install project dependencies including Cypress. The Cypress binary is either cached from a previous run or downloaded fresh. Environment variables configure the cache directory, download mirror, and verification behavior.
Key considerations:
- Most CI platforms support caching the Cypress binary directory (~/.cache/Cypress)
- The CYPRESS_CACHE_FOLDER environment variable controls the cache location
- Binary verification runs automatically on first use unless CYPRESS_VERIFY_TIMEOUT is set
- Docker images (cypress/browsers, cypress/included) provide pre-installed environments
Step 2: Configure CI Environment
Set environment variables for Cypress Cloud recording, browser selection, and test configuration. The record key authenticates the CI run with Cypress Cloud. Additional flags control parallelization, grouping, tagging, and failure thresholds.
Key considerations:
- CYPRESS_RECORD_KEY authenticates recording to Cypress Cloud (keep secret)
- The --ci-build-id flag links parallel containers to the same logical run
- Group names organize specs within a run (e.g., by browser or testing type)
- Tags enable filtering and categorization in the Cloud dashboard
Step 3: Execute Tests in Headless Mode
Run cypress run to execute tests in headless mode. The CLI spawns the server process, launches the specified browser without a visible window, and executes all matching spec files sequentially or in the order optimized by Cypress Cloud. Test progress is logged to stdout.
Key considerations:
- The default browser in headless mode is Electron (or Chrome via --browser flag)
- The --spec flag filters which spec files to run
- The --config and --env flags override configuration values for the CI context
- The process captures screenshots on failure and optionally records video
Step 4: Record Results to Cypress Cloud
When the --record flag is provided, test results including run metadata, spec results, command logs, screenshots, and videos are uploaded to Cypress Cloud. The Cloud service stores results, generates analytics, and provides a web dashboard for reviewing test runs.
Key considerations:
- Recording requires a valid project ID in the config and a record key
- Upload happens incrementally as each spec completes
- Failed screenshot and video artifacts are uploaded for debugging
- The Cloud API returns the run URL for linking in CI notifications
Step 5: Parallelize Across CI Containers
When the --parallel flag is provided along with --record, Cypress Cloud orchestrates spec distribution across multiple CI containers. Each container requests the next spec to run from the Cloud API, which uses historical run data to balance load and minimize total execution time.
Key considerations:
- All parallel containers must share the same --ci-build-id
- Cypress Cloud uses spec duration history for optimal load balancing
- The --auto-cancel-after-failures flag stops remaining containers on repeated failures
- Parallelization requires the --record flag (Cloud coordinates distribution)
Step 6: Process Results and Exit
After all specs complete, Cypress aggregates results and exits with an appropriate code. Exit code 0 indicates all tests passed; non-zero codes indicate failures, errors, or configuration problems. CI pipelines use the exit code to gate deployments or trigger notifications.
Key considerations:
- Exit code 1 indicates test failures occurred
- Exit codes 2+ indicate errors (missing specs, configuration issues, etc.)
- JUnit XML reporters generate files compatible with CI dashboard test result tabs
- The --reporter flag configures output format (spec, dot, junit, json)