Environment Variables

Environment variables are useful when:

  • Values are different across developer machines.
  • Values are different across multiple environments: (dev, staging, qa, prod)
  • Values change frequently and are highly dynamic.

Environment variables can be changed easily - especially when running in CI.

Instead of hard coding this in your tests:

cy.request('https://api.acme.corp') // this will break on other environments

We can move this into a Cypress environment variable:

cy.request(Cypress.env('EXTERNAL_API')) // points to a dynamic env var

Setting

There are different ways to set environment variables. Each has a slightly different use case.

To summarize you can:

Don't feel obligated to pick just one method. It is common to use one strategy for local development but another when running in CI.

When your tests are running, you can use the Cypress.env function to access the values of your environment variables.

Option #1: configuration file

Any key/value you set in your Cypress configuration under the env key will become an environment variable.

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  projectId: '128076ed-9868-4e98-9cef-98dd8b705d75',
  env: {
    login_url: '/login',
    products_url: '/products'
  }
})
import { defineConfig } from 'cypress'

export default defineConfig({
  projectId: '128076ed-9868-4e98-9cef-98dd8b705d75',
  env: {
    login_url: '/login',
    products_url: '/products'
  }
})
{
  "projectId": "128076ed-9868-4e98-9cef-98dd8b705d75",
  "env": {
    "login_url": "/login",
    "products_url": "/products"
  }
}

Test file

Cypress.env() // {login_url: '/login', products_url: '/products'}
Cypress.env('login_url') // '/login'
Cypress.env('products_url') // '/products'

Overview

Option #2: cypress.env.json

You can create your own cypress.env.json file that Cypress will automatically check. Values in here will overwrite conflicting environment variables in your Cypress configuration.

This strategy is useful because if you add cypress.env.json to your .gitignore file, the values in here can be different for each developer machine.

{
  "host": "veronica.dev.local",
  "api_server": "http://localhost:8888/api/v1/"
}

From test file

Cypress.env() // {host: 'veronica.dev.local', api_server: 'http://localhost:8888/api/v1'}
Cypress.env('host') // 'veronica.dev.local'
Cypress.env('api_server') // 'http://localhost:8888/api/v1/'

An Overview

Option #3: CYPRESS_*

Any exported environment variables set on the command line or in your CI provider that start with either CYPRESS_ or cypress_ will automatically be parsed by Cypress.

Overriding configuration options

Environment variables that match a corresponding configuration option will override any value set in the Cypress configuration.

For example, these enviroment variables in the command line will override any viewportWidth or viewportHeight options set in the Cypress configuration:

export CYPRESS_VIEWPORT_WIDTH=800
export CYPRESS_VIEWPORT_HEIGHT=600

Overriding environment variables

Environment variables that do not match configuration options will be set as environment variables for use in tests with Cypress.env(), and will override any existing values in the Cypress configuration env object and cypress.env.json files.

For example, these environment variables in the command line:

export CYPRESS_HOST=laura.dev.local
export cypress_api_server=http://localhost:8888/api/v1/

Will yield these results inside a test file:

Cypress.env() // {HOST: 'laura.dev.local', api_server: 'http://localhost:8888/api/v1'}
Cypress.env('HOST') // 'laura.dev.local'
Cypress.env('api_server') // 'http://localhost:8888/api/v1/'

Overview:

Option #4: --env

You can pass in environment variables as options when using the CLI tool.

Values here will overwrite all other conflicting environment variables.

You can use the --env argument for cypress run.

From the command line or CI

cypress run --env host=kevin.dev.local,api_server=http://localhost:8888/api/v1

Test file:

Cypress.env() // {host: 'kevin.dev.local', api_server: 'http://localhost:8888/api/v1'}
Cypress.env('host') // 'kevin.dev.local'
Cypress.env('api_server') // 'http://localhost:8888/api/v1/'

Overview -

Option #5: Test Configuration

You can set environment variables for specific suites or tests by passing the env values to the test configuration.

Suite of test configuration

// change environment variable for single suite of tests
describe(
  'test against Spanish content',
  {
    env: {
      language: 'es',
    },
  },
  () => {
    it('displays Spanish', () => {
      cy.visit(`https://docs.cypress.io/${Cypress.env('language')}/`)
      cy.contains('¿Por qué Cypress?')
    })
  }
)
// change environment variable for single suite of tests
describe(
  'test against Spanish content',
  {
    env: {
      language: 'es',
    },
  },
  () => {
    it('displays Spanish', () => {
      cy.mount(<International lang={Cypress.env('language')} />)
      cy.contains('¿Por qué Cypress?')
    })
  }
)

Single test configuration

// change environment variable for single test
it(
  'smoke test develop api',
  {
    env: {
      api: 'https://dev.myapi.com',
    },
  },
  () => {
    cy.request(Cypress.env('api')).its('status').should('eq', 200)
  }
)

// change environment variable for single test
it(
  'smoke test staging api',
  {
    env: {
      api: 'https://staging.myapi.com',
    },
  },
  () => {
    cy.request(Cypress.env('api')).its('status').should('eq', 200)
  }
)

Overview

Overriding Configuration

If your environment variables match a standard configuration key, then instead of setting an environment variable they will instead override the configuration value.

Change the baseUrl configuration value / not set env var in Cypress.env()

export CYPRESS_BASE_URL=http://localhost:8080

'foo' does not match config / sets env var in Cypress.env()

export CYPRESS_FOO=bar

You can read more about how environment variables can change configuration here.

See also