Principle:Cypress io Cypress Headless Test Execution
| Knowledge Sources | |
|---|---|
| Domains | CI_CD, Testing |
| Last Updated | 2026-02-12 00:00 GMT |
Overview
A non-interactive test execution mode that runs all specs in a headless browser, collects results, and exits with an appropriate status code for CI integration.
Description
Headless test execution is the primary mode for CI pipelines. It runs cypress run which processes CLI arguments, spawns the Cypress server, iterates through spec files, executes each in a headless browser (Electron by default), aggregates results, and exits with a status code indicating the number of failures (0 for all-pass, N for N failures).
The execution pipeline includes optional features: recording to Cypress Cloud, parallel spec distribution across machines, video recording, and screenshot capture on failure.
Usage
Use this principle for all CI/CD pipeline Cypress execution. It applies to cypress run invocations in automated environments.
Theoretical Basis
Headless Execution Pipeline:
cypress run [options]
→ processRunOptions() → server argument array
→ spawn.start(args) → child process
→ Server: ready() function
→ Discover spec files
→ For each spec:
1. Launch headless browser
2. Inject driver
3. Execute tests
4. Collect results
5. Record video (if enabled)
→ Aggregate all spec results
→ Exit with failure count as exit code
Exit Codes:
0 = All tests passed
N = N test failures
112 = Network error during parallel recording