How to Run tests in headed mode in Cypress (2026)

TL;DR

Run headed Cypress with npx cypress run --headed --browser chrome. Add --spec to watch one file. Headed run mode still exits with codes and can record video; cypress open is the interactive debugger. Prefer headless for normal CI.

Key Takeaways

• Use npx cypress run --headed to show a browser window under run-mode semantics.
• Pin --browser chrome (or another target) so headed repros match the reported environment.
• Headed run mode is not the same as cypress open interactive debugging.
• Keep CI headless by default; only add virtual displays when headed CI is truly required.
• Scope headed investigation with --spec instead of watching the entire suite.
• Keep videos and screenshots even when you observe the run live.
• Do not rely on headed mode to paper over race conditions or weak assertions.

The short answer to cypress how to run tests in headed mode is to pass --headed to cypress run, optionally with --browser chrome (or firefox, edge, electron). Headed mode shows a real browser window while still using the non-interactive run pipeline: exit codes, videos, screenshots, and CI-friendly reporting. It is different from cypress open, which launches the interactive Test Runner GUI for debugging.

Headed runs matter when a failure only appears with a visible window, when you need to watch timing or animations, or when a stakeholder wants to see the suite drive the product. This guide explains headed versus headless, browser choice, config options, CI constraints, video behavior, and how to avoid treating headed mode as a substitute for proper isolation and assertions.

TL;DR

Use headed mode to observe. Use headless mode to gate merges at scale. Use open mode to debug with time travel.

1. Cypress How to Run Tests in Headed Mode: Headed Versus Headless Versus Open

Three related ideas get mixed up in Cypress conversations:

1. Headless run mode: cypress run without a visible browser window (the default for run). Fast, CI-friendly, still real browser automation under the hood.
2. Headed run mode: cypress run --headed with a visible browser window, still non-interactive, still exits when finished.
3. Open mode: cypress open with the Cypress Test Runner UI, command log, and re-run controls.

Headed is not "more correct" than headless for functional assertions. Cypress automates Chromium-based and other supported browsers in both modes. The differences you feel are about window management, GPU and display availability, focus, animations, and human observation. Some flakes that vanish when you stare at a headed window are actually timing bugs, not proof that headless is broken.

When a recruiter or lead asks about cypress how to run tests in headed mode, they often want the CLI flag plus a clear contrast with open mode. Lead with that distinction, then talk about browsers and CI display servers.

2. The Core CLI: --headed, --headless, and --browser

The minimal headed run:

npx cypress run --headed

Pin a browser explicitly (recommended for shared scripts):

npx cypress run --headed --browser chrome
npx cypress run --headed --browser firefox
npx cypress run --headed --browser edge
npx cypress run --headed --browser electron

Force headless when your defaults or environment might open a window:

npx cypress run --headless --browser chrome

List browsers Cypress can see:

npx cypress info
# or
npx cypress run --browser chrome --headed --spec "cypress/e2e/smoke.cy.ts"

Combine headed mode with isolation when you only need to watch one area:

npx cypress run --headed --browser chrome --spec "cypress/e2e/checkout/payment.cy.ts"

That pattern pairs well with how to run a single test in Cypress. Watching an entire suite in headed mode is usually a waste of attention; watch the failing file instead.

npm scripts keep flags consistent:

{
  "scripts": {
    "cy:run": "cypress run --browser chrome",
    "cy:run:headed": "cypress run --headed --browser chrome",
    "cy:open": "cypress open --e2e --browser chrome"
  }
}

npm run cy:run:headed
npm run cy:run:headed -- --spec "cypress/e2e/login.cy.ts"

3. Configure Headed Behavior in cypress.config

CLI flags are enough for most teams, but config can set defaults and browser launch options:

// cypress.config.ts
import { defineConfig } from 'cypress'

export default defineConfig({
  video: true,
  screenshotOnRunFailure: true,
  e2e: {
    baseUrl: 'http://localhost:3000',
    setupNodeEvents(on, config) {
      on('before:browser:launch', (browser = {}, launchOptions) => {
        if (browser.name === 'chrome' && browser.isHeaded) {
          // example: start maximized for easier local observation
          launchOptions.args.push('--start-maximized')
        }
        return launchOptions
      })
      return config
    },
  },
})

