Test configuration per environment in Cypress - Framework Patterns

Framework Mode - Test configuration per environment

Folder Structure

cypress/
├── e2e/                  # Test specs organized by feature
│   ├── login.cy.js
│   ├── dashboard.cy.js
│   └── ...
├── fixtures/             # Static test data files (JSON)
│   └── users.json
├── support/              # Custom commands and global hooks
│   ├── commands.js
│   └── e2e.js
cypress.config.js         # Main Cypress configuration file
cypress.env.json          # Default environment variables
.env.development.json     # Development environment variables
.env.staging.json         # Staging environment variables
.env.production.json      # Production environment variables
package.json             # Project dependencies and scripts

Test Framework Layers

• Configuration Layer: Holds environment-specific settings in separate JSON files and cypress.config.js loads them based on environment.
• Test Layer: Test files inside cypress/e2e/ folder use config values via Cypress.env().
• Support Layer: Custom commands and global setup in cypress/support/ to reuse code and initialize tests.
• Fixtures Layer: Static test data stored in cypress/fixtures/ to separate data from test logic.

Configuration Patterns

Use separate environment files for each environment, for example:

• .env.development.json for development
• .env.staging.json for staging
• .env.production.json for production

In cypress.config.js, load the correct environment file based on a CLI argument or environment variable:

import { defineConfig } from 'cypress'
import fs from 'fs'

function loadEnvConfig(env) {
  const path = `./.env.${env}.json`
  if (fs.existsSync(path)) {
    return JSON.parse(fs.readFileSync(path, 'utf-8'))
  }
  return {}
}

export default defineConfig({
  e2e: {
    setupNodeEvents(on, config) {
      const env = config.env.environment || 'development'
      const envConfig = loadEnvConfig(env)
      config.env = { ...config.env, ...envConfig }
      return config
    },
    baseUrl: 'http://localhost:3000',
    specPattern: 'cypress/e2e/**/*.cy.js'
  }
})

Run tests with environment selection:

npx cypress run --env environment=staging

Access environment variables in tests with Cypress.env('variableName').

Test Reporting and CI/CD Integration

• Use built-in Cypress reporters or add plugins like mochawesome for detailed HTML reports.
• Configure CI pipelines (GitHub Actions, Jenkins, GitLab CI) to run tests with different environment configs by passing --env environment=staging or similar.
• Store test reports as artifacts in CI for review.
• Fail the build if tests fail to ensure quality gates per environment.

Best Practices

1. Separate environment configs: Keep environment-specific data outside test code for easy updates and security.
2. Use Cypress.env() consistently: Access all environment variables through this method to keep tests flexible.
3. Secure sensitive data: Do not commit secrets to version control; use environment variables or secret managers in CI.
4. Parameterize test runs: Allow easy switching of environments via CLI arguments or environment variables.
5. Keep config files simple: Use JSON format for easy parsing and editing.

Self Check

Where in this folder structure would you add a new environment variable for the staging environment?

Key Result

Use separate JSON environment files loaded dynamically in cypress.config.js to manage test configuration per environment.