How to Run Cypress Tests in Headless Mode
Run Cypress tests headlessly with the right browser, spec, and CI setup. Learn how to collect artifacts and diagnose headless-only failures.
From your project root, run npx cypress run. Cypress runs the suite to completion and launches browsers headlessly by default, so you do not need a separate headless flag. Choose a browser with --browser, or limit the run to one spec with --spec.
npx cypress run1. Install Cypress and run the suite
If Cypress is not already a development dependency, install it using the package manager used by your project:
npm install cypress --save-dev
# or
yarn add cypress --dev
# or
pnpm add cypress --save-dev
# or
bun add -d cypressThen run the command from the project root, where Cypress can find the project configuration and spec files:
npx cypress runUse the matching package runner if your project does not use npm. For example, use pnpm exec cypress run or yarn cypress run. The run command executes tests and exits when finished. By contrast, npx cypress open launches the interactive runner in a visible browser.
2. Choose a browser or a spec
Cypress detects installed browsers. The selected browser must be available on the machine or provided by the CI image. Browser names and support can vary by Cypress version, so consult the browser reference for the version in your project.
# Run in installed Chrome
npx cypress run --browser chrome
# Run in installed Firefox
npx cypress run --browser firefox
# Run a single spec matching your configured specPattern
npx cypress run --spec "cypress/e2e/my-spec.cy.js"
# Combine browser selection and spec selection
npx cypress run --browser chrome --spec "cypress/e2e/my-spec.cy.js"The spec path must match Cypress’s configured specPattern. If the file is outside that pattern, Cypress will not discover it. See the official Cypress CLI reference for command options and the browser reference for current browser support.
3. Headless and headed execution
cypress run is headless by default. Add --headed when you want to watch the browser while retaining the command-line run-to-completion workflow:
npx cypress run --headed --browser chromecypress open is the interactive workflow for selecting specs and rerunning tests during development. Use headless runs for repeatable automation, such as CI, and headed runs when observing the browser helps diagnose behavior.
4. Configure a CI run
A reliable CI run needs the application server to be available before Cypress starts visiting it. Starting a server and immediately invoking Cypress can race: the test runner may begin before the app is ready. Use your CI platform’s readiness check or Cypress’s official GitHub Action options for starting and waiting on the server.
# Example shell flow; replace the start and readiness commands for your app
npm run start:test &
# Wait until your app's health endpoint responds before continuing.
# Then run the Cypress suite:
npx cypress runThe shell example shows the order of operations; it does not implement a portable readiness check. Configure the wait step for your CI system and application. The Cypress CI guide explains server startup and the official GitHub Action’s start and wait-on options.
Also make sure the chosen browser is installed in the CI environment. A browser available on a developer laptop is not automatically available in a CI container. Check the Cypress version and browser installation in the job image when a browser cannot launch.
5. Capture screenshots and videos
During cypress run, Cypress automatically captures a screenshot when a test fails. By default, failure screenshots go to cypress/screenshots; Cypress clears that folder before a run. You can turn off failure screenshots in configuration:
const { defineConfig } = require('cypress')
module.exports = defineConfig({
screenshotOnRunFailure: false,
})Video recording is disabled by default. Enable it in your Cypress configuration when you need a recording for each spec; the default output folder is cypress/videos, which Cypress clears before a run.
const { defineConfig } = require('cypress')
module.exports = defineConfig({
video: true,
})Keep artifact settings intentional in CI: screenshots and videos can help explain failures, while producing and retaining extra files uses storage and transfer time. See the official screenshots and videos guide for configuration details.
6. Understand headless rendering defaults
Cypress documents a default headless screen size of 1280 × 720 and a device pixel ratio (DPR) of 1. These settings affect screenshot and video dimensions. If your visual checks depend on another viewport or pixel density, configure the run accordingly and compare like with like. Cypress documents browser launch customization through the before:browser:launch event in its browser launch reference.
7. Troubleshoot common problems
| Symptom | Likely cause | What to check or do |
|---|---|---|
| The browser cannot be found or launched | The requested browser is not installed or is not detected in the local or CI environment. | Install or provide the browser in the environment, then verify its availability and use a supported browser name for your Cypress version. |
| No specs are found | The --spec path does not match a file selected by the configured specPattern. |
Check the path, spelling, working directory, and Cypress configuration. Run without --spec to see whether the suite is discovered. |
| Tests fail visiting the app in CI, but pass locally | The server may not be ready when Cypress starts, or the CI environment may differ. | Add a readiness wait before cypress run; inspect the app URL, environment variables, and server logs in the job. |
| A test passes headed but fails headlessly, or the reverse | The two execution modes can expose different behavior; the mismatch alone does not establish its cause. | Reproduce visibly and compare the run with headless screenshots and videos. Cypress documents this debugging workflow. |
| Video files are missing | Video recording is off by default. | Set video: true in Cypress configuration and check the configured output directory. |
| Failure screenshots are missing | Failure screenshots may be disabled, or the test did not fail. | Check screenshotOnRunFailure and the screenshots output directory. |
| Screenshot dimensions differ from expectations | Headless screen size and DPR affect rendered artifact dimensions. | Check the viewport and browser launch configuration; compare runs using the same settings. |
For a headless-only failure, Cypress’s documented reproduction command is:
npx cypress run --headed --no-exit --browser chromeThis keeps the browser visible and Cypress open after the spec so you can inspect behavior, then compare with the headless screenshots and videos. Consult the official artifact guide when the issue involves missing or unexpected output.
8. Performance, reliability, and cost considerations
Headless mode removes the need to display a browser window, which suits automated runs, but it does not eliminate the work of launching a browser and loading the application. Keep CI runs reliable by using a ready check, selecting only the intended specs when narrowing a diagnosis, and ensuring the browser is present in the environment.
Artifact generation is a tradeoff: failure screenshots are enabled by default, while video is opt-in. Enable video when recordings will help investigate failures; account for the resulting files in CI storage and artifact retention. Cypress’s documentation does not establish one universally best browser or artifact policy, so choose based on your test coverage and debugging needs.
Or skip the browser setup
If your task is to capture a page image rather than execute Cypress assertions, ScreenshotNeo is a website screenshot API and MCP server for developers. A single GET request returns a PNG, JPEG, WebP, or PDF. It is not a Cypress test runner.
Use the API with an access key; see the ScreenshotNeo API documentation for request options.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);- Cookie and consent banners are accepted like a visitor; 60+ known consent platforms, newsletter popups, and chat widgets are removed before the shot. Each cleanup step can be turned off.
- Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing; response headers report the page verdict and whether the request was billed.
- An MCP server provides
take_screenshot,get_page_info, andcapture_pdftools for Claude, Cursor, and other MCP clients. - The free plan includes 1,000 shots per month with no card. Paid plans start at $5 for 3,000 shots. All features are available on every plan.
Create a free ScreenshotNeo account and get 1,000 screenshots a month with no card.
Frequently asked questions
Does cypress run need a headless flag?
No. Headless is the default for browsers launched by the CLI run command.
Can I run one test file?
Yes. Pass its path with --spec, provided it matches the configured spec pattern.
Does Cypress record a video by default?
No. Video recording is disabled by default; enable it with video: true when needed.
Can ScreenshotNeo run my Cypress tests?
No. ScreenshotNeo captures web pages as images or PDFs; Cypress runs browser tests and assertions.