Notes on this pattern:

• browser.isHeaded distinguishes headed launch from headless.
• Launch args differ by browser family. Chrome and Edge accept Chromium flags; Firefox uses its own preferences API in the launch event.
• Do not copy random Chrome flags from the internet into CI without understanding them. Many flags change security, GPU, or sandbox behavior.

Prefer keeping headed-only window cosmetics in local scripts, not as mandatory CI config. CI usually wants headless Chrome with stable, documented flags for containers.

4. Compare When to Use Each Execution Style

Headed mode is a diagnostic and demonstration tool. If headed is the only way your suite passes, investigate the underlying flake: missing assertions, animation races, or environment-only dependencies. Do not paper over instability by requiring a human to watch windows.

5. Headed Mode on Local Machines Versus CI Agents

On a developer laptop, headed mode "just works" when a desktop session exists. On CI, there is often no physical display. Options:

1. Stay headless in CI (recommended default).
2. Use a virtual display such as Xvfb on Linux when you truly need headed in CI.
3. Use Cypress Docker images and documented browser setups rather than inventing fragile agent images.

Illustrative Linux pattern (adapt to your agent image):

# conceptual: provide a virtual framebuffer for headed browsers
xvfb-run -a npx cypress run --headed --browser chrome

Many teams never need this. Videos and screenshots from headless runs already show failure context. Headed CI is justified when a defect is display-server specific and you are validating that theory, not as everyday policy.

GitHub Actions style headless job (typical):

- name: Cypress run
  run: npx cypress run --browser chrome
  # headless by default; upload videos/screenshots as artifacts

If you force headed without a display, the browser may fail to launch with errors about missing display, sandbox, or GPU. Fix the environment or switch back to headless rather than disabling security broadly.

6. Browser Choice, Channels, and Binary Paths

--browser accepts family names and, depending on setup, channels or paths:

npx cypress run --headed --browser chrome
npx cypress run --headed --browser chrome:stable
# path form when needed in custom environments
npx cypress run --headed --browser /usr/bin/google-chrome

Electron is convenient because Cypress bundles an Electron browser path for many workflows, but end-user bugs often appear in Chrome or Edge first. For product confidence, keep at least one Chrome headless CI lane. Use headed Chrome locally when a Chrome-only bug is reported.

Firefox support requires a compatible Firefox installation and Cypress browser support for your version pair. If Firefox is not detected, cypress info helps confirm what the runner sees.

When comparing browsers for a single failing path, keep every other variable fixed: same spec, same baseUrl, same viewport, same seed data. Changing five things at once makes headed mode theater instead of science.

7. Videos, Screenshots, and Observability in Headed Runs

Headed runs still produce Cypress artifacts according to config:

export default defineConfig({
  video: true,
  videosFolder: 'cypress/videos',
  screenshotsFolder: 'cypress/screenshots',
  screenshotOnRunFailure: true,
})

Watching the window does not replace artifact capture. You will miss details, and you cannot paste a live window into a ticket. Prefer:

1. Reproduce headed if you need live observation.
2. Keep video enabled for the run.
3. Attach the video and failure screenshot to the bug or PR.

Open mode remains better for command-level inspection. Headed run mode is better when you need "real run" semantics with a visible browser, including exit codes and the same reporter output CI uses.

For flaky network timing while you watch a headed browser, pair with controlled intercepts from the Cypress cy.intercept guide. Visibility of the UI does not make uncontrolled APIs deterministic.

8. Cypress How to Run Tests in Headed Mode Without Slowing the Team

Headed execution is usually slower in human terms because people watch it, and sometimes slower in machine terms because of windowing overhead. Keep headed usage intentional:

1. Default scripts stay headless for everyday local full-file runs.
2. Provide an explicit headed script for investigation.
3. Scope with --spec so nobody watches twenty minutes of unrelated smoke.
4. Record the reason in the PR ("headed repro for focus loss on modal") so the habit does not become cargo cult.

