Experiments

Improve this doc

If you’d like to try out what we’re working on in the Test Runner, you can enable beta features for your project by turning on the experimental features you’d like to try.

⚠️ 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 the development.

Configuration

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

Option Default Description
experimentalGetCookiesSameSite false Adds sameSite values to the objects yielded from cy.setCookie(), cy.getCookie(), and cy.getCookies(). This will become the default behavior in a later Cypress version.
experimentalComponentTesting false Enables component testing using framework-specific adaptors. See Component Testing for more detail.
experimentalFetchPolyfill false Automatically replaces window.fetch with a polyfill that Cypress can spy on and stub.
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.
experimentalShadowDomSupport false Enables shadow DOM support. Adds the cy.shadow() command and the includeShadowDom option to some DOM commands. See Shadow DOM for more detail.

When you open a Cypress project, clicking on the Settings tab and clicking into the Experiments panel will display the experimental features that are available and whether they are enabled for your project.

Component Testing

Component testing is a feature that is experimental. You can enable component testing by setting the experimentalComponentTesting configuration to true.

Component Libraries

Component testing can be used with the libraries below. You can find more details on integration with each library in their respective repo.

Component Folder

By default cypress/component is the path for component tests. You can change this path by setting the componentFolder configuration option.

Example cypress.json

{
  "experimentalComponentTesting": true,
  "componentFolder": "cypress/component"
}

Example

An example of a component test may look like the code below. This test would execute in the browser, similar to the full end-to-end test, except with no URL website being visited.

import { mount } from 'cypress-react-unit-test'
import Post from './Post.jsx'

describe('Post skeletons', () => {
  it('loads title after timeout', () => {
    mount(<Post title={title} children={text} />)
    // and then use regular Cypress commands
    // at first, the title and the text are 💀
    cy.get('h1 .react-loading-skeleton').should('have.length', 1)
    cy.get('p .react-loading-skeleton').should('have.length', 5)
  })
})
Example React component test

Shadow DOM

Support for shadow DOM is currently experimental and includes the addition of a new command .shadow() and an includeShadowDom option for some DOM commands. You can enable shadow DOM by setting the experimentalShadowDomSupport configuration to true.

.shadow()

.shadow() will traverse into an element’s shadow root, so that further DOM commands will find elements within that shadow root.

includeShadowDom

Enabling the includeShadowDom option allows using existing commands to query the DOM, finding elements within the shadow DOM that would normally not be found due to the shadow DOM’s boundary hiding them. It is supported by the following commands:

Examples

Given the following DOM:

<div class="container">
  <my-component>
    #shadow-root
      <button class="my-button">Click me</button>
  </my-component>
</div>

You can query for the button in two ways:

// with .shadow()
cy
.get('my-component')
.shadow()
.find('.my-button')
.click()

// - or -

// with { includeShadowDom: true }
cy
.get('my-component')
.find('.my-button', { includeShadowDom: true })
.click()

Cross-boundary selectors

Note that cross-boundary selectors are not supported. This is best illustrated with an example (using the html above):

// ❗️INVALID CODE - WILL NOT WORK
cy.get('.container .my-button', { includeShadowDom: true })

In the selector .container .my-button, the first part (.container) exists in the light DOM and the second part (.my-button) exists in the shadow DOM. This will not find the button element. Instead, you can use one of the methods in the above examples.

History

Version Changes
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.