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.

Practice

1. What is the main purpose of environment variables in Cypress testing?

easy

A. To configure tests without changing the test code

B. To write test assertions

C. To locate elements on the page

D. To generate test reports

Solution

1. Step 1: Understand environment variables role

   Environment variables store configuration data separately from code.

2. Step 2: Identify their use in Cypress

   They allow changing test settings without modifying test scripts.

3. Final Answer:

   To configure tests without changing the test code -> Option A

4. Quick Check:

   Environment variables = configure tests without code change [OK]

Hint: Environment variables store config, not test logic [OK]

Common Mistakes:

• Confusing environment variables with test assertions
• Thinking environment variables locate page elements
• Assuming environment variables generate reports

2. Which is the correct way to access an environment variable named API_URL inside a Cypress test?

easy

A. Cypress.env('API_URL')

B. process.env.API_URL

C. env.API_URL

D. getEnv('API_URL')

Solution

1. Step 1: Recall Cypress environment variable syntax

   Cypress uses Cypress.env('VAR_NAME') to access env variables.

2. Step 2: Match the correct syntax

   Only Cypress.env('API_URL') uses this correct method.

3. Final Answer:

   Cypress.env('API_URL') -> Option A

4. Quick Check:

   Access env vars with Cypress.env('VAR_NAME') [OK]

Hint: Use Cypress.env('VAR_NAME') to get env variables [OK]

Common Mistakes:

• Using Node.js process.env inside Cypress tests
• Trying to access env vars as plain variables
• Using incorrect function names like getEnv

3. Given the following cypress.config.js snippet:

export default defineConfig({
  env: {
    USERNAME: 'testUser',
    PASSWORD: 'pass123'
  }
})

What will cy.log(Cypress.env('USERNAME')) print during test execution?

medium

A. undefined

B. 'USERNAME'

C. 'testUser'

D. An error

Solution

1. Step 1: Check environment variable definition

   USERNAME is set to 'testUser' in cypress.config.js under env.

2. Step 2: Understand Cypress.env usage

   Cypress.env('USERNAME') returns the value 'testUser'.

3. Final Answer:

   'testUser' -> Option C

4. Quick Check:

   Cypress.env('USERNAME') = 'testUser' [OK]

Hint: Env vars return their set values, not keys [OK]

Common Mistakes:

• Expecting the key name instead of the value
• Assuming undefined if not set in test file
• Thinking Cypress.env throws error if variable exists

4. You wrote this code in your test:

const apiUrl = Cypress.env.API_URL;
cy.visit(apiUrl);

But the test fails with TypeError: Cannot read property 'API_URL' of undefined. What is the problem?

medium

A. cy.visit() cannot accept variables

B. The environment variable API_URL is not set in cypress.config.js

C. You must import Cypress before using it

D. You should use Cypress.env('API_URL') instead of Cypress.env.API_URL

Solution

1. Step 1: Identify how Cypress.env is accessed

   Cypress.env is a function, not an object, so use parentheses and quotes.

2. Step 2: Understand the error cause

   Using dot notation like Cypress.env.API_URL causes undefined error.

3. Final Answer:

   You should use Cypress.env('API_URL') instead of Cypress.env.API_URL -> Option D

4. Quick Check:

   Access env vars with Cypress.env('VAR_NAME') [OK]

Hint: Always call Cypress.env() as a function with string key [OK]

Common Mistakes:

• Using dot notation instead of function call
• Assuming env vars are properties, not accessed by function
• Ignoring error message details

5. You want to run Cypress tests with a different API URL without changing cypress.config.js. Which command line option correctly sets the environment variable API_URL to https://api.test.com?

hard

A. cypress run --config API_URL=https://api.test.com

B. cypress run --env API_URL=https://api.test.com

C. cypress open --env API_URL=https://api.test.com

D. cypress open --config API_URL=https://api.test.com

Solution

1. Step 1: Understand command line env variable setting

   Use --env VAR_NAME=value to set env variables temporarily.

2. Step 2: Identify correct command for running tests

   cypress run runs tests in headless mode; --env sets env vars.

3. Final Answer:

   cypress run --env API_URL=https://api.test.com -> Option B

4. Quick Check:

   Use --env to set env vars on command line [OK]

Hint: Use --env VAR=value with cypress run to override env vars [OK]

Common Mistakes:

• Using --config instead of --env for environment variables
• Trying to set env vars with cypress open command
• Confusing config options with env variables