feat: add cy.env(), allowCypressEnv, and deprecate Cypress.env()

Split up Deprecations + features in changelog

Split up other features

Author: AtofStryker

cli/CHANGELOG.md

@@ -1,8 +1,17 @@
 <!-- See the ../guides/writing-the-cypress-changelog.md for details on writing the changelog. -->
-## 15.9.1
+## 15.10.0
 
 _Released 01/27/2026 (PENDING)_
 
+**Deprecations:**
+
+[`Cypress.env()](https://docs.cypress.io/api/cypress-api/env) is now deprecated and will be removed in a future major release of Cypress. To understand why, and how to migrate, please read our [Migration Guide](https://on.cypress.io/cypress-env-migration). Addressed in [#33181](https://github.com/cypress-io/cypress/pull/33181).
+
+**Features:**
+
+- Introduced a new [`cy.env()`](https://docs.cypress.io/api/commands/env) command that can be used to asynchronously and securely access Cypress environment variables. Addressed in [#33181](https://github.com/cypress-io/cypress/pull/33181).
+- Added a [`allowCypressEnv`](https://docs.cypress.io/app/references/configuration#Global) configuration option that disallows use of the deprecated `Cypress.env()` API. Addressed in [#33181](https://github.com/cypress-io/cypress/pull/33181).
+
 **Misc:**
 
 - The icon in the 'Open in IDE' button in the command log is now the correct size. Addresses [#32779](https://github.com/cypress-io/cypress/issues/32779). Addressed in [#33217](https://github.com/cypress-io/cypress/pull/33217).

cli/types/cypress.d.ts

@@ -512,6 +512,7 @@ declare namespace Cypress {
      * Returns all environment variables set with CYPRESS_ prefix or in "env" object in "cypress.config.{js,ts,mjs,cjs}"
      *
      * @see https://on.cypress.io/env
+     * @deprecated Use {@linkcode Chainable.env cy.env()} instead.
      */
     env(): ObjectLike
     /**
@@ -521,6 +522,7 @@ declare namespace Cypress {
      *    // cypress.config.js
      *    { "env": { "foo": "bar" } }
      *    Cypress.env("foo") // => bar
+     * @deprecated Use {@linkcode Chainable.env cy.env()} instead.
      */
     env(key: string): any
     /**
@@ -529,13 +531,15 @@ declare namespace Cypress {
      * @see https://on.cypress.io/env
      * @example
      *    Cypress.env("host", "http://server.dev.local")
+     * @deprecated Use {@linkcode Chainable.env cy.env()} instead.
      */
     env(key: string, value: any): void
     /**
      * Set values for multiple variables at once. Values are merged with existing values.
      * @see https://on.cypress.io/env
      * @example
      *    Cypress.env({ host: "http://server.dev.local", foo: "foo" })
+     * @deprecated Use {@linkcode Chainable.env cy.env()} instead.
      */
     env(object: ObjectLike): void
 
@@ -2191,6 +2195,25 @@ declare namespace Cypress {
      */
     task<S = unknown>(event: string, arg?: any, options?: Partial<Loggable & Timeoutable>): Chainable<S>
 
+    /**
+     * Gets multiple environment variables.
+     * @see https://on.cypress.io/env
+     * @example
+     *    cy.env(['KEY_1', 'KEY_2']).then(({ KEY_1, KEY_2 }) => { ... })
+     */
+    env(keys: string[]): Chainable<Record<string, any>>
+
+    /**
+     * Gets multiple environment variables with a specific type.
+     * @see https://on.cypress.io/env
+     * @example
+     *    cy.env<{ KEY_1: string, KEY_2: number }>(['KEY_1', 'KEY_2']).then(({ KEY_1, KEY_2 }) => {
+     *      expect(KEY_1).to.be.a('string')
+     *      expect(KEY_2).to.be.a('number')
+     *    })
+     */
+    env<T extends object>(keys: string[]): Chainable<T>
+
     /**
      * Enables you to work with the subject yielded from the previous command.
      *
@@ -2934,6 +2957,18 @@ declare namespace Cypress {
      * @default null
      */
     baseUrl: string | null
+
+    /**
+     * Whether Cypress should allow [Cypress.env()](https://on.cypress.io/env) API to be available in the browser.
+     *
+     * Cypress recommends migrating to the cy.env() command and disabling this within your Cypress configuration.
+     *
+     * The use of Cypress.env() will warn and throw an error when this is set to false.
+     *
+     * This will be the default behavior in a future major version of Cypress and Cypress.env() will be removed.
+     * @default true
+     */
+    allowCypressEnv: boolean
     /**
      * Any values to be set as [environment variables](https://on.cypress.io/environment-variables)
      * @default {}

npm/grep/cypress.config.ts

@@ -8,6 +8,7 @@ import debug from 'debug'
 const debugInstance = debug('cypress:grep:compare-results')
 
 export default defineConfig({
+  allowCypressEnv: true,
   e2e: {
     defaultCommandTimeout: 1000,
     setupNodeEvents (on, config) {

npm/vite-dev-server/cypress.config.ts

@@ -1,5 +1,6 @@
 import { defineConfig } from 'cypress'
 import { e2ePluginSetup } from '@packages/frontend-shared/cypress/e2e/e2ePluginSetup'
+import { setupCyInCyVariables } from '@packages/frontend-shared/cypress/tasks/cy-in-cy-variables'
 
 export default defineConfig({
   projectId: 'ypt4pf',
@@ -16,6 +17,13 @@ export default defineConfig({
       process.env.CYPRESS_INTERNAL_E2E_TESTING_SELF = 'true'
       process.env.CYPRESS_INTERNAL_VITE_OPEN_MODE_TESTING = 'true'
 
+      const { setCyInCyVariables, getCyInCyVariables } = setupCyInCyVariables()
+
+      on('task', {
+        setCyInCyVariables,
+        getCyInCyVariables,
+      })
+
       return await e2ePluginSetup(on, config)
     },
   },

npm/webpack-dev-server/cypress.config.ts

@@ -1,4 +1,5 @@
 import { defineConfig } from 'cypress'
+import { setupCyInCyVariables } from '@packages/frontend-shared/cypress/tasks/cy-in-cy-variables'
 
 export default defineConfig({
   projectId: 'ypt4pf',
@@ -14,6 +15,12 @@ export default defineConfig({
       delete process.env.CYPRESS_INTERNAL_E2E_TESTING_SELF_PARENT_PROJECT
       process.env.CYPRESS_INTERNAL_E2E_TESTING_SELF = 'true'
       const { e2ePluginSetup } = require('@packages/frontend-shared/cypress/e2e/e2ePluginSetup') as typeof import('@packages/frontend-shared/cypress/e2e/e2ePluginSetup')
+      const { setCyInCyVariables, getCyInCyVariables } = setupCyInCyVariables()
+
+      on('task', {
+        setCyInCyVariables,
+        getCyInCyVariables,
+      })
 
       return await e2ePluginSetup(on, config)
     },

packages/app/cypress.config.ts

@@ -1,8 +1,14 @@
 import { defineConfig } from 'cypress'
 import { initGitRepoForTestProject, resetGitRepoForTestProject } from './cypress/tasks/git'
 import { writeMochaEventSnapshot, readMochaEventSnapshot } from './cypress/tasks/mochaEvents'
+import { setupCyInCyVariables } from '@packages/frontend-shared/cypress/tasks/cy-in-cy-variables'
 
 export default defineConfig({
+  /**
+   * NOTE: currently using Cypress.env() in the test config, so we need to set allowCypressEnv to true
+   * @percy/cypress: https://github.com/percy/percy-cypress/blob/master/index.js#L13
+   */
+  allowCypressEnv: true,
   projectId: 'ypt4pf',
   retries: {
     runMode: 2,
@@ -47,11 +53,15 @@ export default defineConfig({
       process.env.CYPRESS_INTERNAL_VITE_OPEN_MODE_TESTING = 'true'
       const { e2ePluginSetup } = require('@packages/frontend-shared/cypress/e2e/e2ePluginSetup')
 
+      const { setCyInCyVariables, getCyInCyVariables } = setupCyInCyVariables()
+
       on('task', {
         initGitRepoForTestProject,
         resetGitRepoForTestProject,
         writeMochaEventSnapshot,
         readMochaEventSnapshot,
+        setCyInCyVariables,
+        getCyInCyVariables,
       })
 
       return await e2ePluginSetup(on, config)

packages/app/cypress/e2e/runner/support/mochaEventsUtils.ts

@@ -175,16 +175,17 @@ export function runCypressInCypressMochaEventsTest (snapToCompare: string, done:
     }).then((snapshot) => {
       cy.task('readMochaEventSnapshot', { filename }).then((existingSnapshots: any) => {
         existingSnapshots ||= {}
-
-        if (Cypress.env('SNAPSHOT_UPDATE') === 1) {
-          // overwrite the existing snapshot and write it to disk
-          existingSnapshots[snapToCompare] = snapshot
-          cy.task('writeMochaEventSnapshot', { filename, snapshots: existingSnapshots }).then(() => {
+        cy.env(['SNAPSHOT_UPDATE']).then(({ SNAPSHOT_UPDATE }) => {
+          if (SNAPSHOT_UPDATE === 1) {
+            // overwrite the existing snapshot and write it to disk
+            existingSnapshots[snapToCompare] = snapshot
+            cy.task('writeMochaEventSnapshot', { filename, snapshots: existingSnapshots }).then(() => {
+              bus.emit('assert:cypress:in:cypress', existingSnapshots, snapshot)
+            })
+          } else {
             bus.emit('assert:cypress:in:cypress', existingSnapshots, snapshot)
-          })
-        } else {
-          bus.emit('assert:cypress:in:cypress', existingSnapshots, snapshot)
-        }
+          }
+        })
       })
     })
   }

packages/config/src/browser.ts

@@ -70,8 +70,8 @@ export function resetIssuedWarnings () {
 }
 
 const validateNoBreakingOptions = (breakingCfgOptions: Readonly<BreakingOption[]>, cfg: any, onWarning: ErrorHandler, onErr: ErrorHandler, testingType?: TestingType) => {
-  breakingCfgOptions.forEach(({ name, errorKey, newName, isWarning, value }) => {
-    if (_.has(cfg, name)) {
+  breakingCfgOptions.forEach(({ name, errorKey, newName, isWarning, value, shouldDisplayOrThrow }) => {
+    if (_.has(cfg, name) && (!shouldDisplayOrThrow || shouldDisplayOrThrow(cfg[name]))) {
       if (value && cfg[name] !== value) {
         // Bail if a value is specified but the config does not have that value.
         return

packages/config/src/options.ts

@@ -28,6 +28,7 @@ const BREAKING_OPTION_ERROR_KEY: Readonly<AllCypressErrorNames[]> = [
   'VIDEO_UPLOAD_ON_PASSES_REMOVED',
   'RENAMED_CONFIG_OPTION',
   'EXPERIMENTAL_STUDIO_REMOVED',
+  'CYPRESS_ENV_DEPRECATION',
 ] as const
 
 type ValidationOptions = {
@@ -91,6 +92,10 @@ export interface BreakingOption {
     * Whether to show the error message in the launchpad
     */
   showInLaunchpad?: boolean
+  /**
+   * Whether to display or throw the error message based on the configuration value present.
+   */
+  shouldDisplayOrThrow?: (value: any) => boolean
 }
 
 const isValidConfig = (testingType: string, config: any, opts: ValidationOptions) => {
@@ -177,6 +182,12 @@ const driverConfigOptions: Array<DriverConfigOption> = [
     defaultValue: 4000,
     validation: validate.isNumber,
     overrideLevel: 'any',
+  }, {
+    name: 'allowCypressEnv',
+    defaultValue: true,
+    validation: validate.isBoolean,
+    overrideLevel: 'never',
+    requireRestartOnChange: 'server',
   }, {
     name: 'downloadsFolder',
     defaultValue: 'cypress/downloads',
@@ -643,6 +654,13 @@ export const breakingOptions: Readonly<BreakingOption[]> = [
     errorKey: 'EXPERIMENTAL_STUDIO_REMOVED',
     isWarning: true,
   },
+  {
+    name: 'allowCypressEnv',
+    errorKey: 'CYPRESS_ENV_DEPRECATION',
+    // Display this warning if the value is not present or is explicitly false
+    shouldDisplayOrThrow: (value: any) => value !== false,
+    isWarning: true,
+  },
 ] as const
 
 export const breakingRootOptions: Array<BreakingOption> = [

packages/config/src/project/utils.ts

@@ -413,6 +413,14 @@ export function mergeDefaults (
     additionalIgnorePattern,
   }
 
+  // we want the allowCypressEnv option to be inherited by e2e/component config when evaluating
+  // breaking options in order to correctly hide the error that Cypress.env() is deprecated when allowCypressEnv is false
+  // unless the value is explicitly set
+  config.allowCypressEnv = config.allowCypressEnv ?? true
+  if (!_.has(config[testingType], 'allowCypressEnv') && _.isObject(config[testingType])) {
+    config[testingType].allowCypressEnv = config.allowCypressEnv
+  }
+
   // split out our own app wide env from user env variables
   // and delete envFile
   config.env = parseEnv(config, { ...cliConfig.env, ...options.env }, resolved)