# How to Run Cypress in Headed Mode: Complete Guide to Visible Browser Testing

> Learn to run Cypress in headed mode for visible browser testing using npx cypress run --headed or npx cypress open for the interactive runner. Master visible Cypress tests.

- Repository: [Cypress.io/cypress](https://github.com/cypress-io/cypress)
- Tags: how-to-guide
- Published: 2026-06-16

---

**Use `npx cypress run --headed` to launch a visible browser window, or `npx cypress open` for the interactive test runner UI.**

Running tests in a visible browser is essential for debugging complex interactions and verifying UI behavior in real-time. In the `cypress-io/cypress` repository, headed mode launches an actual browser window rather than running headlessly in the background, allowing you to watch the Test Runner in real time. This guide explains how to run Cypress in headed mode using CLI commands and explores the underlying implementation in the source code.

## What is Headed Mode in Cypress?

Cypress supports two distinct execution modes:

- **Headed mode**: Launches a real browser window (Chrome, Edge, Firefox, or Electron) where you can see the application under test, interact with the page, and watch the Cypress UI execute commands.
- **Headless mode**: Runs tests without any visible UI, executing in the background—this is the default for `cypress run` and is ideal for continuous integration environments.

While headless mode offers faster execution for CI pipelines, headed mode is indispensable for local development and debugging flaky tests.

## CLI Commands to Run Cypress in Headed Mode

### Run Specific Specs with `--headed`

To execute your test suite in a visible browser window from the command line, use the `--headed` flag with the `run` command:

```bash
npx cypress run --headed

```

Target a specific spec file for faster debugging:

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

```

Specify the browser explicitly:

```bash
npx cypress run --headed --browser chrome

```

### Launch the Interactive Test Runner (Always Headed)

The `cypress open` command boots the Electron-based desktop UI, which is inherently headed and requires no additional flags:

```bash
npx cypress open

```

For component testing with the interactive UI:

```bash
npx cypress open --component

```

### Force Headless Mode (The Opposite)

The `--headless` flag forces headless execution, though it is the default for `cypress run`. According to the source code in [`cli/lib/exec/run.ts`](https://github.com/cypress-io/cypress/blob/main/cli/lib/exec/run.ts), these flags are mutually exclusive—when `--headless` is passed, the CLI internally adds `--headed false` to prevent conflicts.

## How the Headed Flag Works Under the Hood

The `--headed` flag flows through several layers of the Cypress architecture:

1. **CLI Parsing**: In [`cli/lib/exec/run.ts`](https://github.com/cypress-io/cypress/blob/main/cli/lib/exec/run.ts), the `processRunOptions` function builds an argument array. When you pass `--headed`, the code executes `args.push('--headed', options.headed)` to forward the flag to the server. If you supply `--headless` instead, the system converts this to `--headed false` to maintain mutual exclusivity.

2. **Server Mode**: The arguments reach [`packages/server/lib/modes/run.ts`](https://github.com/cypress-io/cypress/blob/main/packages/server/lib/modes/run.ts), which interprets the flag and determines whether to launch a browser with a visible UI.

3. **Browser Launcher**: The `@packages/launcher` package receives the headed flag and calls `launchBrowser`. When headed mode is active, the launcher omits the `--headless` argument from Chrome (or equivalent flags for other browsers), allowing the browser window to render normally.

4. **Execution**: The driver injects Cypress code into the visible browser, reports results back to the CLI, and streams UI events if applicable.

## When to Use Headed Mode

Headed mode is not just for watching tests run—it is required for specific workflows:

- **Debugging Flaky Tests**: Seeing the DOM update in real time helps identify race conditions and timing issues that are invisible in headless logs.
- **Browser Extension Support**: Chrome version 137 and later dropped support for the `--load-extension` flag in headless mode. According to the [`npm/puppeteer/README.md`](https://github.com/cypress-io/cypress/blob/main/npm/puppeteer/README.md) in the repository, extensions—including those used by `@cypress/puppeteer`—only work in headed runs.
- **Component Testing**: When running `cypress open --component`, the headed UI allows you to interact with the component preview pane and inspect isolated component behavior.

## Practical Code Examples

Run all specs in a visible Chrome window:

```bash
npx cypress run --headed --browser chrome

```

Debug a single failing spec:

```bash
npx cypress run --headed --spec "cypress/e2e/checkout.cy.js"

```

Programmatic usage from a Node.js script:

```javascript
const { exec } = require('child_process');

// Run in headed mode with Chrome
exec('npx cypress run --headed --browser chrome', (err, stdout, stderr) => {
  console.log(stdout);
  if (err) console.error(stderr);
});

```

## Summary

- Use `npx cypress run --headed` to execute tests in a visible browser window from the command line.
- Use `npx cypress open` for the interactive, always-headed test runner that allows manual spec selection.
- The `--headed` flag is parsed in [`cli/lib/exec/run.ts`](https://github.com/cypress-io/cypress/blob/main/cli/lib/exec/run.ts) and propagated through [`packages/server/lib/modes/run.ts`](https://github.com/cypress-io/cypress/blob/main/packages/server/lib/modes/run.ts) to the `@packages/launcher`.
- Headed mode is required for loading browser extensions in Chrome 137+ and is essential for debugging complex UI interactions.
- For CI environments, omit the flag or use `--headless` to run tests without a UI.

## Frequently Asked Questions

### What is the difference between `cypress run --headed` and `cypress open`?

`cypress run --headed` executes your complete test suite (or specified specs) in a visible browser window and automatically exits when finished. In contrast, `cypress open` launches the interactive Electron-based desktop application where you can manually select individual specs, watch them run in real time, and interact with the Test Runner's time-travel debugging features.

### Can I run specific test files in headed mode?

Yes. Append the `--spec` flag to target specific files while running in headed mode: `npx cypress run --headed --spec "cypress/e2e/login.cy.js"`. This command launches the specified file in a visible browser window, which is useful for isolating and debugging individual test failures.

### Why do browser extensions not work in headless mode?

According to the `cypress-io/cypress` source code, Chrome version 137 and later removed support for the `--load-extension` flag when running in headless mode. Consequently, extensions—including those required by `@cypress/puppeteer`—can only initialize when Cypress runs in headed mode, as the browser must fully render the UI to load extension artifacts.

### How do I programmatically run Cypress in headed mode from JavaScript?

Spawn a child process with the `--headed` flag included in the command string: `exec('npx cypress run --headed --browser chrome', callback)`. The CLI parser in [`cli/lib/exec/run.ts`](https://github.com/cypress-io/cypress/blob/main/cli/lib/exec/run.ts) processes this flag and passes it through the server to the launcher, ensuring the browser launches with a visible window.