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.

Practice

1. What is the main benefit of running Cypress tests in headless mode?

easy

A. Tests run faster without opening the browser window

B. Tests show detailed browser UI for debugging

C. Tests require manual interaction during execution

D. Tests only run on mobile devices

Solution

1. Step 1: Understand headless mode purpose

   Headless mode runs tests without opening the browser window, making execution faster.

2. Step 2: Compare options with headless mode features

   Options B and C describe interactive or visible tests, which are not headless. Tests only run on mobile devices is unrelated.

3. Final Answer:

   Tests run faster without opening the browser window -> Option A

4. Quick Check:

   Headless mode = faster tests without UI [OK]

Hint: Headless means no browser window visible during tests [OK]

Common Mistakes:

• Thinking headless mode shows browser UI
• Confusing headless with manual testing
• Assuming headless only runs on specific devices

2. Which command correctly runs Cypress tests in headless mode?

easy

A. npx cypress run --headless

B. npx cypress open --headless

C. npx cypress start --headless

D. npx cypress test --headless

Solution

1. Step 1: Recall Cypress commands for running tests

   The correct command to run tests in headless mode is npx cypress run --headless.

2. Step 2: Eliminate incorrect commands

   open launches the interactive GUI, start and test are not valid Cypress commands.

3. Final Answer:

   npx cypress run --headless -> Option A

4. Quick Check:

   Run + --headless = correct command [OK]

Hint: Use 'run' command with --headless flag [OK]

Common Mistakes:

• Using 'open' instead of 'run' for headless
• Typing invalid commands like 'start' or 'test'
• Omitting the --headless flag

3. What will happen if you run npx cypress run --headless in your terminal?

medium

A. Cypress opens the browser window and runs tests interactively

B. Tests run in the background without showing the browser UI

C. Tests fail because --headless is not a valid option

D. Cypress opens a GUI to select tests manually

Solution

1. Step 1: Understand the effect of --headless flag

   The --headless flag runs tests without opening the browser window, so tests run in the background.

2. Step 2: Match options with expected behavior

   Cypress opens the browser window and runs tests interactively and D describe interactive modes, which do not happen with --headless. Tests fail because --headless is not a valid option is incorrect because --headless is valid.

3. Final Answer:

   Tests run in the background without showing the browser UI -> Option B

4. Quick Check:

   --headless = background test run [OK]

Hint: Headless runs tests silently without UI [OK]

Common Mistakes:

• Expecting browser window to open
• Thinking --headless is invalid
• Confusing headless with interactive mode

4. You ran npx cypress run --headless but tests did not start. Which is the most likely cause?

medium

A. Headless mode requires a GUI environment

B. You forgot to install Cypress globally

C. You used cypress open --headless instead of run

D. Your test files are missing or misnamed

Solution

1. Step 1: Check the command used

   Using cypress open --headless is invalid because open does not support --headless.

2. Step 2: Evaluate other options

   Installing Cypress globally is not required with npx. Missing test files cause errors but not silent failure. Headless mode does not require GUI.

3. Final Answer:

   You used cypress open --headless instead of run -> Option C

4. Quick Check:

   Use 'run' command with --headless [OK]

Hint: Use 'run' not 'open' with --headless [OK]

Common Mistakes:

• Using 'open' command with --headless
• Assuming global install is mandatory
• Thinking headless needs GUI

5. You want to integrate Cypress tests into a CI pipeline to run automatically without UI. Which approach is best?

hard

A. Run npx cypress open and manually start tests

B. Use npx cypress run without --headless to see browser

C. Run tests only on local machines with GUI

D. Run npx cypress run --headless in the pipeline script

Solution

1. Step 1: Understand CI pipeline needs

   CI pipelines require automated, non-interactive test runs without UI.

2. Step 2: Choose the command that fits automation

   npx cypress run --headless runs tests automatically without opening browser UI, ideal for CI.

3. Step 3: Eliminate other options

   Run npx cypress open and manually start tests requires manual start, C limits tests to local GUI, D shows browser UI which slows CI.

4. Final Answer:

   Run npx cypress run --headless in the pipeline script -> Option D

5. Quick Check:

   CI automation = run with --headless [OK]

Hint: Use headless run for CI automation [OK]

Common Mistakes:

• Running tests manually in CI
• Expecting GUI in CI environment
• Omitting --headless in automated runs