Parallelization and cloud recording services generally assume headless CI. Do not force headed workers across a large grid unless you have a concrete display-related hypothesis and the hardware to support it.

Component testing also supports run and open modes. Headed component runs can help when a component library depends on layout that is easier to see live, but most component failures are clearer in open mode with the component harness.

9. Viewport, Device Emulation, and What Headed Does Not Fix

A visible window does not automatically match a phone or tablet. Control viewport explicitly:

beforeEach(() => {
  cy.viewport(1280, 720)
})

it('shows the mobile nav', () => {
  cy.viewport('iphone-x')
  cy.visit('/')
  cy.get('[data-cy=mobile-menu]').should('be.visible')
})

Headed mode can still use these viewport settings. The window chrome around the page is not the same thing as CSS viewport. For responsive bugs, set cy.viewport (or config defaults) deliberately, then decide whether you also need a headed window to observe transitions.

Similarly, headed mode does not fix:

• Missing data-cy selectors
• Race conditions without proper assertions
• Cross-origin gaps that need cy.origin
• Auth state that should use cy.session

If the test is wrong, a larger monitor will not save it.

10. Launch Flags, Sandbox Issues, and Container Hardening

Containerized browsers sometimes need extra launch configuration. Prefer documented, minimal flags:

on('before:browser:launch', (browser = {}, launchOptions) => {
  if (browser.family === 'chromium' && browser.name !== 'electron') {
    // only when your environment requires it and policy allows it
    // launchOptions.args.push('--disable-dev-shm-usage')
  }
  return launchOptions
})

Guidelines:

• Do not disable the sandbox casually on developer laptops.
• Prefer official Cypress Docker images over ad hoc Chrome installs when possible.
• Separate "CI container needs" from "headed local demo needs."
• Document any required flag in the repo so future agents do not reverse-engineer failures.

When headed Chrome fails to start on Linux CI, read the browser launch error fully. Missing dependencies, missing display, and permission problems have different fixes. Blindly adding every Chrome flag you find on a forum usually creates a worse image.

11. Security, Secrets, and Demo Hygiene in Visible Browsers

A headed browser can expose secrets on a shared screen. During demos:

1. Use staging credentials, not production admin sessions.
2. Avoid typing real API keys into forms while recording.
3. Prefer seeded test users documented for demos.
4. Turn off notifications and unrelated desktop windows.
5. Be careful with live customer data in screenshots and videos.

Headed mode is great for onboarding videos and lunch-and-learns. Treat recordings as potentially sensitive artifacts. Store them where your company already stores test evidence, not in public Slack channels by default.

12. A Decision Playbook for Real Failures

When a test fails in CI headless and someone says "run it headed," use this sequence:

1. Re-run the same command headless locally with the same browser and spec.
2. If it fails, open the video/screenshot; fix the assertion or product bug.
3. If it passes headless locally but fails in CI, compare env, data, and parallelism, not headedness first.
4. If you suspect a focus, blur, or animation issue, re-run headed with --spec and watch once.
5. If headed reveals a real UI defect, add a stable assertion that catches it headless (for example, assert focused element or completed transition class).
6. Return the default pipeline to headless.

This playbook keeps cypress how to run tests in headed mode as a sharp tool. The goal is a suite that fails correctly without a human audience.

Headed Mode Review Checklist

Confirm the command uses --headed and an explicit --browser. Confirm the scope is a single file or small set, not the entire monorepo suite. Confirm videos remain enabled for evidence. Confirm CI still gates on headless unless you have a documented display requirement. Confirm no secrets appear on screen. Confirm the underlying flake has a deterministic assertion, not "works when I watch it." Confirm teammates know the headed npm script name. Confirm open mode was considered for command-level debugging when that is really what you needed. This checklist prevents headed mode from becoming either superstition or a security leak.

13. Team Conventions That Make Headed Mode Predictable

Write a short section in your testing README that states the default is headless CI, the headed script name, and the expected browser. Include one example command for a single-file headed repro and one note about not sharing production credentials on stream. When conventions live only in tribal knowledge, every engineer invents a slightly different headed workflow, and Slack fills with "what flag do I use again?" messages.

