Cypress CLI and Test Runner: How to Use Them

Use npx cypress open to author and debug tests interactively; use npx cypress run to execute them to completion, usually in headless mode. They are complementary workflows: open mode gives you the Cypress app, browser, Command Log, and interactive debugging; run mode is suited to repeatable local runs and CI. This guide covers setup, common commands, configuration, and reliable CI execution.

1. Choose open or run

Workflow	Command	Best for	Browser display
Open mode	`npx cypress open`	Writing, inspecting, and debugging specs	Interactive app and browser
Run mode	`npx cypress run`	Repeatable execution and automation	Headless by default; use `--headed` to show it

In open mode, Cypress runs specs in its app, updates the Command Log as tests proceed, and can rerun tests when files are saved. The runner is where you run and debug specs in open mode, as the Cypress open-mode guide explains. Run mode completes execution without requiring interactive inspection.

2. Install Cypress and launch it

Install Cypress as a development dependency with the package manager already used by your project:

# npm
npm install cypress --save-dev

# Yarn
yarn add cypress --dev

# pnpm
pnpm add --save-dev cypress

# Bun
bun add --dev cypress

From the project root, launch the app:

npx cypress open

On first launch, the Launchpad guides you through choosing a testing type, creating configuration and folder structure, and selecting a browser. The project configuration file is typically named cypress.config.js, cypress.config.ts, or an equivalent supported module format. See the official installation guide and open the app guide.

The package and binary are separate

The npm package and Cypress application binary are distinct. Binary installation normally runs as a package lifecycle step. If your environment blocks lifecycle scripts, skips the download, or your CI setup installs the binary separately, run the package-manager form of cypress install after installing the package. Check the advanced installation guide for binary cache and install controls.

3. Add repeatable project scripts

Scripts make the common workflows easy to remember and consistent across a team. Do not name a script cypress; Yarn may resolve that script instead of the Cypress binary.

{
  "scripts": {
    "cy:open": "cypress open",
    "cy:run": "cypress run",
    "cy:run:e2e": "cypress run --e2e",
    "cy:run:component": "cypress run --component"
  },
  "devDependencies": {
    "cypress": "<installed-version>"
  }
}

Then run npm run cy:open while developing or npm run cy:run for an automated run. The exact package version is managed by your package manager and lockfile.

4. Run specs from the CLI

These examples use npm’s npx invocation. Use the equivalent local binary invocation supported by your package manager if needed.

# Run all specs in the configured test type
npx cypress run

# Run one spec
npx cypress run --spec "cypress/e2e/login.cy.js"

# Run matching specs (quote globs so the shell does not expand them first)
npx cypress run --spec "cypress/e2e/**/*.cy.js"

# Select the testing type
npx cypress run --e2e
npx cypress run --component

# Show the browser while run mode executes
npx cypress run --headed

# Select a detected browser
npx cypress run --browser chrome

# Select a browser by executable path
npx cypress run --browser "/path/to/browser"

# Combine options
npx cypress run --e2e --browser chrome --spec "cypress/e2e/smoke.cy.js"

--spec only selects specs allowed by the configured specPattern. If the file exists but Cypress reports that it found no specs, verify both the path and the pattern in configuration. Browser availability and supported names can vary by environment; consult the current browser documentation when compatibility matters.

5. Configure a run

Configuration file and command-line overrides

Keep shared project defaults in Cypress configuration. For a one-off run, select a different file with --config-file, override settings with --config, and pass test environment values with --env. Command-line configuration overrides the configuration file.

# Select a configuration file
npx cypress run --config-file cypress/cypress.staging.config.js

# Override configuration values for this invocation
npx cypress run --config "baseUrl=https://staging.example.com,viewportWidth=1280,viewportHeight=800"

# Provide values available to Cypress tests
npx cypress run --env "apiUrl=https://staging.example.com/api,locale=en"

Environment variables prefixed with CYPRESS_ can also override configuration for an environment. Read the configuration reference for the supported configuration values and precedence details. Avoid putting credentials directly in shell commands: CI logs can expose command arguments. Store secrets in your CI provider’s secret manager and pass them through the supported environment mechanism.

Reporter output

Choose a Mocha reporter with --reporter and set its options with --reporter-options. For example, a JUnit reporter can produce XML output for CI systems that ingest test reports:

npx cypress run --reporter junit --reporter-options "mochaFile=results/test-output-[hash].xml,toConsole=true"

Install the reporter package required by your selected reporter, and configure your CI job to collect the generated files. Reporter names and options depend on the reporter being used.

