Headless mode in Cypress

Introduction

Headless mode runs tests without opening a browser window. It helps run tests faster and in the background.

When you want to run tests on a server without a screen.

When you want to speed up test runs by skipping the browser UI.

When running tests automatically after code changes.

When integrating tests into continuous integration (CI) pipelines.

When you do not need to watch the test visually.

Syntax

Cypress

npx cypress run --headless

This command runs all tests in headless mode using the default browser.

You can specify a browser with --browser option, for example: npx cypress run --headless --browser chrome.

Examples

Runs all tests in headless mode using the default browser.

Cypress

npx cypress run --headless

Runs tests headlessly in Firefox browser.

Cypress

npx cypress run --headless --browser firefox

Runs only the login test file in headless mode.

Cypress

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

Sample Program

This test visits a page and checks if the title contains 'Kitchen Sink'. Run it with npx cypress run --headless to see the result without opening a browser window.

Cypress

describe('Simple test', () => {
  it('checks page title', () => {
    cy.visit('https://example.cypress.io')
    cy.title().should('include', 'Kitchen Sink')
  })
})

Important Notes

Headless mode is great for automation but you cannot see the test running visually.

Use headless mode in CI pipelines to save resources and speed up tests.

If you want to debug, run tests in headed mode with npx cypress open.

Summary

Headless mode runs tests without showing the browser window.

It is faster and useful for automated test runs and CI pipelines.

Use npx cypress run --headless to run tests this way.