Experiments

If you'd like to try out what we're working on in Cypress, you can enable specific experimental features for your project using the Cypress configuration options described below.

caution

⚠️ The experimental features might change or ultimately be removed without making it into the core product. Our primary goal for experiments is to collect real-world feedback during their development. For more information, see the documentation for all Cypress Release Stages.

Configuration

You can pass the Cypress configuration options below to enable or disable experiments. See our Configuration Guide on how to pass configuration to Cypress.

Option	Default	Description
experimentalCspAllowList	false	Indicates the Content-Security-Policy directives to be permitted during a test run. See Content-Security-Policy for more information.
experimentalFetchPolyfill	false	Automatically replaces window.fetch with a polyfill that Cypress can spy on and stub. Note: experimentalFetchPolyfill has been deprecated in Cypress 6.0.0 and will be removed in a future release. Consider using cy.intercept() to intercept fetch requests instead.
experimentalInteractiveRunEvents	false	Allows listening to the before:run, after:run, before:spec, and after:spec events in the setupNodeEvents function during interactive mode.
experimentalMemoryManagement	false	Enables support for improved memory management within Chromium-based browsers.
experimentalModifyObstructiveThirdPartyCode	false	Whether Cypress will search for and replace obstructive code in third party .js or .html files. NOTE: Setting this flag removes Subresource Integrity (SRI).
experimentalSourceRewriting	false	Enables AST-based JS/HTML rewriting. This may fix issues caused by the existing regex-based JS/HTML replacement algorithm. See #5273 for details.
experimentalWebKitSupport	false	Enable experimental support for running tests in WebKit. When set, installs of playwright-webkit will be detected and available in Cypress. See Launching Browsers for more information.

Experimental CSP Allow List

Cypress by default strips all CSP headers (Content-Security-Policy and Content-Security-Policy-Report-Only) from the response before it is sent to the browser. The experimentalCspAllowList option allows for more granular control over which CSP directives are stripped from the CSP response headers, allowing you to test your application with CSP enabled. Valid values for this option are false (the default), true, or an array of CSP directive names.

Value	Example
false (default)	experimentalCspAllowList=false
true	experimentalCspAllowList=true
<CspDirectives>[]	experimentalCspAllowList=["default-src","script-src"]

Strip All CSP Headers

The value experimentalCspAllowList=false (default) will remove all CSP headers from the response before it is sent to the browser. This option should be used if you do not depend on CSP for any tests in your application.

Strip Minimum CSP Directives

If you need to test your application with CSP enabled, setting the experimentalCspAllowList option will allow all CSP headers to be sent to the browser except those that could prevent Cypress from functioning normally.

The following CSP directives will always be stripped:

Stripped Directive	Allowable	Reason
frame-ancestors	No	Prevents Cypress from loading a test application into an iframe.
navigate-to	No	Affects Cypress' ability to navigate to different URLs.
require-trusted-types-for	No	Might prevent Cypress from rewriting the DOM.
sandbox	No	Can restrict access to script and iframe functionality.
trusted-types	No	Could cause Cypress injections to be marked as untrusted.

When experimentalCspAllowList=true the following directives are also stripped in addition to the ones listed above, but can be configured to be allowed to be sent to the browser:

Stripped Directive	Allowable	Reason
child-src	Yes	Could prevent iframes from loading in combination with other Cypress options.
default-src	Yes	Conditionally prevents Cypress from loading scripts and running.
frame-src	Yes	Could prevent iframes from loading in combination with other Cypress options.
form-action	Yes	Can prevent Cypress from monitoring form events.
script-src	Yes	Conditionally prevents Cypress from loading scripts and running.
script-src-elem	Yes	Conditionally prevents Cypress from loading scripts and running.

Allow Specific CSP Directives

Set the experimentalCspAllowList option to an array of directive names marked as "Allowable" from the list above. This will allow the specified CSP directives to be sent to the browser.

The following configuration would allow the default-src, script-src, and script-src-elem directives to be sent to the browser:

cypress.config.js

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  experimentalCspAllowList: ['default-src', 'script-src', 'script-src-elem'],
})

cypress.config.ts

import { defineConfig } from 'cypress'

export default defineConfig({
  experimentalCspAllowList: ['default-src', 'script-src', 'script-src-elem'],
})

caution

