From your project root, run npx cypress run. Cypress runs the suite to completion in headless mode by default, so you do not need an extra headless flag. To choose Chrome, use npx cypress run --browser chrome; to run one spec, add --spec and its path.
Run Cypress headlessly from the command line
Use the package-manager command that matches your project. The examples below assume Cypress is installed in the project and that you run them from its root directory.
As an Amazon Associate I earn from qualifying purchases.
npx cypress runThis runs the configured test suite and exits when it finishes. Headless is the default for cypress run; there is no need to add a separate headless option.
Install Cypress if it is not already in the project
The Cypress CI setup documentation gives these installation commands:
npm install cypress --save-devyarn add cypress --devpnpm add cypress --save-devbun add cypress --dev
After installation, use the corresponding project-local runner or package-manager script in place of npx if that is how the project is configured.
Choose a browser or a specific spec
Select an installed browser
Pass a browser name with --browser when you want the run to use a particular browser:
npx cypress run --browser chrome
npx cypress run --browser firefoxCypress detects supported browsers that are installed in the local environment. The browser must also be available in your CI image or container. Cypress lists Chrome-family browsers, Firefox, and experimental WebKit among its browser options; availability and installation details can vary by Cypress release, so check the browser reference for the version installed in your project. A browser name is not a way to install that browser.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Run one spec
npx cypress run --spec "cypress/e2e/my-spec.cy.js"Replace the example path with the spec you want to run. The file must match the project’s configured specPattern; a spec outside that pattern will not be discovered as a test. Omit --spec to run the configured suite.
Use Cypress in CI reliably
In a continuous-integration job, make sure the application server is running and responding before Cypress starts. Starting the server and immediately invoking the test command can race: a test may visit the local app before it is ready. Cypress’s CI guidance explicitly warns that there is no guarantee the server has booted by the time cypress run executes.
- Install project dependencies and ensure the CI environment has the browser required by your run.
- Start the application using the project’s normal build or development command.
- Wait for the application URL to respond before running Cypress. Cypress’s official GitHub Action provides
startandwait-onoptions for this workflow. - Run
npx cypress run, adding--browseror--speconly when needed.
Use the same app URL and environment configuration your tests expect. If CI reports navigation or connection failures, first verify that the server is reachable from the job and that the readiness check waits on the correct URL.
Headless and headed runs: what changes
cypress run is the run-to-completion command and launches browsers headlessly by default. Add --headed when you want to see the browser during that CLI run:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
npx cypress run --headed --browser chromecypress open is the interactive workflow: it opens Cypress and a headed browser for choosing and working with tests. Use it for interactive development; use cypress run for a run that completes through the CLI.
Headless viewport and pixel ratio
Cypress documents a default headless screen size of 1280 × 720 and a device pixel ratio (DPR) of 1. These rendering defaults can affect screenshot and video dimensions. Cypress documents changing browser launch behavior through the before:browser:launch event; consult the launch documentation for the configuration appropriate to your installed version.
Save screenshots and video for failures
Failure screenshots
During cypress run, Cypress automatically captures a screenshot when a test fails. The default directory is cypress/screenshots, and Cypress clears that folder before a run unless configured otherwise. To turn off automatic failure screenshots, set screenshotOnRunFailure: false in Cypress configuration.
Video recording
Video recording is disabled by default. Set video: true in Cypress configuration to record video for each spec during cypress run. The default directory is cypress/videos; Cypress clears it before a run unless configured otherwise. Configure artifact retention in CI if you need to inspect the files after the job ends.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Troubleshoot headless test failures
A test passes headed but fails headlessly
Cypress notes that a test can pass in one mode and fail in the other. Reproduce the run with the browser visible and keep Cypress open after the spec:
Rank #4
npx cypress run --headed --no-exit --browser chromeCompare the visible run with the headless failure screenshots or enabled videos. A difference does not by itself prove a rendering problem; inspect the failing assertion, timing, browser, and application state as well.
The requested browser is not found
Install the requested browser in the local environment or use a CI image that supplies it. Confirm that the browser name is supported by the Cypress version in the project and that Cypress detects the installation.
The selected spec is not found
Check the spelling and path passed to --spec, then verify that the file matches the configured specPattern. Run without --spec if you intend to execute all discovered specs.
The app is unavailable when tests start
Do not rely on the server-start command finishing as proof that the site is ready. Add a readiness wait for the app’s actual URL, and check that the server is reachable from the same CI job or container running Cypress.
Best Value
Screenshot or video artifacts are missing
For screenshots, confirm a test failed and that screenshotOnRunFailure has not been disabled. For video, confirm video: true is set. Also account for Cypress clearing the default artifact folders at the start of a run and ensure CI saves the files before cleanup.
Or skip the browser setup
ScreenshotNeo is a website screenshot API, not a Cypress runner: it captures a page but does not execute Cypress tests. If your separate task is to capture a page image or PDF without installing and managing a browser, this one-call request returns a screenshot. See the ScreenshotNeo API documentation for parameters.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp- Cookie and consent banners, newsletter popups, and chat widgets are removed before capture; each step can be turned off.
- Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed. Responses include
X-Page-VerdictandX-Billedheaders. - An MCP server offers
take_screenshot,get_page_info, andcapture_pdftools for AI agents. - The Free plan includes 1,000 screenshots per month with no card required; paid plans start at $5 for 3,000 shots.
Sign up for ScreenshotNeo’s free plan to try it with 1,000 screenshots a month and no card.
Frequently asked questions
Does headless mode mean Cypress runs tests in a different command?
No. The ordinary run command, cypress run, uses headless browser launching by default; headed mode is an explicit option.
Can I use headless Cypress to test a page without running my application?
Cypress tests still need the application or target environment their commands visit. Headless describes whether the browser window is displayed, not whether a site or server is needed.
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.
