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.