Experimental Features
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.
⚠️ 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 permit during a test run. See Content-Security-Policy for more information. |
experimentalInteractiveRunEvents | false | Allows listening to the before:run, after:run, before:spec, and after:spec events in the setupNodeEvents function during interactive mode. |
experimentalModifyObstructiveThirdPartyCode | false | Whether Cypress searches for and replaces obstructive code in third party .js or .html files. NOTE: Setting this flag removes Subresource Integrity (SRI) from third-party resources. To also remove SRI from first-party resources, use removeSRIAttributes. |
experimentalRunAllSpecs | false | Enables the "Run All Specs" UI feature, allowing the execution of multiple specs sequentially. |
experimentalWebKitSupport | false | Enable experimental support for running tests in WebKit. When set, Cypress detects installs of playwright-webkit and makes them available. See Launching Browsers for more information. |
retries.experimentalStrategy | N/A | Applies a strategy for test retries according to your "flake tolerance"; options are detect-flake-but-always-fail or detect-flake-and-pass-on-threshold. See Experimental Retries for more details. |
retries.experimentalOptions | N/A | Sets retries strategy-specific options like maxRetries, passesRequired, and stopIfAnyPassed. See Experimental Retries for more details. |
Experimental CSP Allow List
Cypress by default strips all CSP headers (Content-Security-Policy and
Content-Security-Policy-Report-Only) from the response before sending it to
the browser. The experimentalCspAllowList option provides more granular
control over which CSP directives Cypress strips from the CSP response headers,
so your application runs under test 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) removes all CSP headers
from the response before Cypress sends it to the browser. Use this option 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 makes Cypress send all CSP headers to the
browser except those that could prevent Cypress from functioning normally.
Cypress always strips the following CSP directives:
| 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 the browser to mark Cypress injections as untrusted. |
When experimentalCspAllowList=true, Cypress also strips the following
directives in addition to the ones listed above, but you can configure Cypress to
send them 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. Cypress then sends the specified CSP directives to
the browser.
The following configuration sends the default-src, script-src, and
script-src-elem directives to the browser:
- cypress.config.js
- cypress.config.ts
const { defineConfig } = require('cypress')
module.exports = defineConfig({
experimentalCspAllowList: ['default-src', 'script-src', 'script-src-elem'],
})
import { defineConfig } from 'cypress'
export default defineConfig({
experimentalCspAllowList: ['default-src', 'script-src', 'script-src-elem'],
})
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 option. Using this option in combination
with the experimentalCspAllowList option can cause a mismatch between the
original hashed directive value, and the modified HTML or JS value.
Experimental Flake Detection Features
Experimental Test Retries
Test retries is a Cypress Flake Detection feature that re-attempts any test that initially fails. The failure may not be a "true" failure, i.e. flaky. The only way to determine this is to retry the test.
Normally, test retries stop on the first passing attempt. And the final test result of any flaky test is always "passing", regardless of how many prior attempts failed. The following experimental settings for retries give you more control over the retries process.
There are two strategies for retries:
detect-flake-and-pass-on-thresholddetect-flake-but-always-fail
The detect-flake-and-pass-on-threshold strategy is most like the current implementation of retries, where failing tests have a "chance" to still pass, but still detect flake. But this new experimental strategy also adds a threshold of passing attempts that the test must reach for a passing final result. And if you want to ensure flaky tests are treated with the same urgency as failing tests, then use the detect-flake-but-always-fail strategy, which assures that Cypress still marks every flaky test as failing.
experimentalStrategy: 'detect-flake-and-pass-on-threshold'
Setting experimentalStrategy: 'detect-flake-and-pass-on-threshold' within retries makes the test result pass only after a set number of passing attempts. You must set two experimentalOptions with this strategy:
maxRetriessets the maximum number of retries that can occur after the first attempt failed.passesRequiredsets the required number of passing attempts for the final test result to be passing. Cannot be greater thanmaxRetries.passesRequiredalso determines how the retries may stop beforemaxRetriesis reached; either if the number of passing attempts so far has met thepassesRequiredcondition or if the number of failing attempts exceeds the difference betweenmaxRetriesandpassesRequired(when it's impossible to achieve the passing result).
- cypress.config.js
- cypress.config.ts
const { defineConfig } = require('cypress')
module.exports = defineConfig({
retries: {
experimentalStrategy: 'detect-flake-and-pass-on-threshold',
experimentalOptions: {
maxRetries: 2,
passesRequired: 2,
},
// you must also explicitly set openMode and runMode to
// either true or false when using experimental retries
openMode: true,
runMode: true,
},
})
import { defineConfig } from 'cypress'
export default defineConfig({
retries: {
experimentalStrategy: 'detect-flake-and-pass-on-threshold',
experimentalOptions: {
maxRetries: 2,
passesRequired: 2,
},
// you must also explicitly set openMode and runMode to
// either true or false when using experimental retries
openMode: true,
runMode: true,
},
})
Examples of the above configuration's results:
Scenario 1:
- Attempt 1: Fail
- Attempt 2: Pass
- Attempt 3: Fail
The retries stop on attempt 3, since maxRetries: 2 is now met and the test's final result is failing and flaky. Only one attempt passed, but two are needed to pass.
Scenario 2:
- Attempt 1: Fail
- Attempt 2: Pass
- Attempt 3: Pass
Retries stop at attempt 3 again, and the test is passing and flaky, since there are now two passing attempts.
Scenario 3:
- Attempt 1: Fail
- Attempt 2: Fail
Retries stop on attempt 2, and the test is failing , because the test can no longer achieve the requisite two passing attempts for a passing result once the 1st retry failed. The test is also not flaky, since there were no passing attempts.
experimentalStrategy: 'detect-flake-but-always-fail'
Setting experimentalStrategy: 'detect-flake-but-always-fail' within retries ensures any test with any failed attempt always ends with a failing final result. You must set two experimentalOptions in this strategy:
maxRetriessets the maximum number of retries that can occur after the first attempt failed.stopIfAnyPassedstops the retries beforemaxRetriesis reached when there is any passing attempt.stopIfAnyPassedcauses retries to exit as soon as Cypress detects any flake (a test that is retrying after a failure only needs to pass once to exhibit flaky behavior). However it may help to see more retry attempts, such as when the failure mode is also non-deterministic and more retries reveal more of these different errors, in which casestopIfAnyPassed: falsemay be desirable.
- cypress.config.js
- cypress.config.ts
const { defineConfig } = require('cypress')
module.exports = defineConfig({
retries: {
experimentalStrategy: 'detect-flake-but-always-fail',
experimentalOptions: {
maxRetries: 2,
stopIfAnyPassed: true,
},
// you must also explicitly set openMode and runMode to
// either true or false when using experimental retries
openMode: true,
runMode: true,
},
})
import { defineConfig } from 'cypress'
export default defineConfig({
retries: {
experimentalStrategy: 'detect-flake-but-always-fail',
experimentalOptions: {
maxRetries: 2,
stopIfAnyPassed: true,
},
// you must also explicitly set openMode and runMode to
// either true or false when using experimental retries
openMode: true,
runMode: true,
},
})
Examples of the above configuration's results:
Scenario 1:
- Attempt 1: Fail
- Attempt 2: Fail
- Attempt 3: Fail
The retries stop on attempt 3, since maxRetries: 2 is now met and the test is failing , but also not flaky.
Scenario 2:
- Attempt 1: Fail
- Attempt 2: Pass
Retries stop on the first retry, due to the passing attempt. The test is failing and flaky. If stopIfAnyPassed was false, then the retries would have proceeded once more.
Note: You can configure experimental retries only at the global level and not per individual test, whereas you can configure non-experimental retries per test. If you configure retries on a per-test basis while using experimental retries globally, that particular test's retries configuration overrides the experimental retries and ignores it.
Also, while using experimental retries, you cannot set numeric values for openMode or runMode at the global level. You can instead set true or false for each.
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
You can specify these experiments inside the e2e configuration object:
| Option | Default | Description |
|---|---|---|
experimentalOriginDependencies | false | Enables support for Cypress.require within cy.origin. |
Component Testing
You can specify these experiments 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. Running in a single tab can improve run mode performance, but can impact spec isolation and reliability on large test suites. |
History
| Version | Changes |
|---|---|
| 16.0.0 | Removed experimentalSourceRewriting. The default regex-based source rewriting is now the only implementation. |
| 16.0.0 | Removed experimentalFastVisibility. The modern visibility algorithm is now the default. |
| 16.0.0 | Removed experimentalMemoryManagement. Memory management graduated to manageBrowserMemory, enabled by default. |
| 15.9.0 | Added component testing support for experimentalRunAllSpecs. |
| 15.8.0 | Added support for experimentalFastVisibility experiment. |
| 15.4.0 | Removed experimentalStudio. Cypress Studio is available as default behavior. |
| 14.0.0 | Removed experimentalFetchPolyfill, experimentalJustInTimeCompile, and experimentalSkipDomainInjection and made it default behavior. |
| 13.14.0 | Added support for configuring the Experimental Just-In-Time (JIT) Compiling for component testing via experimentalJustInTimeCompile. |
| 13.4.0 | Added support for configuring the Experimental Flake Detection strategy via retries.experimentalStrategy and retries.experimentalOptions. |
| 12.6.0 | Removed require/import and added Cypress.require for experimentalOriginDependencies. |
| 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. |