Environment variables for configuration in Cypress - Framework Patterns

Framework Mode - Environment variables for configuration

Folder Structure

  cypress/
  ├── e2e/                  # Test specs
  │   ├── login.cy.js       # Example test file
  │   └── dashboard.cy.js
  ├── fixtures/             # Test data files
  │   └── user.json
  ├── support/              # Custom commands and utilities
  │   ├── commands.js
  │   └── e2e.js
  └── config/               # Configuration files
      ├── baseConfig.js     # Base config shared across envs
      ├── devConfig.js      # Dev environment config
      ├── stagingConfig.js  # Staging environment config
      └── prodConfig.js     # Production environment config
  cypress.config.js          # Main Cypress config file
  .env                      # Environment variables file
  

Test Framework Layers

• Configuration Layer: Holds environment variables and config files to set URLs, credentials, and browser options.
• Support Layer: Contains reusable commands and utilities that use config values dynamically.
• Test Layer: Test specs that read environment variables to run tests against different environments.
• Fixtures Layer: Static test data that can be environment-specific or shared.

Configuration Patterns

Use cypress.config.js to load environment variables from .env files or system variables.

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

  dotenv.config() // Loads .env file into process.env

  export default defineConfig({
    e2e: {
      baseUrl: process.env.BASE_URL || 'http://localhost:3000',
      env: {
        username: process.env.USERNAME,
        password: process.env.PASSWORD
      },
      setupNodeEvents(on, config) {
        // modify config if needed
        return config
      }
    }
  })
  

Access environment variables in tests via Cypress.env('username').

Use different .env files for dev, staging, and prod, and load them before running tests.

Test Reporting and CI/CD Integration

• Use Cypress built-in reporters or plugins like mochawesome for detailed HTML reports.
• Configure CI pipelines (GitHub Actions, Jenkins) to load correct .env files per environment before running tests.
• Fail tests if required environment variables are missing to avoid false passes.
• Publish reports as build artifacts or send notifications on test results.

Best Practices

1. Keep secrets out of code: Store sensitive data like passwords in environment variables, never in test code.
2. Use .env files per environment: Separate config for dev, staging, and prod to avoid mistakes.
3. Access env vars via Cypress.env(): Use Cypress API to read variables, not process.env directly in tests.
4. Validate env vars on startup: Fail fast if required variables are missing to catch config errors early.
5. Document required variables: Keep a README listing all env vars needed for tests.

Self Check

Where in this folder structure would you add a new environment variable for the API base URL used in tests?

Key Result

Use environment variables loaded via Cypress config and .env files to manage test settings securely and flexibly.