Cypress App

Cypress.expose

Get and set public configuration in your tests.

Cypress.expose() provides synchronous access to configuration that is safe to expose in the browser context. It may be used for feature flags, plugin configuration, and other public values that need to be available outside of Cypress command chains.

caution

Security considerations

Cypress.expose() is intended for public/non-sensitive configuration values only. Values set with Cypress.expose() are accessible in the browser context, including to application code, third-party scripts, and browser extensions.

Do NOT store sensitive data (API keys, passwords, tokens, etc.) using Cypress.expose(). Use cy.env() for sensitive values.

Syntax

Cypress.expose()
Cypress.expose(key)
Cypress.expose(key, value)
Cypress.expose(object)

Arguments

key (String)

The name of the exposed configuration variable to get or set.

value (any)

The value of the exposed configuration variable to set. Can be any serializable type (string, number, boolean, object, etc.).

object (Object)

Set multiple exposed configuration variables with an object literal. Values are merged with existing values.

Examples

Get all exposed configuration variables

cypress.config.js

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  expose: {
    pluginConfig: 'value1',
    featureFlag: true,
    apiVersion: 2,
  },
})

cypress.config.ts

import { defineConfig } from 'cypress'

export default defineConfig({
  expose: {
    pluginConfig: 'value1',
    featureFlag: true,
    apiVersion: 2,
  },
})

Cypress.expose() // => {pluginConfig: 'value1', featureFlag: true, apiVersion: 2}

Get a single exposed configuration variable

cypress.config.js

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  expose: {
    pluginConfig: 'my-plugin-config',
    featureFlag: true,
  },
})

cypress.config.ts

import { defineConfig } from 'cypress'

export default defineConfig({
  expose: {
    pluginConfig: 'my-plugin-config',
    featureFlag: true,
  },
})

Cypress.expose('pluginConfig') // => "my-plugin-config"
Cypress.expose('featureFlag') // => true
Cypress.expose('nonExistent') // => undefined

Set a single exposed configuration variable

Changes made with Cypress.expose() apply only for the remainder of the current spec file.

cypress.config.js

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  expose: {
    pluginConfig: 'initial-value',
  },
})

cypress.config.ts

import { defineConfig } from 'cypress'

export default defineConfig({
  expose: {
    pluginConfig: 'initial-value',
  },
})

Cypress.expose('pluginConfig', 'updated-value')

Cypress.expose('pluginConfig') // => "updated-value"

Set multiple exposed values

cypress.config.js

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  expose: {
    pluginConfig: 'initial-value',
    featureFlag: false,
  },
})

cypress.config.ts

import { defineConfig } from 'cypress'

export default defineConfig({
  expose: {
    pluginConfig: 'initial-value',
    featureFlag: false,
  },
})

Cypress.expose({
  pluginConfig: 'updated-value',
  featureFlag: true,
})

Cypress.expose() // => {pluginConfig: 'updated-value', featureFlag: true}

Configuration sources

Read the Environment Variables & Secrets guide for more details.

Cypress configuration file

Exposed configuration variables can be set in your Cypress configuration file:

cypress.config.js

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  expose: {
    pluginConfig: 'foo',
    featureFlag: true,
    apiVersion: 1,
  },
})

cypress.config.ts

import { defineConfig } from 'cypress'

export default defineConfig({
  expose: {
    pluginConfig: 'foo',
    featureFlag: true,
    apiVersion: 1,
  },
})

// In your test or support file
const pluginConfig = Cypress.expose('pluginConfig') // => "foo"
const featureFlag = Cypress.expose('featureFlag') // => true
const apiVersion = Cypress.expose('API_VERSION') // => 1

CLI Flags

You can set exposed configuration variables using the --expose or -x CLI flags. CLI values override configuration file values.

cypress run --expose pluginConfig=foo,featureFlag=true,API_VERSION=1

Or using the short form:

cypress run -x pluginConfig=foo,featureFlag=true,API_VERSION=1

Common use cases

Use Cypress.expose() in plugins or support files

Cypress.expose() is ideal when configuration is needed outside of Cypress command chains:

// cypress/support/commands.js or plugin code
const pluginConfig = Cypress.expose('pluginConfig')

if (pluginConfig === 'enabled') {
  initializePlugin(pluginConfig)
}

Migrate from Cypress.env() to Cypress.expose()

If you're migrating a plugin from Cypress.env() to Cypress.expose(), the API is similar:

Before (using deprecated Cypress.env()):

const config = Cypress.env('PLUGIN_CONFIG')

After (using Cypress.expose()):

const config = Cypress.expose('PLUGIN_CONFIG')

Update your configuration file:

Before:

{
  env: {
    PLUGIN_CONFIG: 'value',
  },
}

After:

{
  expose: {
    PLUGIN_CONFIG: 'value',
  },
}

Notes

When to use cy.env() vs Cypress.expose()

Both cy.env() and Cypress.expose() provide access to configuration values in Cypress, but they serve different security and execution needs. Choosing the right API helps avoid accidental exposure of sensitive data and keeps configuration intent clear.

Use Cypress.expose() for public configuration

Recommended when:

• Values are public or non-sensitive - Examples include feature flags, API versions, environment labels, or plugin configuration that is safe to appear in browser state.
• Synchronous access is needed - Cypress.expose() returns values immediately, without requiring Cypress command chaining.

Use cy.env() for sensitive or secret values

Choose cy.env() when security, scoping, and controlled access matter. Recommended when:

• Values are sensitive - API keys, passwords, tokens, or any data that should not be broadly exposed to the browser.
• Security is a priority - cy.env() only exposes the variables you explicitly request and does not automatically serialize them into browser state.
• You're already working within Cypress command chains: cy.env() is asynchronous and designed to be used inside Cypress tests and hooks.

Example: choosing the right API

// ✅ Use cy.env() for sensitive values
cy.env(['apiKey']).then(({ apiKey }) => {
  cy.request({
    url: 'https://api.example.com/users',
    headers: { Authorization: `Bearer ${apiKey}` },
  })
})

// ✅ Use Cypress.expose() for public configuration
const apiVersion = Cypress.expose('apiVersion') // Synchronous, public value
const featureFlag = Cypress.expose('featureFlag') // Safe to expose in browser

See cy.env() for more details.

Scope and lifecycle limitations

• Exposed values persist only while the browser is open.
• Runtime changes apply only within the current spec file
• Values do not propagate back to Node.js contexts such as setupNodeEvents

History

Version	Changes
15.10.0	Cypress.expose() API introduced

See also

• cy.env()
• Cypress.env() - Deprecated API
• Migration Guide to cy.env() - Guide for migrating from Cypress.env()
• Configuration options