Headless mode in Cypress - Framework Patterns

Framework Mode - Headless mode

Folder Structure of a Cypress Test Project

cypress/
├── e2e/                  # Test specs (end-to-end tests)
│   ├── login.cy.js       # Example test file
│   └── dashboard.cy.js
├── fixtures/             # Test data files (JSON, etc.)
│   └── users.json
├── support/              # Custom commands and reusable utilities
│   ├── commands.js
│   └── e2e.js            # Global setup for tests
cypress.config.js         # Cypress configuration file
package.json              # Project dependencies and scripts

Test Framework Layers

• Test Specs (cypress/e2e/): Contains test scripts that describe user flows and assertions.
• Fixtures (cypress/fixtures/): Holds static test data like JSON files for consistent inputs.
• Support (cypress/support/): Contains reusable commands and setup code to keep tests clean.
• Configuration (cypress.config.js): Defines environment settings, browser options, and test runner behavior.
• Utilities: Custom helper functions or plugins can be added inside support or separate folders.

Configuration Patterns for Headless Mode

To run Cypress tests in headless mode, configure the test runner to launch browsers without UI. This is useful for CI/CD pipelines or faster test runs.

// cypress.config.js
import { defineConfig } from 'cypress'

export default defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      // implement node event listeners here if needed
    },
    baseUrl: 'https://example.com',
    video: true, // record video of tests
    screenshotOnRunFailure: true,
    // other config options
  }
})

Run tests in headless mode from command line:

npx cypress run --headless --browser chrome

This command runs tests without opening the browser window, using Chrome by default or any supported browser.

Environment variables can be passed to customize behavior:

npx cypress run --headless --env login_user=admin,login_pass=1234

Test Reporting and CI/CD Integration

• Headless mode is ideal for CI/CD pipelines because it runs tests without UI, saving resources.
• Use built-in Cypress reporters or plugins like mochawesome for detailed HTML or JSON reports.
• Configure CI tools (GitHub Actions, Jenkins, GitLab CI) to run npx cypress run --headless as part of build steps.
• Store test artifacts like screenshots and videos for failed tests to help debugging.
• Example GitHub Actions snippet:

name: Cypress Tests

on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install Node.js
        uses: actions/setup-node@v3
        with:
          node-version: 20
      - run: npm ci
      - run: npx cypress run --headless
      - name: Upload test artifacts
        if: failure()
        uses: actions/upload-artifact@v3
        with:
          name: cypress-videos
          path: cypress/videos/

Best Practices for Headless Mode in Cypress

1. Use explicit waits and retries: Headless runs can be faster, so ensure tests wait for elements properly to avoid flakiness.
2. Keep tests independent: Each test should clean up after itself to avoid state issues in headless runs.
3. Use environment variables: Manage sensitive data and environment-specific settings outside test code.
4. Record videos and screenshots: Enable these to help debug failures in headless mode where you cannot see the UI.
5. Run tests in parallel: Headless mode supports parallelization to speed up large test suites.

Self-Check Question

Where in this Cypress framework structure would you add a new custom command to handle login functionality for headless test runs?

Key Result

Cypress test framework uses a clear folder structure with configuration to run tests in headless mode for fast, UI-less automation.

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