| | |

Cypress 04 🌲 Running Tests — cypress open vs cypress run

⏱️ Estimated read: 8 min | |

Cypress has two commands for running tests, and the difference is not a flag on the same runner—it is the runner’s entire mode of operation. cypress open launches the interactive Test Runner with a visible browser, a command log, and time-travel debugging. cypress run launches the same browser engine headless, runs the specs, prints the results to the terminal, and exits with a status code. The first is for development; the second is for CI and for a final check before committing.

This chapter covers the two commands, the browser defaults that differ between them, and the headless flag that lets cypress run show the browser when a CI failure needs to be watched. The sections that follow walk through the interactive mode, the headless mode, and the selection flags that narrow a run.

Key point: cypress open runs interactively in a headed browser for debugging; cypress run runs headless by default for CI and exits with a status code, and the --headed flag makes cypress run show the browser without switching to the interactive runner.


a. cypress open and the interactive runner

cypress open launches the Cypress App. The first launch shows the Launchpad (covered in the previous chapter); subsequent launches land on the spec list, where clicking a spec runs it in a visible browser. The Test Runner displays the command log on the left, the application under test on the right, and the time-travel snapshots on hover .

The browser is always headed in this mode. The command log shows every cy command, the assertions that passed or failed, and the network requests. A failing assertion is highlighted in the log, and hovering over a previous command restores the DOM as it was at that moment. The mode is not designed for a full suite run; it is designed for writing a test, watching it fail, and inspecting the failure.

# Open the interactive runner
npx cypress open

# Open directly to E2E specs in Chrome
npx cypress open --e2e --browser chrome

The --e2e and --component flags skip the testing-type prompt and open the spec list for that type. The --browser flag preselects a browser instead of asking .


b. cypress run and the headless mode

cypress run is the CI command. It launches the browser headless by default, runs every spec (or the selected specs), prints the results to stdout, and exits with code 0 if all tests pass or a non-zero code if any fail. The headless browser runs without a visible UI, which is what makes the command suitable for a CI environment with no display .

# Run all specs headless
npx cypress run

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

# Run in a specific browser
npx cypress run --browser chrome

The default browser for cypress run is Electron. A test that passes in cypress run under Electron may fail under a different browser, and a test that passes in cypress open under Chrome may fail in cypress run under Electron. The difference is the browser, not the command. Passing --browser chrome to both commands makes the comparison meaningful .

The --headed flag makes cypress run show the browser window while still running the specs non-interactively. This is the flag for a CI failure that cannot be reproduced locally: run the same command with --headed and watch the browser execute the failing test.

# Run headless but show the browser
npx cypress run --headed --browser chrome

The --headless flag is the explicit opposite, and it is the default for cypress run. It exists for scripts that want to be explicit or that pass --headed conditionally.


c. Selection flags and the CI configuration

The --spec flag selects one or more specs by glob pattern. A single spec runs with its path; a pattern runs every matching spec. The --browser flag selects the browser, and the --config flag overrides configuration values for the run, such as video=false to skip video recording or retries=0 to disable retries for a fast-fail run .

# One spec, no video, no retries
npx cypress run --spec "cypress/e2e/login.cy.js" --config video=false,retries=0

# All specs in a directory
npx cypress run --spec "cypress/e2e/auth/**/*.cy.js"

The --record flag sends the run to Cypress Cloud, which requires a project ID and a record key. The --parallel flag runs specs across multiple machines in Cloud; it has no effect without --record . For a local or self-hosted CI run, neither flag is needed.

The exit code is the contract with CI. cypress run exits 0 on success and non-zero on failure, and the CI step fails when the exit code is non-zero. The --pass-with-no-tests flag (added in 15.11.0) makes a run with no tests exit 0 instead of failing, which is useful when a spec filter matches nothing in a particular environment .


Complete Example Session

# ============================================
# PART 1: INTERACTIVE (DEVELOPMENT)
# ============================================
# Open the runner, watch the browser, inspect the log
npx cypress open

# ============================================
# PART 2: HEADLESS (CI)
# ============================================
# Run all specs, print results, exit code
npx cypress run

# ============================================
# PART 3: SAME BROWSER, BOTH MODES
# ============================================
# The browser must match for a fair comparison
npx cypress open --browser chrome
npx cypress run --browser chrome

# ============================================
# PART 4: SELECTED SPEC, FAST FAIL
# ============================================
npx cypress run \
  --spec "cypress/e2e/login.cy.js" \
  --browser chrome \
  --config video=false,retries=0

# ============================================
# PART 5: WATCH A CI FAILURE
# ============================================
# Headless runner, but visible browser
npx cypress run --headed --browser chrome

The parts covered the interactive mode, the headless CI run, the browser-matching requirement, a selected-spec fast-fail run, and the headed run for watching a failure.


Quick Reference

Command Comparison

Aspectcypress opencypress run
ModeInteractiveNon-interactive
BrowserAlways headedHeadless by default
Default browserUser selectsElectron
OutputCommand log, time-travelTerminal, exit code
UseDevelopment, debuggingCI, final check

Flags

FlagCommandEffect
--e2e / --componentopenSkip testing-type prompt
--browser chromeBothSelect browser
--spec "path"runRun selected specs
--headedrunShow the browser
--config key=valuerunOverride config
--recordrunSend to Cypress Cloud

CI Exit Behavior

ConditionExit Code
All tests pass0
Any test failsNon-zero
No tests match (default)Non-zero
No tests with --pass-with-no-tests0

