Cypress.env

get and set environment variables in your tests.

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: {
    foo: 'bar',
    baz: 'quux'
  }
})

import { defineConfig } from 'cypress'

export default defineConfig({
  env: {
    foo: 'bar',
    baz: 'quux'
  }
})

{
  "env": {
    "foo": "bar",
    "baz": "quux"
  }
}

Cypress.env() // => {foo: 'bar', baz: 'quux'}

Name

Return a single environment variable from the Cypress configuration

CYPRESS_HOST=laura.dev CYPRESS_IS_CI=true CYPRESS_MY_ID=123 cypress run

Cypress.env('HOST') // => "laura.dev"
Cypress.env('IS_CI') // => true
Cypress.env('MY_ID') // => 123

Name and Value

Change environment variables from the Cypress configuration from within your tests

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  env: {
    foo: 'bar',
    baz: 'quux'
  }
})

import { defineConfig } from 'cypress'

export default defineConfig({
  env: {
    foo: 'bar',
    baz: 'quux'
  }
})

{
  "env": {
    "foo": "bar",
    "baz": "quux"
  }
}

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: {
    foo: 'bar',
    baz: 'quux'
  }
})

import { defineConfig } from 'cypress'

export default defineConfig({
  env: {
    foo: 'bar',
    baz: 'quux'
  }
})

{
  "env": {
    "foo": "bar",
    "baz": "quux"
  }
}

Cypress.env({
  host: 'http://server.dev.local',
  foo: 'foo',
})

Cypress.env() // => {foo: 'foo', baz: 'quux', 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.sharedSecret =
        process.env.NODE_ENV === 'qa' ? 'hoop brick tort' : 'sushi cup lemon'
      
      return config
    }
  }
})

import { defineConfig } from 'cypress'

export default defineConfig({
  // setupNodeEvents can be defined in either
  // the e2e or component configuration
  e2e: {
    setupNodeEvents(on, config) {
      config.env.sharedSecret =
        process.env.NODE_ENV === 'qa' ? 'hoop brick tort' : 'sushi cup lemon'
      
      return config
    }
  }
})

// cypress/plugins/index.js

module.exports = (on, config) => {
  config.env.sharedSecret =
    process.env.NODE_ENV === 'qa' ? 'hoop brick tort' : 'sushi cup lemon'
  
  return config
}

// cypress/e2e/secrets.cy.js
describe('Environment variable set in plugin', () => {
  let sharedSecret

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

  it.only('can be accessed within test.', () => {
    cy.log(sharedSecret)
  })
})

Notes

Why would I ever need to use environment variables?

The Environment Variables 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 guide explains the other ways you can set environment variables for your tests.

Why is it Cypress.env and not cy.env?

As a rule of thumb anything you call from Cypress affects global state. Anything you call from cy affects local state.

Since the environment variables added or changed by Cypress.env are only in scope for the current spec file, you'd think that it should be cy.env and not Cypress.env… and you'd be right. The fact that Cypress.env affects local state is an artifact of the API evolving over time: Cypress.env used to affect global state—environment variables added in one test spec file were available in other specs—but the Cypress team wisely made each spec run in isolation in 3.0.0 and by that time Cypress.env was public API.

See also