feat: add Cypress.expose() API

Author: AtofStryker

.circleci/src/pipeline/@pipeline.yml

@@ -127,7 +127,7 @@ commands:
             if [[ "<< pipeline.parameters.force-persist-artifacts >>" == "true" ]]; then
               echo 'export SHOULD_PERSIST_ARTIFACTS=true' >> "$BASH_ENV"
             else
-              echo 'if ! [[ "$CIRCLE_BRANCH" != "develop" && "$CIRCLE_BRANCH" != "release/"* && "$CIRCLE_BRANCH" != "feat/deprecate_cypress_env_feature_branch" ]]; then
+              echo 'if ! [[ "$CIRCLE_BRANCH" != "develop" && "$CIRCLE_BRANCH" != "release/"* && "$CIRCLE_BRANCH" != "feat/deprecate_cypress_env_feature_branch" && "$CIRCLE_BRANCH" != "feat/add_cypress_expose" ]]; then
                   export SHOULD_PERSIST_ARTIFACTS=true
               fi' >> "$BASH_ENV"
             fi

.circleci/src/pipeline/workflows/@main.yml

@@ -5,6 +5,7 @@ linux-x64:
       # use the following branch as well to ensure that v8 snapshot cache updates are fully tested
       - equal: [ 'update-v8-snapshot-cache-on-develop', << pipeline.git.branch >> ]
       - equal: [ 'feat/deprecate_cypress_env_feature_branch', << pipeline.git.branch >> ]
+      - equal: [ 'feat/add_cypress_expose', << pipeline.git.branch >> ]
       - matches:
           pattern: /^release\/\d+\.\d+\.\d+$/
           value: << pipeline.git.branch >>

cli/CHANGELOG.md

@@ -11,6 +11,7 @@ _Released 01/27/2026 (PENDING)_
 
 - 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).
