products

Public Environment Variables For Your Tests Using cypress-expose Plugin

How to pass public variables to the browser in Cypress v16.

Recently Cypress announced a change in how it will handle environment variables. Variables were always public and accessible to the application under test in the browser (via calling Cypress.env() method), but now you can have truly private values. I published a blog post Migrating From Cypress.env To cy.env and Cypress.expose Methods describing the change.

Looking at the changes, I noticed a missing area: it is not easy to pass public variables (non-secrets) to Cypress tests. I used a lot of "configuration" values that were meant to be used inside the spec files, and now these values are private by default. For example, let's say we want to run a test only on CI. We could do something like this:

cypress/e2e/ci.cy.js
1
2
3
4
5
6
7
8
9
// only run these tests on CI
if (Cypress.env('ci')) {
  it('has CI variable', () => {
    expect(Cypress.env('ci'), 'CI variable').to.equal(true)
    expect(Cypress.env('ciName'), 'CI name variable').to.equal(
      'GitHub Actions',
    )
  })
}

In Cypress before v15 we could have set / used "ci" and "ciName" via environment variables, for example, if using Cypress github action:

.github/workflows/ci.yml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
name: ci
on: push

jobs:
  test:
    runs-on: ubuntu-24.04
    steps:
      - name: Checkout 🛎
        # https://github.com/actions/checkout
        uses: actions/checkout@v6

      - name: Run tests 🧪
        # https://github.com/cypress-io/github-action
        uses: cypress-io/github-action@v7
        env:
          # default CI variable
          CYPRESS_ci: true
          CYPRESS_ciName: 'GitHub Actions'

The test runs, Cypress.env() returns { ci: true, ciName: 'GitHub Actions' }, everyone is happy. But in Cypress v16 the process environment variables that start with CYPRESS_ are automatically added to the private cy.env space, and are not accessible outside test blocks / hooks. We could still pass them, but now we need to use a complete custom cypress run --expose ... command, instead of letting Cypress GitHub Action do its thing!

This is why I wrote cypress-expose plugin. It grabs every CYPRESS_EXPOSE_... process environment variable and sets it into Cypress.expose object, letting the specs access it. This is meant for public data only! Simply add plugin to your setupNodeEvents callback function and pass the config object.

cypress.config.js
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
const { defineConfig } = require('cypress')
const cypressExpose = require('cypress-expose')

module.exports = defineConfig({
  allowCypressEnv: false,
  e2e: {
    // baseUrl, etc
    supportFile: false,
    fixturesFolder: false,

    setupNodeEvents(on, config) {
      cypressExpose(config)

      // IMPORTANT: return the config object
      // to let Cypress know we modified it
      return config
    },
  },
})

Boom, you are all set. Now any CYPRESS_EXPOSE_... variable is available under camel-cased name. Let's say we run Cypress using the following command:

1
2
3
$ CYPRESS_API_KEY=123secret! \
  CYPRESS_EXPOSE_ANSWER=42 \
  cypress open --env PASS_WORD=my-password --expose USER_NAME=Joe

The api key and the password are going to be reachable via cy.env command, while the answer and the username are publicly accessible using Cypress.expose:

cypress-expose "moved" the environment variable "answer" to be publicly accessible in the browser

The EXPOSE_ANSWER value in the cy.env is null, the plugin overwrites it, but cannot delete it (since Cypress merged any modifications to the env object with the original values). I feel like having null there is enough.

Take the plugin for a spin, let me know if it works for you.