Also decide where headed demos fit in release communication. Product managers sometimes ask to "see the tests run" before a major launch. A five-minute headed smoke on a curated @demo tag is perfect. A thirty-minute unattended headed full regression is not. Curate the demo path the same way you curate release notes: intentionally, with a clear audience, and with non-production data.

If your company records lunch-and-learn sessions, store the headed recording beside other internal training assets. Add chapters in the video description for install, headed flag, isolation with --spec, and interpreting a failure screenshot. New hires who can self-serve that video stop blocking seniors for basic runner questions and free senior time for genuine flake analysis.

Finally, revisit headed conventions quarterly. Browser defaults change, Cypress config shapes evolve, and CI images get upgraded. A headed script that pointed at an old Chrome channel can fail mysteriously after an image bump. Treat the headed path as a supported interface of your test platform, not a forgotten alias in package.json.

Interview Questions and Answers

Q: How do you run Cypress tests in headed mode?

I use npx cypress run --headed and usually pin --browser chrome. That shows a real browser window while keeping run-mode reporting and exit codes.

Q: How is headed mode different from cypress open?

Headed run mode is non-interactive and exits when finished. Open mode launches the interactive Test Runner for debugging with time travel and manual re-runs.

Q: Is headless less "real" than headed?

No. Both drive supported browsers. Differences are about display, performance, and some environment factors. Functional coverage should not depend on a human watching.

Q: How do you run headed Cypress in CI?

Usually I do not. I keep CI headless. If headed is required, I provide a virtual display such as Xvfb and still scope the specs tightly.

Q: Which browser do you choose for headed debugging?

I match the browser where the bug was reported, often Chrome. I keep the same viewport and test data as the failing job.

Q: Can you combine headed mode with a single spec?

Yes. npx cypress run --headed --browser chrome --spec "path/to/file.cy.ts" is the standard investigation command.

Q: What artifacts should you keep from a headed run?

Videos and failure screenshots, plus the exact command used. Observation alone is not enough for tickets and regressions.

Common Mistakes

• Confusing --headed with cypress open.
• Running the entire suite headed and calling it debugging.
• Forcing headed CI without a display server, then disabling security to "make it work."
• Assuming a headed pass proves headless CI was wrong without comparing env and data.
• Forgetting --browser and wondering why Electron looks different from Chrome.
• Demoing production credentials in a visible headed window.
• Using headed mode to hide race conditions instead of fixing assertions.
• Changing viewport, browser, and data at the same time during a headed repro.
• Disabling videos because "I watched it live."
• Teaching juniors that headless is fake browser testing.

When comparing headed and headless results for the same spec, capture a small matrix in the ticket: browser name, headed or headless, viewport, baseUrl, seed user, and pass or fail. Two rows often reveal that the failure is data related rather than display related. Five uncontrolled variables turn the investigation into guesswork. The matrix habit is especially useful when a remote teammate cannot watch your headed window live and must trust the written evidence.

If you use Cypress Cloud or another run history service, tag headed investigation runs clearly so they do not pollute flake analytics for the main CI lane. Separate project keys or explicit run tags keep experimental headed sessions from skewing failure rate dashboards. Observability is part of professional headed usage, not an afterthought.

Conclusion

For cypress how to run tests in headed mode, start with npx cypress run --headed --browser chrome and scope the run with --spec when you need to watch real browser chrome under run-mode semantics. Keep everyday CI headless, use open mode for deep debugging, and treat headed execution as an observation tool rather than a quality strategy.

Tomorrow, take one flaky visual or focus-related failure, reproduce it headed on a single file, capture the video, and add a headless-friendly assertion that locks the fix. That is how headed mode earns its place in a professional Cypress toolkit.

Interview Questions and Answers

Frequently Asked Questions

Related Guides

• How to Run tests in headed mode in Playwright (2026)
• How to Run tests in headed mode in Selenium (2026)
• How to Debug a failing test in VS Code in Cypress (2026)
• How to Run a single test in Cypress (2026)
• How to Scroll to an element in Cypress (2026)
• How to Skip and group tests in Cypress (2026)