Run cypress run in your CI job after installing Cypress and the browser you want to test, starting your website, and waiting for a real readiness check. Cypress launches browsers headlessly by default when you use the CLI command. Keep a headed command available for diagnosis, because browser versions, timing, rendering, and container settings can make a test behave differently with or without a visible window.
How do I run Cypress headlessly in CI?
The shortest dependable sequence is:
- Install project dependencies, including Cypress.
- Install or select a supported browser on the runner.
- Start the application under test, or point Cypress at a deployed preview.
- Wait until the application answers on its URL.
- Run
npx cypress run(or your package manager’s equivalent).
cypress run is headless by default; cypress open is the interactive, headed application. To display a browser during a CLI run, add --headed. Cypress documents this behavior in Launching browsers in Cypress.
Prerequisites for a repeatable run
A project-local Cypress installation
Install Cypress as a development dependency with the package manager already used by the project. A normal CI install then downloads the version recorded in the lockfile instead of silently choosing a different release. Run the package manager’s Cypress binary through npx cypress, npm exec cypress, or the equivalent command for your package manager.
An available browser
Cypress supports Chrome-family browsers and Firefox; WebKit support is experimental. The selected browser must exist on the runner. A container image that includes the browser and Linux prerequisites is often simpler than installing graphical dependencies one by one. Interactive cypress open needs a display in a container, while headless execution can work without an extra display configuration when the required Linux packages are present.
Free tools Windows power users keep installed
One-click scans. No signup required.
A ready application
The web server must be accepting requests before Cypress starts. This is a race:
npm start & npx cypress runThe command can launch Cypress while the server is still compiling or binding its port. Use a readiness-checking utility or your CI provider’s equivalent instead of an arbitrary fixed sleep. If the job tests a preview or staging deployment, set CYPRESS_BASE_URL to that address and do not start a local server unnecessarily.
A minimal local headless run
From the project directory, run:
npx cypress runTo select an installed browser explicitly:
npx cypress run --browser chrome
npx cypress run --browser firefoxTo run one spec while watching the browser for diagnosis:
npx cypress run --spec cypress/e2e/login.cy.js --browser chrome --headed --no-exit--no-exit leaves the headed browser open after the run, which is useful when you need to inspect the final page. Remove --headed for the normal CI path.
Build a CI job without a startup race
1. Install deterministically
Use the lockfile-aware install command for your package manager. Cache dependencies only when the cache key includes the lockfile and relevant operating-system or browser changes. A stale Cypress binary or browser can create failures that do not reproduce locally.
2. Start and probe the server
Start the application in the background, then poll its real URL until it returns the expected response. A readiness probe should fail after a bounded timeout and print the server’s logs. Cypress’s CI guidance describes a start and wait-on pattern in its official GitHub Action; use the same principle with another CI system.
# Illustrative shell sequence; replace commands with your project's scripts
npm run build
npm run start > server.log 2>&1 &
# Run a readiness tool here, waiting for http://127.0.0.1:3000
npx cypress runDo not treat the comment as a readiness implementation. Configure your CI’s wait utility to check the exact host and port your application binds to, and upload server.log when the job fails.
3. Set the base URL
Keep the base URL in Cypress configuration for local development, or override it for a job:
CYPRESS_BASE_URL=https://preview.example.test npx cypress run --browser chromeUse a preview URL that is reachable from the runner. Private deployments may also require custom headers, cookies, VPN access, or an allowlist entry.
4. Preserve diagnostics
On failure, collect Cypress’s screenshot and video directories together with browser and server logs. Cypress captures failure screenshots automatically during cypress run unless screenshots are disabled. Video recording is opt-in; set video: true when the additional storage and encoding time are worthwhile. Cypress clears configured artifact folders before a run by default, so copy artifacts out before the job workspace is discarded.
Choose a browser deliberately
| Choice | When it fits | Trade-off |
|---|---|---|
| Chrome-family browser | Primary coverage, especially when you can pin a version | Requires the matching browser binary on the runner |
| Firefox | Secondary coverage for a Firefox user base or browser-specific risk | Adds runtime and another browser environment to maintain |
| WebKit | Experimental investigation where WebKit coverage is important | Experimental support means more qualification and maintenance |
Cypress recommends Chrome for Testing where possible because its versioned binaries do not silently auto-update, improving reproducibility. That is a recommendation for stable automation, not a reason to skip browsers your users depend on. A practical policy is to run the full suite on a primary browser and critical user journeys on secondary browsers, then adjust the split according to product risk, duration, and infrastructure cost.
Electron is documented as deprecated. Do not choose it as a new default without checking the current Cypress browser reference and understanding the migration path.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Repair Windows errors before they cause bigger problems3Fix the driver behind crashes, sound loss and screen glitchesUnderstand headless dimensions and artifacts
Browser display versus application viewport
Cypress documents headless browser defaults of 1280×720 screen size and device pixel ratio 1. These values influence screenshot and video framing. They are not the same as viewportWidth and viewportHeight, which control the page’s application viewport for commands such as responsive-layout assertions.
If artifact framing matters, configure the browser display in the before:browser:launch event and configure the application viewport separately in Cypress configuration or with cy.viewport(). Record both settings in the test documentation so a change to one is not mistaken for a change to the other.
Screenshot and video policy
- Failure screenshots are automatic in
cypress rununless disabled. - Videos are disabled by default; enable
video: truewhen a visual timeline is more useful than its storage and encoding cost. - Compression can reduce file size but adds encoding work.
- Because artifact folders are cleared before runs by default, archive them in the same job that creates them.
Diagnose headed/headless differences
A pass in headed mode and a failure in headless mode (or the reverse) is a signal to compare environments, not proof of one universal cause.
- Run the same browser and spec visibly:
npx cypress run --headed --no-exit --browser chrome --spec path/to/spec.cy.js. - Compare the browser version, operating-system image, viewport, device pixel ratio, base URL, environment variables, and test data.
- Inspect the automatic failure screenshot and any recorded video from the headless run.
- Check server logs, browser console errors, failed network requests, and application timestamps.
- Replace fixed sleeps with assertions that wait for a meaningful UI or API state.
Common possibilities include timing sensitivity, animation or font rendering, browser-version differences, constrained CPU or memory, and a server that was not ready. Treat each as a hypothesis and change one variable at a time. Where your team uses Cypress Test Replay, a recorded run can expose the DOM, network requests, console logs, JavaScript errors, and rendering state for deeper inspection.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Reliability, speed, and cost decisions
Make waiting state-based
Prefer a command that waits for a selector, URL, or aliased request to complete over a fixed delay. State-based waits shorten fast runs and protect slower CI runners without hiding genuine failures.
Control parallel work
Run independent specs in separate CI workers only after the suite is reliable in one worker. Parallelism can reduce wall-clock time while increasing browser, database, and artifact consumption. Ensure test data is isolated so concurrency does not turn ordering assumptions into intermittent failures.
Budget artifact work
Videos, high-resolution screenshots, and aggressive compression affect both job duration and storage. Enable them for the branches or failure paths where they answer a debugging question; retain failure screenshots as the inexpensive baseline.
Pin the environment
Pin Node, Cypress, browser, and container-image versions where practical. Update them deliberately, then review failures as an environment change rather than silently accepting drift.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Common errors and fixes
| Symptom | Likely cause | Fix |
|---|---|---|
| Connection refused or page never loads | Server is not ready, wrong port, or inaccessible preview | Check server logs, verify the URL from the runner, and add a bounded readiness probe before Cypress. |
| “Browser not found” | The requested Chrome or Firefox binary is absent | Install it in the image, use a Cypress image that contains prerequisites, or select a browser that is actually installed. |
| Headless screenshot has unexpected framing | Screen dimensions or device pixel ratio differ from the application viewport | Configure browser launch dimensions and viewportWidth/viewportHeight separately. |
| Video files are missing | Video recording remains disabled or the artifact directory was not archived | Set video: true and upload the configured folder before workspace cleanup. |
| Test is flaky only in CI | Timing, resource pressure, browser drift, or shared test data | Use state-based waits, inspect screenshots/logs, isolate data, and compare pinned versions. |
| Headed mode cannot start in a container | No graphical display is available | Use headless mode for CI, or provide a supported display when interactive debugging is required. |
Or skip the browser setup
If your goal is a clean screenshot or PDF rather than an interactive assertion, ScreenshotNeo provides a website screenshot API and MCP server. It accepts consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each cleanup step can be disabled. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and each response reports the page verdict and billing status in X-Page-Verdict and X-Billed headers.
One GET request is enough. See the full parameter reference in the ScreenshotNeo documentation.
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}`);ScreenshotNeo also offers an MCP server for Claude, Cursor, and other MCP clients with take_screenshot, get_page_info, and capture_pdf. Its options include full-page lazy-image loading, CSS-selector element capture, dark mode, device presets and custom viewports, retina scale, PDF paper and page-range controls, custom CSS and JavaScript, clicks, selector waits, network-idle waits, request blocking, headers, cookies, user agents, authorization, timezone, geolocation, transparent backgrounds, resizing, chosen cache TTLs, signed image links, asynchronous webhooks, bulk capture of 100 URLs per call, a usage API, and an OpenAPI specification. Existing parameter names used by other screenshot APIs also work.
Every plan includes every feature. The Free plan allows 1,000 shots per month with no card; paid plans start at $5 for 3,000 shots, with yearly billing providing two months free. Create a free ScreenshotNeo account to start without a card.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11When Cypress is still the right tool
Use Cypress when you need assertions, retries, controlled test data, browser interaction, and pass/fail results in CI. Use a screenshot API when the deliverable is a rendered image or PDF and maintaining a browser runner would add unnecessary setup. Many teams use both: Cypress validates behavior, while ScreenshotNeo creates clean visual assets or lets an AI agent capture pages on demand.
Frequently Asked Questions
Does Cypress need a virtual display for headless CI?
Not generally. Headless execution can run in a suitable Linux container without extra display configuration; headed debugging does require a graphical display.
Can I test a deployed preview instead of localhost?
Yes. Set CYPRESS_BASE_URL to the preview or staging URL and ensure the CI runner can reach it before invoking cypress run.
Why are my Cypress screenshots different from the page viewport?
Headless screen defaults (1280×720 and device pixel ratio 1) affect artifact framing, while viewportWidth and viewportHeight affect the application viewport. Configure them independently.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
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.
