Cypress CI/CD Overview

Running Cypress in CI/CD is where a test suite proves its real value: catching regressions before they reach production. This lesson covers the core principles before diving into specific CI providers.

Running Cypress Headlessly in CI

CI environments run Cypress via cypress run, the headless mode, since there's no interactive display to open the Test Runner against. The application under test typically needs to be started (or already deployed somewhere reachable) before Cypress runs against it.

# Typical CI pipeline steps
npm ci
npm run build
npm run start &      # start the app in the background
npx wait-on http://localhost:3000
npx cypress run

wait-on (or an equivalent health-check step) ensures Cypress doesn't start running against an application that hasn't finished booting yet.

Key CI Considerations

1. Install dependencies (with caching)
2. Build/start the application under test
3. Wait for the app to be ready
4. Run Cypress (cypress run)
5. Upload artifacts (screenshots/videos) on failure

Cache node_modules and the Cypress binary cache to avoid slow, repeated downloads.
Always wait for a health check before running tests, rather than a fixed sleep.
Configure baseUrl to match the CI-started application's actual address and port.
Upload failure artifacts so a failing CI run is debuggable without local reproduction.

CI/CD Checklist Cheat Sheet

A checklist for setting up any new CI pipeline running Cypress.

Step	Why It Matters
Cache `node_modules` + Cypress binary	Avoids slow reinstalls on every run
Use a real health check before testing	Avoids flaky "app not ready" failures
Run headlessly with `cypress run`	No display server available in CI
Set `baseUrl` to match the CI environment	Avoids hardcoded, environment-specific URLs
Upload screenshots/videos on failure	Enables debugging without local reproduction
Fail the build on test failure	Ensures broken code doesn't merge/deploy silently

Deciding Where Tests Run in the Pipeline

E2E tests can run against a locally built application inside the CI job itself, or against a deployed preview/staging environment. Running locally in-job is typically faster and more isolated; running against a deployed preview more closely validates the actual deployed artifact, including infrastructure-level concerns.

In-job local run: fast, isolated, but doesn't validate real deployment infrastructure.
Against a deployed preview: slower, but closer to true production-like validation.
Many teams use both: fast in-job runs on every PR, deployed-preview runs before production release.

Failing Fast vs. Full Test Visibility

Some CI configurations stop the entire suite at the first failure; others let all tests run and report every failure together. For most teams, letting the full suite run and reporting all failures gives more complete information per pipeline run, at the cost of slightly longer feedback for the very first failure.

Common Mistakes

Using a fixed sleep instead of a real health check to wait for the application to be ready.
Not caching the Cypress binary, causing slow, repeated downloads on every single CI run.
Hardcoding a baseUrl that only works in one specific environment, breaking other pipeline stages.
Never configuring artifact upload, leaving CI failures without any debugging evidence.

Key Takeaways

CI runs Cypress headlessly via cypress run, after the application under test is ready.
Caching dependencies and the Cypress binary meaningfully speeds up pipeline runs.
Choosing where tests run (local in-job vs. deployed preview) is a deliberate trade-off.
Uploading screenshots and videos as artifacts is essential for debugging CI-only failures.

Pro Tip

Treat your CI Cypress configuration with the same care as production code, review changes to it, and periodically audit caching and artifact upload settings, a slow or under-configured CI pipeline quietly costs a team far more cumulative time than most people realize.