To run Cypress tests in CI, install Cypress with your project’s package manager, start the application, wait until it is reachable, then run npx cypress run. For GitHub Actions, Cypress’s maintained action can handle dependency installation, a configured build and server start, and test execution. Cypress Cloud recording is optional for a normal single-machine run, but required for Cypress’s documented parallelization across CI machines.
Set up the basic CI run
Install Cypress as a development dependency and run its CLI in the CI job. Use the command for the package manager already used by the project:
As an Amazon Associate I earn from qualifying purchases.
npm install cypress --save-devyarn add cypress --devpnpm add --save-dev cypressbun add --dev cypress
Then run npx cypress run (or the equivalent script/package-manager command) in the job. This runs Cypress in headless mode by default. Cypress documents provider-neutral setup and these installation commands in its CI overview.
Start the app and wait until it is ready
Tests that visit a locally served application need the server running during the test run. Starting it in the background and immediately invoking Cypress can create a race: the test process may begin before the app is listening. Prefer a readiness check to an arbitrary sleep.
For a custom workflow, Cypress documents using concurrently with wait-on to launch the app and wait for its URL. In the maintained GitHub Action, configure the start and wait-on inputs. Set the URL to the actual address and port used by your app, and ensure the server process remains alive while tests run. See the Cypress CI overview and GitHub Actions guide.
Run Cypress tests in GitHub Actions
The following workflow uses Cypress’s documented maintained action, checks out the repository, and supplies build and server-start commands. Replace the example commands with the scripts in your project and use the URL your server actually serves.
name: Cypress tests
on: [push, pull_request]
jobs:
cypress:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Cypress run
uses: cypress-io/github-action@v7
with:
build: npm run build
start: npm start
wait-on: 'http://localhost:3000'The action installs project dependencies, can run the configured build, starts the server, waits for the configured URL, and runs Cypress. The guide uses cypress-io/github-action@v7 as its current example and recommends the latest major version or a specific release tag for tighter pinning. Action and runner versions are volatile; verify current tags and GitHub runner images when implementing.
Choose a browser
Set the action’s browser input to the browser your project needs. Cypress says GitHub-hosted Ubuntu and Windows runners have Chrome, Firefox, and Edge, while macOS runners also include Safari. Availability and versions can change with runner images; check the current Cypress GitHub Actions guidance before relying on a particular browser.
Use direct CLI steps when you need more control
You can instead add explicit install, build, server-start/readiness, and npx cypress run steps. This leaves more orchestration in your workflow to maintain, while the maintained action packages common Cypress setup into action inputs. The right choice depends on whether convenience or direct control matters more to your project.
Run Cypress in other CI providers
The core approach is the same across providers: install dependencies, make the application available, wait for readiness, and invoke Cypress. The provider’s YAML or job syntax changes, not the need for those stages. Cypress documents integrations for GitHub Actions, CircleCI, GitLab CI, Jenkins, and AWS CodeBuild in its provider overview. Its GitLab CI guide gives provider-specific setup.
Configure Cypress Cloud recording and protect the key
A basic single-machine cypress run does not require recording. If you want Cypress Cloud run reporting and its associated run information, configure the project for Cloud and pass --record with a record key, or use the corresponding action settings.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallCrashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteProvide the key as the CYPRESS_RECORD_KEY operating-system environment variable through your CI secret store or masked variable. Cypress says the key is not read from cypress.env.json or the Cypress configuration env block. Do not commit it in workflow files or expose it in logs. See the CLI reference and CI overview.
Parallelize tests across CI machines
Cypress’s documented multi-machine parallelization requires recorded runs in Cypress Cloud. Configure multiple workers to join the same recorded run with parallelization enabled; Cloud distributes spec files among the available machines. The parallelization guide explains orchestration, and Cypress’s GitHub Actions guide shows a pattern that separates install/build work from matrix workers and transfers the build artifact.
Before scaling out, account for both elapsed time and the CI capacity used by extra workers. Keep workers on the same build artifact and compatible run configuration. If browser or runner updates could make workers differ, use a consistent container image and browser version.
Choose between a hosted runner and Docker
Use the provider’s native runner when its available Node.js and browser versions meet your needs and minimizing environment setup is the priority. Use a Cypress Docker image when a controlled Linux environment with Cypress dependencies and browsers is more valuable; image tags and included versions still need to be selected and maintained. Cypress publishes Linux images for CI and local use.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
On GitHub Actions, a job using a container image must use a Linux runner. Cypress also notes a non-root user setting for Firefox in its container example. Select an image compatible with the project’s Node.js and browser requirements, and verify its tag and browser versions at implementation time. Details are in the CI overview and GitHub Actions guide.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Set CI-specific Cypress configuration
Cypress configuration values can generally be overridden with CYPRESS_-prefixed environment variables. Examples in the overview include CYPRESS_BASE_URL, CYPRESS_REPORTER, and timeout and viewport settings. Put machine- or CI-specific values in the job environment rather than hard-coding assumptions that do not apply to local development. Consult the overview and CLI reference for supported options.
Troubleshoot common CI failures
- Cypress starts before the app: the server process was launched, but the app was not ready. Add a URL readiness check with the action’s
wait-oninput or await-on-based custom setup instead of relying on a fixed sleep. - The server exits during tests: ensure the start command launches a process that stays alive for the test run; avoid a workflow step that starts the app and then terminates it before Cypress runs.
- The workflow cannot find the app: check the readiness URL, port, and server binding against the environment in the job. The configured URL must be reachable from the Cypress process.
- Cloud recording or parallelization fails: verify the project is configured for Cypress Cloud, the record key is available to the job as
CYPRESS_RECORD_KEY, and workers join the same recorded run. Keep the key in CI secrets, not source control. - Parallel workers behave differently: check that each uses the same build artifact and compatible browser/runtime environment. Pin or standardize image and browser versions when runner updates can change them.
- A container job is rejected or behaves unexpectedly: on GitHub Actions, use a Linux runner for a job container; for Firefox, check the non-root user configuration in Cypress’s example.
Or skip the browser setup
If you need website screenshots alongside CI tests, ScreenshotNeo is a screenshot API and MCP server for developers. A single GET request can return an image or PDF. For example, here is the cURL request; replace the target URL with the page you want to capture:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo API documentation for options and response details. It accepts cookie/consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each cleanup step can be disabled. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, with response headers indicating the page verdict and billing status. Its MCP server provides screenshot and PDF tools for AI agents. The Free plan includes 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots. Sign up for ScreenshotNeo’s free plan.
Quick wins for a faster PC:
Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Frequently Asked Questions
Does a basic Cypress CI run need Cypress Cloud?
No. A normal single-machine cypress run can run without Cloud recording; Cypress requires recorded runs for its documented parallelization across machines.
Can Cypress run in CI providers other than GitHub Actions?
Yes. Cypress documents provider integrations including CircleCI, GitLab CI, Jenkins, and AWS CodeBuild; provider configuration syntax varies.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
