Environment Variables | Cypress Documentation (2024)

caution

Difference between OS-level and Cypress environment variables

In Cypress, "environment variables" are variables that are accessible viaCypress.env. These are not the same as OS-level environment variables.However,it is possible to set Cypress environment variables from OS-level 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

info

Using 'baseUrl'

Environment variables are great at pointing to external services and servers, orstoring password or other credentials.

However, you do not need to use environment variables to point to the originand domain under test. Use baseUrl instead of environment variables.

cy.visit() and cy.request()are automatically prefixed with this value - avoiding the need to specify them.

baseUrl can be set in the Cypress configuration file - and then you can set anenvironment variable in your OS to override it like shown below.

CYPRESS_BASE_URL=https://staging.app.com cypress run

Setting

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

To summarize you can:

Set in your configuration file
Create a cypress.env.json
Export as CYPRESS_*
Pass in the CLI as --env
Set an environment variable within test configuration.

Don't feel obligated to pick just one method. It is common to use one strategyfor local development but another when running inCI.

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

Option #1: configuration file

Any key/value you set in yourCypress configuration under the env keywill become an environment variable.

cypress.config.js
cypress.config.ts

const { defineConfig } = require('cypress')

module.exports = defineConfig({
 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

tip

Benefits

Great for values that need to be checked into source control and remain thesame on all machines.

danger

Downsides

Only works for values that should be the same on across all machines.

Option #2: `cypress.env.json`

You can create your own cypress.env.json file that Cypress will automaticallycheck. Values in here will overwrite conflicting environment variables in yourCypress 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 developermachine.

{
 "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

tip

Benefits

Dedicated file just for environment variables.
Enables you to generate this file from other build processes.
Values can be different on each machine (if not checked into source control).
Supports nested fields (objects), e.g.{ testUser: { name: '...', email: '...' } }.

danger

Downsides

Another file you have to deal with.
Overkill for 1 or 2 environment variables.

Option #3: `CYPRESS_*`

Any exported environment variables set on the command line or in your CIprovider that start with either CYPRESS_ or cypress_ will automatically beparsed by Cypress.

danger

The environment variable CYPRESS_INTERNAL_ENV is reserved and should not beset.

Overriding configuration options

Environment variables that match a corresponding configuration option willoverride any value set in theCypress configuration.

info

Cypress automatically normalizes both the key and the value. The leadingCYPRESS_ or cypress_ is removed and the remaining name is camelCased, whilevalues are converted to Number or Boolean wherever possible.

For example, these enviroment variables in the command line will override anyviewportWidth 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 asenvironment variables for use in tests withCypress.env(), and will override any existing valuesin the Cypress configuration env object and cypress.env.json files.

info

Cypress automatically removes the leading CYPRESS_ or cypress_ from anyenvironment variable name specified in this way.

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:

tip

Benefits

Quickly export some values.
Can be stored in your bash_profile.
Allows for dynamic values between different machines.
Especially useful for CI environments.

danger

Downsides

Not as obvious where values come from versus the other options.
No support for nested fields.

Option #4: `--env`

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

Values here will overwrite all other conflicting environment variables.

You can use the --env argument forcypress run.

caution

Multiple values must be separated by a comma, not a space. In some shells, like Windows PowerShell, you may need to surround the key/value pair with quotes: --env "cyuser=dummyUser,cypassword=dummyPassword".

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 -

tip

Benefits

Does not require any changes to files or configuration.
More clear where environment variables come from.
Allows for dynamic values between different machines.
Overwrites all other forms of setting env variables.

danger

Downsides

Pain to write the --env options everywhere you use Cypress.
No support for nested fields.

Option #5: Test Configuration

You can set environment variables for specific suites or tests by passing theenv values to thetest configuration.

Suite of test configuration

End-to-End Test
Component Test

// 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?')
 })
 }
)

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

tip

Benefits

Only takes effect for duration of suite or test.
More clear where environment variables come from.
Allows for dynamic values between tests

Overriding Configuration

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

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

export CYPRESS_BASE_URL=http://localhost:8080

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

export CYPRESS_FOO=bar

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

Environment Variables | Cypress Documentation (2024)

Instead of hard coding this in your tests:

We can move this into a Cypress environment variable:

Setting

Option #1: configuration file

Test file

Overview

Option #2: `cypress.env.json`

From test file

An Overview

Option #3: `CYPRESS_*`

Overriding configuration options

Overriding environment variables

Overview:

Option #4: `--env`

From the command line or CI

Test file:

Overview -

Option #5: Test Configuration

Suite of test configuration

Single test configuration

Overview

Overriding Configuration

See also

References

Environment Variables | Cypress Documentation (2024)

Instead of hard coding this in your tests:​

We can move this into a Cypress environment variable:​

Setting​

Option #1: configuration file​

Test file​

Overview​

Option #2: cypress.env.json​

From test file​

An Overview​

Option #3: CYPRESS_*​

Overriding configuration options​

Overriding environment variables​

Overview:​

Option #4: --env​

From the command line or CI​

Test file:​

Overview -​

Option #5: Test Configuration​

Suite of test configuration​

Single test configuration​

Overview​

Overriding Configuration​

See also​

References

Instead of hard coding this in your tests:

We can move this into a Cypress environment variable:

Setting

Option #1: configuration file

Test file

Overview

Option #2: `cypress.env.json`

From test file

An Overview

Option #3: `CYPRESS_*`

Overriding configuration options

Overriding environment variables

Overview:

Option #4: `--env`

From the command line or CI

Test file:

Overview -

Option #5: Test Configuration

Suite of test configuration

Single test configuration

Overview

Overriding Configuration

See also