Defining experimentalCspAllowList may cause Cypress to be unable to run tests against your application. If you experience issues, reduce the directives specified in your allow list to identify which directive is causing issues.

There is a known issue when using certain directives containing hash algorithm values and the modifyObstructiveCode and/or experimentalSourceRewriting options. Using these options in combination with the experimentalCspAllowList option can cause a mismatch between the original hashed directive value, and the modified HTML or JS value.

Testing Type-Specific Experiments

You can provide configuration options for either E2E or Component Testing by creating e2e and component objects inside your Cypress configuration.

End-to-End Testing

These experiments are available to be specified inside the e2e configuration object:

Option	Default	Description
experimentalStudio	false	Generate and save commands directly to your test suite by interacting with your app as an end user would.
experimentalRunAllSpecs	false	Enables the "Run All Specs" UI feature, allowing the execution of multiple specs sequentially.
experimentalOriginDependencies	false	Enables support for require/import within cy.origin.
experimentalSkipDomainInjection	null	Removes injecting document.domain into text/html pages for any sites that match the provided patterns.

Experimental Skip Domain Injection

Under the hood, Cypress injects document.domain into your test application to lessen the burden of navigation. This is well described in our Cross Origin Testing guide. However, some sites have compatibility issues with this feature.

The experimentalSkipDomainInjection option disables injecting document.domain inside Cypress. When enabled, all cross-origin/subdomain navigation must use cy.origin(), which may make tests a bit more verbose. We only recommend including your site pattern if you are having issues running Cypress out of the box and suspect setting document.domain is interfering with your site's ability to render properly.

Before enabling, verify your application is not implementing frame busting techniques, which you can mitigate with the modifyObstructiveCode and experimentalModifyObstructiveThirdPartyCode flags.

At this point in time, we are aware of the following sites that require the experimentalSkipDomainInjection option to be set to be tested properly:

• Google
• Salesforce

This flag can be enabled by passing an array of origin URLs or minimatch glob patterns:

cypress.config.js

const { defineConfig } = require('cypress')

module.exports = defineConfig({
  e2e: {
    experimentalSkipDomainInjection: [
      '*.salesforce.com',
      '*.force.com',
      '*.google.com',
    ],
  },
})

cypress.config.ts

import { defineConfig } from 'cypress'

export default defineConfig({
  e2e: {
    experimentalSkipDomainInjection: [
      '*.salesforce.com',
      '*.force.com',
      '*.google.com',
    ],
  },
})

If using other Salesforce domains, such as enhanced domains, you will need to add the correct matching glob pattern.

Component Testing

These experiments are available to be specified inside the component configuration object:

Option	Default	Description
experimentalSingleTabRunMode	false	Run all specs in a single tab, instead of creating a new tab per spec. This can improve run mode performance, but can impact spec isolation and reliability on large test suites.

History

Version	Changes
12.4.0	Added experimentalSkipDomainInjection and experimentalMemoryManagement.
12.0.0	Removed experimentalSessionAndOrigin and made it the default behavior. Added experimentalOriginDependencies.
11.2.0	Added experimentalRunAllSpecs.
10.8.0	Added experimentalWebKitSupport.
10.6.0	Added support for experimentalSingleTabRunMode.
10.4.0	Added support for experimentalModifyObstructiveThirdPartyCode.
9.6.0	Added support for experimentalSessionAndOrigin and removed experimentalSessionSupport.
8.2.0	Added support for experimentalSessionSupport.
7.1.0	Added support for experimentalInteractiveRunEvents.
7.0.0	Removed experimentalComponentTesting and made it the default behavior.
6.7.0	Removed experimentalRunEvents and made it the default behavior.
6.3.0	Added support for experimentalStudio.
6.2.0	Added support for experimentalRunEvents.
6.0.0	Removed experimentalNetworkStubbing and made it the default behavior when using cy.intercept().
6.0.0	Deprecated experimentalFetchPolyfill.
5.2.0	Removed experimentalShadowDomSupport and made it the default behavior.
5.1.0	Added support for experimentalNetworkStubbing.
5.0.0	Removed experimentalGetCookiesSameSite and made it the default behavior.
4.9.0	Added support for experimentalFetchPolyfill.
4.8.0	Added support for experimentalShadowDomSupport.
4.6.0	Added support for experimentalSourceRewriting.
4.5.0	Added support for experimentalComponentTesting.
4.3.0	Added support for experimentalGetCookiesSameSite.