How to Run Cypress Tests in Headless Mode

cypress headless mode

Cypress is a powerful open-source end-to-end testing framework designed for web applications. It simplifies the process of writing and executing tests, providing developers with a robust tool for ensuring the quality and reliability of their web applications.

Running Cypress tests in headless mode means executing the tests without displaying the graphical user interface of the browser. This can be useful in certain scenarios, such as when running tests in a continuous integration (CI) environment or when you want to perform tests without the visual distraction of the browser window.

How to Setup Cypress Headless

Setting up Cypress to run tests in headless mode involves a few steps. Ensure that Node.js and npm (Node Package Manager) are installed on your machine. If not, you can download and install them from the official Node.js website. Below is a general guide on how to set up Cypress in headless mode:

  1. Initiate the Project

Create a folder in your system and open it using any javascript-enabled IDE. Eg. VS Code, IntelliJ, Eclipse, etc. Then initiate the project by using the below command:

npm init command

It will create a package.json file in the project directory. 

  1. Install Cypress

Once you have your project folder created, navigate to your project directory in the terminal and run the following command to install Cypress:

npm install cypress –save-dev

  1. Open Cypress

After the installation is complete, open Cypress for the first time to set up the initial project structure. Run the following command:

npx cypress open

This command opens the Cypress Test Runner

cypress Headless

Here we will select the Testing type. For end-to-end testing select the E2E testing option and for testing individual components or units of a web application select component testing. Here in this example, we have selected E2E testing.

cypress headless for end-to-ending testing

On pressing continue, Cypress will create a ‘cypress’ directory with default files. After selecting your preferred browser, the browser will be opened automatically.

4. Create your first specs

On the opened browser, Select the option whether you want a few already created examples specs or want to start with a new blank specs file.


On selecting the Create new spec option, a new spec file will automatically be generated in the ‘e2e’ subdirectory of the ‘cypress’ directory. Now the project structure will look like this:


5. Configure Headless Mode

By default, Cypress runs tests in headless mode during the command line execution (cypress run). If you want to customize headless options, you can update your npm scripts in ‘package.json’. For example

  "name": "cypress-headless",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "cypress run --headless"
  "author": "Arjun Shrivastva",
  "license": "ISC",
  "devDependencies": {
    "cypress": "^13.6.0"

This script will run Cypress tests in headless mode when you execute npm run test.

6. Customize Headless Options

You can customize headless options by adding additional flags to the cypress run command. For example, to run tests in Chrome in headless mode:

npm run test –browser chrome

Example for Testing with Cypress in Headless Mode

For the example, You will log in to a Demo Website and after that, we will verify that the login is successful.

Test Steps

  1. Navigate to the URL.(
  2. Fill in the ‘Email address’ field
  3. Fill in the ‘Password’ field
  4. Click ‘Sign in’ Button
  5. Verify Login is successful.

Test Script

describe('Login', () => {
  it('Log in successful', () => {

To execute the test script just run the below command:

npm run test

Test Result

After the execution, you can see the test result in the terminal.


Advantages of Cypress Headless

Cypress headless mode, where tests run without a visible browser, provides several key advantages in the realm of automated testing:

1.Resource Optimization

Headless browsers consume far fewer computational resources than their headed counterparts. This means:

  • Reduced memory and CPU usage on your testing machine.
  • Potential to run more tests in parallel, further increasing efficiency.

2. Parallel Execution for Speed

Headless mode supports parallel test execution, enabling multiple tests to run simultaneously without the overhead of managing visible browser windows. This results in significant time savings and improved overall test suite performance.

3. Reduced Flakiness:

Some test failures in headed mode might result from inconsistencies in browser rendering or other visual factors. Headless execution can help minimize these, focusing on functionality rather than rendering quirks.

4. Consistent Testing Environment

Headless mode ensures a consistent testing environment by eliminating variations related to browser window sizes and visibility. This consistency enhances the reliability and predictability of test results across different runs and environments.

5. Seamless Integration with CI/CD Tools:

Cypress headless mode seamlessly integrates with popular CI/CD tools such as Jenkins, Travis CI, and GitLab CI. This allows for the automatic triggering and execution of tests as an integral part of the development and deployment workflows.


In conclusion, running Cypress tests in headless mode is a strategic choice for modern software development. The efficiency gains in CI/CD pipelines, resource optimization, and seamless integration with development workflows make it a compelling approach. Headless mode not only accelerates test execution but also ensures a consistent testing environment, fostering reliability and scalability. As teams strive for faster, more automated testing practices, Cypress headless mode stands out as a valuable tool, facilitating agile development and enhancing the overall quality of software products.