Use npx cypress open to author and debug tests in Cypress’s interactive app; use npx cypress run to run tests to completion, usually headlessly, including in CI. They are complementary workflows: develop and inspect tests with open, then use run for repeatable execution.
Install Cypress and open the Test Runner
Install Cypress as a development dependency with the package manager already used by your project. From the project root, run the matching command:
npm install cypress --save-devyarn add cypress --devpnpm add --save-dev cypressbun add --dev cypress
Then launch the interactive app:
npx cypress openUse yarn cypress open, pnpm exec cypress open, or bunx cypress open with those package managers. On first launch, Cypress’s Launchpad guides you through choosing a testing type, creating the configuration and folder structure, and selecting a browser. In open mode, the Test Runner runs specs, displays test activity in the Command Log, and reruns tests when you save changes, so you can inspect the application and step through test behavior. Cypress describes it as the place to run and debug specs in open mode (official open-mode guide).
Make the binary available
The npm package and Cypress application binary are separate parts of setup. Binary installation normally runs as a package-installation postinstall step. If lifecycle scripts are disabled, the binary download was skipped, or your CI cache strategy installs it separately, run the install command for your package manager, such as npx cypress install. See the advanced installation guide for binary installation and cache controls.
Recommended Free Tools
Choose open or run for the job
| Workflow | Command | Best for | Browser display |
|---|---|---|---|
| Interactive | npx cypress open |
Authoring, debugging, and inspecting test behavior | Opens the Cypress app and selected browser |
| Automated | npx cypress run |
Repeatable local runs and CI | Headless by default; add --headed to show the browser |
The CLI’s command reference covers run options. Open mode is the interactive workflow, not a substitute for repeatable CI execution; run is the completion-oriented command, not the interactive debugging interface.
Run tests from the CLI
Run all specs matched by the project configuration with:
npx cypress runChoose a testing type, browser, or spec as needed:
# Run end-to-end tests in the default browser, headlessly
npx cypress run --e2e
# Run component tests and show the browser
npx cypress run --component --headed
# Run one spec
npx cypress run --spec "cypress/e2e/login.cy.js"
# Run matching specs using a glob
npx cypress run --spec "cypress/e2e/**/*.cy.js"
# Select a detected browser
npx cypress run --browser chromeUse the testing type actually configured in your project. Cypress only runs a spec if its path also matches the configured specPattern; a valid file path excluded by that pattern will not be found. Browser availability and compatibility can change, so consult Cypress’s current browser guidance when a specific browser matters. The CLI can select detected browsers and accepts a browser path where needed.
Useful run options
--headeddisplays the browser duringcypress run; without it, the run is headless by default.--speclimits execution to a file or glob that must matchspecPattern.--browserselects a detected browser or a browser executable path.--e2eand--componentselect the testing type.--config-fileselects a different project configuration file;--configoverrides configuration values for this invocation.--reporterselects a Mocha reporter, and--reporter-optionsconfigures it, for example for JUnit output.--envsupplies test environment values. Do not pass sensitive values where they may appear in shell history or CI logs.--record,--group,--tag, and--parallelsupport recording and organizing runs with Cypress Cloud. Parallelization distributes recorded specs across multiple machines.
Set up project scripts and configuration
Scripts give teammates consistent commands without requiring them to remember flags. For example, add scripts to package.json:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
{
"scripts": {
"cy:open": "cypress open",
"cy:run": "cypress run"
}
}Then run npm run cy:open or npm run cy:run. Avoid naming a script simply cypress: Yarn can resolve that script instead of the Cypress binary. Equivalent script execution varies by package manager.
Keep shared settings in the Cypress project configuration file. For a one-off change, use --config; use --config-file when the job needs a different configuration file. CYPRESS_-prefixed environment variables can override configuration for a particular environment. CLI configuration overrides values in the project file. The configuration reference describes configuration values and precedence.
Rank #4
For CI-specific values such as a base URL, reporter, or viewport, provide environment-specific configuration rather than modifying shared settings at runtime. Store record keys and other secrets in your CI provider’s secret manager: command-line secrets can appear in logs. See Cypress’s CI guide.
Run Cypress reliably in CI
A CI job typically installs Cypress, starts the application, waits until it is ready, and then runs cypress run. The readiness wait matters: launching the test command immediately after starting a background server creates a race in which Cypress may start before the application can respond.
Best Value
- Install project dependencies and ensure the Cypress binary is available, including a separate
cypress installstep if your install or cache setup skipped it. - Start the application using the CI workflow’s supported server command.
- Wait for the application URL to respond with a readiness-waiting tool. In the official GitHub Action, use its documented
startandwait-onoptions. - Run the configured tests with
cypress run, adding the browser, reporter, or other options your job requires.
For a basic local CI-style sequence, the key is the wait between server startup and the test command; use your CI provider’s syntax and a readiness tool rather than assuming the background process is ready. The official CI overview explains the supported patterns.
Containers: headless and interactive are different
Headless cypress run can work in a container when the image contains Cypress’s required Linux prerequisites; official Cypress Docker images include them. Interactive cypress open needs a graphical display, which a container does not provide by default. If you need open mode in a container, arrange a display environment rather than treating it like a headless run. Refer to the advanced installation guide for container and system requirements.
Troubleshoot common failures
- The Cypress binary is missing. The package may be present while its application binary was not downloaded. Run the package-manager form of
cypress install, and check whether lifecycle scripts were blocked or the cache strategy expects a separate install step. - No spec files were found. Check the spelling and quoting of the
--specpath, then confirm the file matches the configuredspecPattern. - The browser option fails. Confirm the browser is installed and detectable, or provide its executable path. Check Cypress’s current browser support guidance for version-sensitive compatibility.
- Tests fail because the application is unavailable. Ensure the server process starts successfully and that CI waits for its URL to respond before running Cypress.
cypress opencannot start in a container. Open mode requires a graphical display; use a display-capable environment or use headlesscypress runwhere interactive inspection is not needed.- A config value appears to be ignored. Check whether an invocation-time
--configsetting or aCYPRESS_-prefixed environment variable overrides the project configuration. - A secret appears in logs. Remove it from command-line arguments and use the CI provider’s secret-management mechanism instead.
Or skip the browser setup
For capturing a webpage screenshot rather than running Cypress tests, ScreenshotNeo is a one-request screenshot API and MCP server. Its API accepts a URL and returns an image or PDF. Here is a complete cURL example; see the ScreenshotNeo documentation for API options.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpScreenshotNeo accepts cookie and consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers identify the page verdict and billing status. Its MCP server includes tools for AI agents to take screenshots, get page information, and capture PDFs. The free plan includes 1,000 shots per month with no card required; paid plans start at $5 for 3,000 shots.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Scan for outdated or missing drivers - takes under a minute3Repair Windows errors before they cause bigger problemsSign up for ScreenshotNeo’s free plan: 1,000 screenshots a month, no card required.
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.
