How to Run Cypress Tests in Headless Mode: Complete CLI Guide

Use the cypress run command to execute Cypress tests without the interactive GUI, automatically enabling headless mode with Electron or adding --headless for other browsers.

The cypress-io/cypress repository provides a robust command-line interface for running end-to-end tests without a visible browser window. Understanding how to run Cypress tests in headless mode is essential for integrating with continuous integration pipelines and containerized environments where display servers are unavailable.

Headless Execution Architecture

When you invoke cypress run, the system initializes a non-interactive session. In cli/lib/cypress.ts, the CLI sets config.isInteractive = false immediately upon entry, signaling the server to bypass GUI-related services. The @packages/launcher component then determines the target browser and appends the appropriate --headless flag to the underlying driver.

The @packages/server module serves your test files, spawns the browser process, and coordinates WebSocket communication between the browser and Node process. Throughout this execution, the @packages/config system merges CLI flags with user configurations, ensuring the headless setting overrides any headed preferences. Upon completion, Cypress exits with code 0 for success or a non-zero code for failures, enabling reliable CI/CD orchestration.

How to Run Cypress Tests in Headless Mode

Basic Headless Execution

The default cypress run command launches Electron in headless mode automatically. No additional flags are required for the default configuration.

# Basic headless run (default Electron)

yarn cypress:run

Browser-Specific Headless Configuration

To run Cypress tests in headless mode with Chrome, Firefox, Edge, or WebKit, explicitly pass the --headless flag alongside the --browser option.

# Headless run with a specific browser

yarn cypress:run -- --browser chrome --headless

For Chrome versions 112 and later, Cypress automatically forwards the --headless=new flag when detected, leveraging Chrome's updated headless implementation as documented in cli/CHANGELOG.md.

Targeting Specific Spec Files

Limit execution to individual test files using the --spec flag while maintaining headless operation.

# Run a single spec file in headless mode

yarn cypress:run -- --spec "cypress/e2e/login.cy.js" --headless

CI/CD Integration Patterns

Configure your pipeline to fail builds on test failures using exit codes. According to AGENTS.md, standard headless execution returns appropriate exit codes, while --posix-exit-codes provides standardized behavior for automation environments.

# CI-friendly command (fails the build on test failures)

npm run cypress:run -- --headless --record --key $CYPRESS_RECORD_KEY

Configuration and Browser Support

The headless mode configuration flows through several key components:

• CLI Parser (cli/lib/cypress.ts): Parses flags and sets isInteractive: false
• Browser Launcher (packages/launcher): Appends native headless flags to browser binaries for Chrome, Firefox, Edge, and WebKit
• Configuration Merger (packages/config): Resolves conflicts between headless and headed options, with headless taking precedence

Video recording, screenshots, and reporter output function identically in headless mode. Assets are written to the configured videosFolder and screenshotsFolder regardless of GUI availability.

Summary

• Execute cypress run to run Cypress tests in headless mode without GUI dependencies
• The CLI automatically sets config.isInteractive = false in cli/lib/cypress.ts
• Add --headless explicitly when using Chrome, Firefox, Edge, or WebKit browsers
• Chrome 112+ users benefit from automatic --headless=new flag forwarding
• Exit codes (0 for success, non-zero for failures) enable reliable CI/CD integration
• Video recording and screenshots function identically to headed mode, outputting to videosFolder and screenshotsFolder

Frequently Asked Questions

What is the difference between cypress open and cypress run?

The cypress open command launches the interactive Test Runner GUI for local development, while cypress run executes tests in headless mode via the CLI. The latter sets isInteractive to false in the configuration and is designed for automation environments where no display server is available.

Does headless mode support video recording and screenshots?

Yes. Video recording, screenshots, and reporter output function identically in headless mode. Assets are written to the configured videosFolder and screenshotsFolder regardless of whether the browser displays a GUI, as handled by the @packages/server module.

How do I run headless tests in Chrome instead of Electron?

Pass the --browser chrome flag combined with --headless. Electron runs headless by default with cypress run, but Chrome, Firefox, Edge, and WebKit require explicit headless flags. The launcher in packages/launcher handles the browser-specific argument passing, including support for Chrome's --headless=new mode.

Can I use headless mode in Docker containers?

Yes. Headless mode is specifically designed for environments without display servers, making it ideal for Docker containers and CI pipelines. The browser runs without X11 or other GUI dependencies, and the process exits with appropriate codes upon completion, as implemented in the cli/lib/cypress.ts entry point.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}