Best Practices

✅ Do This:

# Develop with open
npx cypress open                                            # ✅

# CI with run
npx cypress run                                             # ✅

# Match the browser in both modes
npx cypress open --browser chrome && npx cypress run --browser chrome # ✅

# Use --headed to watch a CI failure
npx cypress run --headed --browser chrome                   # ✅

❌ Don’t Do This:

# Use open in CI
npx cypress open # hangs, no display                         # ❌

# Compare results across different browsers
# (open on Chrome, run on Electron)                          # ❌

# Use --record without a project ID
npx cypress run --record # fails without setup               # ❌

Common Pitfalls

PitfallWhy It HappensFix
Test passes in open, fails in runDifferent default browserPass --browser to both
CI job hangscypress open usedUse cypress run
Exit code 1 with no test failuresNo specs matchedUse --pass-with-no-tests
Video files not in CIDefault recording offPass --config video=true

Real-World Examples

1. Interactive development

npx cypress open

2. Headless CI run

npx cypress run

3. Single spec

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

4. Specific browser

npx cypress run --browser chrome

5. Fast-fail run

npx cypress run --config video=false,retries=0

6. Watch a failure

npx cypress run --headed --browser chrome

7. Open to E2E in Chrome

npx cypress open --e2e --browser chrome

8. Glob pattern

npx cypress run --spec "cypress/e2e/auth/**/*.cy.js"

9. Allow empty runs

npx cypress run --pass-with-no-tests

10. Record to Cloud

npx cypress run --record --key <key>

Visual

The Two Modes

┌─────────────────────────────────────────────────────────┐
│  cypress open                                           │
│  ┌──────────────────────────────────────────┐           │
│  │ Interactive runner                       │           │
│  │ Visible browser                          │           │
│  │ Command log + time-travel                │           │
│  │ Click a spec to run it                   │           │
│  └──────────────────────────────────────────┘           │
│                                                         │
│  cypress run                                            │
│  ┌──────────────────────────────────────────┐           │
│  │ Headless browser                         │           │
│  │ Terminal output                          │           │
│  │ Exit code for CI                         │           │
│  │ Runs all selected specs                  │           │
│  └──────────────────────────────────────────┘           │
└─────────────────────────────────────────────────────────┘

Browser Defaults

┌─────────────────────────────────────────────────────────┐
│  cypress open          cypress run                      │
│         │                     │                         │
│         ▼                     ▼                         │
│  User selects         Electron (default)                │
│  a browser                                           │
│                                                         │
│  To compare fairly, pass --browser to both.             │
└─────────────────────────────────────────────────────────┘

The --headed Flag

┌─────────────────────────────────────────────────────────┐
│  cypress run --headed                                   │
│         │                                               │
│         ▼                                               │
│  Headless runner logic + visible browser window         │
│                                                         │
│  Use for: watching a CI failure locally                 │
│  Not for: interactive clicking (use open)               │
└─────────────────────────────────────────────────────────┘

CI Exit Flow

┌─────────────────────────────────────────────────────────┐
│  CI step: npx cypress run                               │
│         │                                               │
│         ▼                                               │
│  Run all specs                                          │
│         │                                               │
│    ┌────┴────┐                                          │
│    ▼         ▼                                          │
│  all pass  any fail                                     │
│    │         │                                          │
│    ▼         ▼                                          │
│  exit 0    exit non-zero                                │
│    │         │                                          │
│    ▼         ▼                                          │
│  CI green  CI red                                       │
└─────────────────────────────────────────────────────────┘

Summary

ItemValue
Interactive commandcypress open
Headless commandcypress run
open browserAlways headed
run default browserElectron
run --headedHeadless logic, visible browser
Spec selection--spec "path"
Exit code0 on pass, non-zero on fail
Empty runFails unless --pass-with-no-tests

Key takeaways:

  • cypress open is for development; cypress run is for CI. The interactive runner shows the command log and time-travel snapshots, and it requires a display. The headless runner prints results and exits with a code.
  • The browser defaults differ. cypress open lets the user select a browser; cypress run defaults to Electron. A test that passes in one and fails in the other is usually a browser difference, not a command difference .
  • --headed makes cypress run show the browser without switching to interactive mode. It is the flag for watching a CI failure locally.
  • The exit code is the CI contract. cypress run exits 0 on success and non-zero on failure. A run with no matching specs fails by default; --pass-with-no-tests changes that.
  • The --spec and --config flags narrow and configure the run. A single spec, a glob pattern, or a config override like video=false keeps the run focused and fast.

Remember: The two commands are not two ways to do the same thing; they are two modes of the same runner. open is for watching and debugging, run is for automation. The browser matters more than the command: a test that behaves differently between them is almost always running in a different browser. Pass --browser chrome to both, use --headed when a failure needs to be seen, and let the exit code decide whether CI passes.

Was this helpful?


Stop using slow, ad-bloated tool sites! 🤮

🔎 Search “KandZ Tools” on Google to use many professional utilities for free.

KandZ.me is the ultimate minimalist hub for:
✅ Finance (Mortgage, Interest, Inflation)
✅ Tech (Base64, JSON, Dev Suite, IP)
✅ Health (BMI, BMR, TDEE)
✅ Productivity (Timer, Workspace, QR)

⚡️ Fast & Private
🔒 No data leaves your device
💎 100% Free

🔗 Use it now: https://tools.kandz.me
🔖 Bookmark it—you’ll need it later!