Cypress Environment Variables

Environment variables store values that change depending on where a test runs, such as a staging server or a production server. Cypress provides a dedicated system for managing these values. This topic explains how to define and use them.

Defining Environment Variables

Environment variables can be set inside the configuration file under the env key.

module.exports = defineConfig({
  env: {
    apiUrl: 'https://staging-api.example.com',
    adminEmail: 'admin@example.com'
  }
})

A Simple Way to Picture It

Think of environment variables as address labels used for shipping the same package to different cities. The package contents stay the same, but the destination label changes each time. Cypress tests stay the same, but the environment variable values change depending on where the test runs.

Accessing Environment Variables in Tests

The Cypress.env function reads a defined environment variable inside any test file.

const apiUrl = Cypress.env('apiUrl')
cy.request('GET', apiUrl + '/products')

This pattern avoids hardcoding a specific address directly inside the test.

Setting Variables from the Command Line

Cypress allows overriding environment variables temporarily without editing the configuration file.

npx cypress run --env apiUrl=https://production-api.example.com

This approach suits quick test runs against a different environment for a single execution.

Environment Variable Flow Diagram

cypress.config.js (default values)
      |
      v
Command line override (optional)
      |
      v
Cypress.env('apiUrl') reads the final value
      |
      v
Test uses the correct address for its environment

Using a Separate Environment File

Cypress also supports a file named cypress.env.json for storing environment values separately from the main configuration file.

{
  "apiUrl": "https://local-api.example.com"
}

This separation keeps sensitive or environment-specific values out of the main configuration file, which often gets shared through version control.

Why Keep Sensitive Values Separate

Passwords, API keys, and tokens should never sit directly inside a file shared with the whole team. The cypress.env.json file can be excluded from version control using a gitignore rule, keeping private values on each developer's machine only.

Using System Environment Variables

Cypress can also read values from your operating system's environment variables, prefixed with CYPRESS_.

export CYPRESS_apiUrl=https://staging-api.example.com

This approach suits automated pipelines where secrets get injected securely at runtime.

Practical Example: Switching Environments

const baseApi = Cypress.env('apiUrl')

describe('Product API', () => {
  it('returns a list of products', () => {
    cy.request(baseApi + '/products').its('status').should('equal', 200)
  })
})

This test automatically points to whichever address the environment variable currently holds, without needing manual edits for each environment.

Best Practices for Environment Variables

Keep variable names consistent and descriptive across the entire project. Store default values in the configuration file, then override them only when necessary. Avoid mixing sensitive credentials with regular configuration values in the same file.

Key Points

• Environment variables store values that change based on the testing environment.
• Cypress.env reads defined variables inside test files.
• Command-line overrides allow temporary changes without editing files.
• The cypress.env.json file keeps sensitive values separate from shared configuration.
• System-level variables prefixed with CYPRESS_ suit automated pipelines.