Skip to main content
Cypress App
caution
Deprecated

Cypress.env() was deprecated in Cypress 15.10.0 and will be removed in a future major version.

Cypress recommends migrating to use cy.env() or Cypress.expose() instead.

Please see the Migration Guide for more information.

Cypress.env

get and set environment variables in your tests.

info
Scope

Environment variables set using Cypress.env are only in scope for the current spec file.

Cypress runs each spec file in isolation: the browser is exited between specs. Environment variables added or changed in one spec won't be visible in other specs.

Syntax​

Cypress.env()
Cypress.env(name)
Cypress.env(name, value)
Cypress.env(object)

Arguments​

name (String)

The name of the environment variable to get or set.

value (String)

The value of the environment variable to set.

object (Object)

Set multiple environment variables with an object literal.

Examples​

No Arguments​

Get all environment variables from the Cypress configuration​

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  env: {
    apiUrl: 'https://api.example.com',
    apiVersion: 'v1',
  },
})
Cypress.env() // => {apiUrl: 'https://api.example.com', apiVersion: 'v1'}

Name​

Return a single environment variable from the Cypress configuration​

info
Boolean

We automatically normalize both the key and the value when passed via the command line. Cypress will automatically convert values into Number or Boolean.

CYPRESS_HOST=laura.dev CYPRESS_IS_CI=true CYPRESS_API_VERSION=123 cypress run
Cypress.env('HOST') // => "laura.dev"
Cypress.env('IS_CI') // => true
Cypress.env('API_VERSION') // => 123

Name and Value​

Change environment variables from the Cypress configuration from within your tests​

info
Scope

Remember, any changes that you make to environment variables using this API will only be in effect for the remainder of the tests in the same spec file.

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  env: {
    host: 'laura.dev',
  },
})
Cypress.env('host', 'http://server.dev.local')

Cypress.env('host') // => http://server.dev.local

Object​

Override multiple values from the Cypress configuration by passing an object​

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  env: {
    host: 'laura.dev',
    apiVersion: 'v1',
  },
})
Cypress.env({
  host: 'http://server.dev.local',
  apiVersion: 'v2',
})

Cypress.env() // => {apiVersion: 'v2', host: 'http://server.dev.local'}

From a plugin​

Here's an example that uses Cypress.env to access an environment variable that's been dynamically set in a plugin.

Use this approach to grab the value of an environment variable once before any of the tests in your spec run.

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  // setupNodeEvents can be defined in either
  // the e2e or component configuration
  e2e: {
    setupNodeEvents(on, config) {
      config.env.apiBaseUrl =
        process.env.NODE_ENV === 'qa'
          ? 'https://api-qa.example.com'
          : 'https://api.example.com'

      return config
    },
  },
})
// cypress/e2e/api-tests.cy.js
describe('API tests', () => {
  let apiBaseUrl

  before(() => {
    apiBaseUrl = Cypress.env('apiBaseUrl')
  })

  it('can make requests to the correct environment', () => {
    cy.request({
      method: 'GET',
      url: `${apiBaseUrl}/users`,
    }).then((response) => {
      expect(response.status).to.eq(200)
    })
  })
})

Notes​

Why would I ever need to use environment variables?​

The Environment Variables & Secrets guide explains common use cases.

Can I pass in environment variables from the command line?​

Yes. You can do that and much more.

The Environment Variables & Secrets guide explains the other ways you can set environment variables for your tests.

History​

VersionChanges
15.10.0Cypress.env() API deprecated

See also​

Contents