Cypress Cloud recording and parallel runs

Options including --record, --group, --tag, and --parallel are for organizing runs with Cypress Cloud. Parallelization distributes recorded specs across multiple machines; it is not simply a switch that makes an unrecorded local run parallel. Follow Cypress Cloud setup and protect its record key as a CI secret.

6. Run Cypress reliably in CI

A basic CI sequence is: install dependencies, ensure the Cypress binary is present, start the application, wait until it is ready, then run Cypress. Starting the server in the background and immediately invoking tests creates a race: Cypress may visit the app before the server responds.

# Illustrative shell sequence; use your CI platform's supported readiness tool
npm ci
npx cypress install
npm run start:test &
# Wait for the application's configured readiness URL here.
npx cypress run

Use a readiness-waiting tool or the CI action’s documented start and wait options. The Cypress CI guide describes this pattern and the official GitHub Action’s start and wait-on options. Set environment-specific values such as the base URL or reporter through configuration or CI environment variables, and store secrets in the CI provider’s secret-management system.

Containers and display requirements

Headless cypress run works in a container when its Linux prerequisites are installed; the official Cypress Docker images include required prerequisites. Interactive cypress open needs a graphical display, which a container does not provide by default. Use a display-capable setup if you need open mode in a container; otherwise use headless run mode. See the Cypress container guidance.

7. Troubleshooting

Symptom	Likely cause	What to do
Cypress binary is missing	Lifecycle scripts were blocked or binary installation was skipped	Run `npx cypress install` and inspect the advanced installation settings and cache.
No specs found	The `--spec` path or glob does not match, or the configured `specPattern` excludes the file	Check the path, quote globs in the shell, and review Cypress configuration.
Browser cannot be found	The requested browser is not installed or its name/path is invalid in this environment	Install or select an available browser; check the detected browser list and current browser docs.
Tests fail to load the application in CI	The test run started before the server became ready, or its URL is wrong	Wait for a readiness URL before Cypress starts and confirm the configured base URL.
`cypress open` fails in a container	No graphical display is available	Use headless `cypress run` or provide a display-capable environment.
CLI option appears ignored	There may be a typo, unsupported value, or conflicting configuration	Check the CLI reference and configuration precedence; verify the effective value.
Secret appears in a job log	It was embedded in a command or printed by a script	Move it to CI secret storage, rotate it if exposed, and avoid logging it.

8. Performance, reliability, and cost

Keep runs targeted while iterating. Use open mode to investigate behavior and --spec to run a focused spec when appropriate; run the full suite at the validation points your workflow requires.
Make CI startup deterministic. Waiting for the application to respond removes a common startup race. A readiness check should target the actual app endpoint tests depend on.
Keep local and CI configuration explicit. Use project defaults for shared behavior and per-environment overrides for URLs or viewport settings. Avoid relying on an unstated local browser or environment variable.
Use parallel execution appropriately. Cypress’s documented --parallel option is for recorded Cypress Cloud runs spread across machines. It requires Cloud configuration and is not a generic local speed switch.
Plan infrastructure costs from your environment. Cypress itself does not establish the cost of your CI minutes, browsers, container capacity, or any Cypress Cloud plan in this guide. Check the current provider and product pricing for your setup rather than assuming a fixed cost.

9. Capture a page during development

Sometimes a test failure is easier to inspect as a page image: for example, when checking layout, a visual regression, or a page state that is difficult to describe. You can add browser screenshot logic to a test, or call a screenshot API for a standalone capture. This is separate from Cypress’s open and run commands.

Or skip the browser setup

For a standalone website capture, ScreenshotNeo is a website screenshot API and MCP server for developers. Its one-call API returns a PNG, JPEG, WebP, or PDF; the parameter names used by other screenshot APIs also work, which can make switching easier. See the ScreenshotNeo API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import 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 accepts cookie or consent banners as a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each cleanup step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers report the page verdict and billing status. Its MCP server provides take_screenshot, get_page_info, and capture_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. Every feature is on every plan. Create a free account and get 1,000 screenshots a month with no card.

10. FAQ

Can I use both open mode and run mode in the same project?

Yes. Use open mode for interactive authoring and debugging, and run mode for completion-oriented local or automated execution.

Does `cypress run` always hide the browser?

It is headless by default. Add --headed when you need the browser displayed.

Can I run only one test file?

Yes. Pass its path with --spec, making sure it matches the configured spec pattern.

Why does open mode work locally but not in my container?

Open mode needs a graphical display. Headless run mode has different requirements and is the usual container workflow.