+- Introduced the new `Cypress.expose()` API, intended for use of public configuration of non-sensitive values. Addressed in [#33238](https://github.com/cypress-io/cypress/pull/33238).
 
 **Misc:**
 

cli/lib/cli.ts

@@ -117,6 +117,7 @@ const descriptions: any = {
   dev: 'runs cypress in development and bypasses binary check',
   e2e: 'runs end to end tests',
   env: 'sets environment variables. separate multiple values with a comma. overrides any value in cypress.config.{js,ts,mjs,cjs} or cypress.env.json',
+  expose: 'sets exposed public configuration variables. separate multiple values with a comma. overrides any value in cypress.config.{js,ts,mjs,cjs}',
   exit: 'keep the browser open after tests finish',
   forceInstall: 'force install the Cypress binary',
   global: 'force Cypress into global mode as if it were globally installed',
@@ -252,6 +253,7 @@ const addCypressRunCommand = (program: any): any => {
   .option('-C, --config-file <config-file>', text('configFile'))
   .option('--e2e', text('e2e'))
   .option('-e, --env <env>', text('env'))
+  .option('-x, --expose <expose>', text('expose'))
   .option('--group <name>', text('group'))
   .option('-k, --key <record-key>', text('key'))
   .option('--headed', text('headed'))
@@ -284,6 +286,7 @@ const addCypressOpenCommand = (program: any): any => {
   .option('-d, --detached [bool]', text('detached'), coerceFalse)
   .option('--e2e', text('e2e'))
   .option('-e, --env <env>', text('env'))
+  .option('-x, --expose <expose>', text('expose'))
   .option('--global', text('global'))
   .option('-p, --port <port>', text('port'))
   .option('-P, --project <project-path>', text('project'))

cli/lib/exec/open.ts

@@ -46,6 +46,10 @@ const processOpenOptions = (options: any = {}): string[] => {
     args.push('--env', options.env)
   }
 
+  if (options.expose) {
+    args.push('--expose', options.expose)
+  }
+
   if (options.port) {
     args.push('--port', options.port)
   }

cli/lib/exec/run.ts

@@ -71,6 +71,10 @@ const processRunOptions = (options: any = {}): string[] => {
     args.push('--env', options.env)
   }
 
+  if (options.expose) {
+    args.push('--expose', options.expose)
+  }
+
   if (options.exit === false) {
     args.push('--no-exit')
   }

cli/lib/util.ts

@@ -190,6 +190,7 @@ const parseOpts = (opts: any): any => {
     'e2e',
     'exit',
     'env',
+    'expose',
     'force',
     'global',
     'group',

cli/test/lib/__snapshots__/cli.spec.ts.snap

@@ -388,6 +388,10 @@ exports[`cli > unknown option > shows help 1`] = `
                                      multiple values with a comma. overrides any
                                      value in cypress.config.{js,ts,mjs,cjs} or
                                      cypress.env.json
+    -x, --expose <expose>            sets exposed public configuration variables.
+                                     separate multiple values with a comma.
+                                     overrides any value in
+                                     cypress.config.{js,ts,mjs,cjs}
     --global                         force Cypress into global mode as if it were
                                      globally installed
     -p, --port <port>                runs Cypress on a specific port. overrides
@@ -530,6 +534,7 @@ exports[`cli > unknown option > shows help for run command 1`] = `
     -C, --config-file <config-file>                             path to script file where configuration values are set. defaults to "cypress.config.{js,ts,mjs,cjs}".
     --e2e                                                       runs end to end tests
     -e, --env <env>                                             sets environment variables. separate multiple values with a comma. overrides any value in cypress.config.{js,ts,mjs,cjs} or cypress.env.json
+    -x, --expose <expose>                                       sets exposed public configuration variables. separate multiple values with a comma. overrides any value in cypress.config.{js,ts,mjs,cjs}
     --group <name>                                              a named group for recorded runs in Cypress Cloud
     -k, --key <record-key>                                      your secret Record Key. you can omit this if you set a CYPRESS_RECORD_KEY environment variable.
     --headed                                                    displays the browser instead of running headlessly

cli/types/cypress.d.ts

@@ -512,7 +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.
+     * @deprecated Use {@linkcode Chainable.env cy.env()} or {@linkcode expose Cypress.expose()} instead.
      */
     env(): ObjectLike
     /**
@@ -522,7 +522,7 @@ declare namespace Cypress {
      *    // cypress.config.js
      *    { "env": { "foo": "bar" } }
      *    Cypress.env("foo") // => bar
-     * @deprecated Use {@linkcode Chainable.env cy.env()} instead.
+     * @deprecated Use {@linkcode Chainable.env cy.env()} or {@linkcode expose Cypress.expose()} instead.
      */
     env(key: string): any
     /**
@@ -531,17 +531,48 @@ 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.
+     * @deprecated Use {@linkcode Chainable.env cy.env()} or {@linkcode expose Cypress.expose()} 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.
+     * @deprecated Use {@linkcode Chainable.env cy.env()} or {@linkcode expose Cypress.expose()} instead.
      */
     env(object: ObjectLike): void
+    /**
+     * Returns all exposed public configuration variables set with --expose in the CLI or in "expose" object in "cypress.config.{js,ts,mjs,cjs}"
+     *
+     * @see https://on.cypress.io/expose
+     */
+
+    expose(): ObjectLike
+    /**
+     * Returns specific exposed public configuration variable or undefined
+     * @see https://on.cypress.io/expose
+     * @example
+     *    // cypress.config.js
+     *    { "expose": { "foo": "bar" } }
+     *    Cypress.expose("foo") // => bar
+     */
+    expose(key: string): any
+    /**
+     * Set value for an exposed public configuration variable.
+     * Any value you change will be permanently changed for the remainder of your tests.
+     * @see https://on.cypress.io/expose
+     * @example
+     *    Cypress.expose("host", "http://server.dev.local")
+     */
+    expose(key: string, value: any): void
+    /**
+     * Set values for multiple exposed public configuration variables at once. Values are merged with existing values.
+     * @see https://on.cypress.io/expose
+     * @example
+     *    Cypress.expose({ host: "http://server.dev.local", foo: "foo" })
+     */
+    expose(object: ObjectLike): void
 
     /**
      * @returns the number of test retries currently enabled for the run
@@ -2974,6 +3005,11 @@ declare namespace Cypress {
      * @default {}
      */
     env: { [key: string]: any }
+    /**
+     * Any values to be set as [exposed public configuration variables](https://on.cypress.io/expose).
+     * @default {}
+     */
+    expose: { [key: string]: any }
     /**
      * A String or Array of glob patterns used to ignore test files that would otherwise be shown in your list of tests. Cypress uses minimatch with the options: {dot: true, matchBase: true}. We suggest using a tool to test what files would match.
      * @default "*.hot-update.js"

cli/types/tests/cypress-tests.ts

@@ -55,6 +55,16 @@ namespace CypressEnvTests {
   })
 }
 
+namespace CypressExposeTests {
+  // Just making sure these are valid - no real type safety
+  Cypress.expose('foo')
+  Cypress.expose('foo', 'bar')
+  Cypress.expose().foo
+  Cypress.expose({
+    foo: 'bar',
+  })
+}
+
 namespace CypressStopTests {
   Cypress.stop() // $ExpectType void
   Cypress.stop('foo') // $ExpectError