Add shadow dom experimental flag

source/guides/references/experiments.md

@@ -17,6 +17,7 @@ Option | Default | Description
 `experimentalGetCookiesSameSite` | `false` | If `true`, Cypress will add `sameSite` values to the objects yielded from {% url "`cy.setCookie()`" setcookie %}, {% url "`cy.getCookie()`" getcookie %}, and {% url "`cy.getCookies()`" getcookies %}. This will become the default behavior in Cypress 5.0.
 `experimentalComponentTesting` | `false` | When set to `true`, Cypress allows you to execute component tests using framework-specific adaptors. By default  `cypress/component` is the path for component tests. You can change this setting by setting the `componentFolder` configuration option. For more details see the {% url "cypress-react-unit-test" https://github.com/bahmutov/cypress-react-unit-test %} and {% url "cypress-vue-unit-test" https://github.com/bahmutov/cypress-vue-unit-test %} repos.
 `experimentalSourceRewriting` | `false` | Enables AST-based JS/HTML rewriting. This may fix issues caused by the existing regex-based JS/HTML replacement algorithm. See {% issue 5273 %} for details.
+`experimentalShadowDomSupport` | `false` | Enables shadow DOM support. Adds the `cy.shadow()` command and the `includeShadowDom` option to some DOM commands.
 
 # Component Testing
 
@@ -57,7 +58,66 @@ Code coverage | ✅ / maybe | ✅
 
 \* Most common libraries: React Testing Library, Enzyme, Vue Testing Library, Vue Test Utils
 
+# 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.
+
+## .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:
+
+- {% url `cy.get()` get %}
+- {% url `.find()` find %}
+
+## Examples
+
+Given the following DOM:
+
+```html
+<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:
+
+```javascript
+// 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):
+
+```javascript
+// 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 %}
+{% url "4.8.0" changelog#4-8-0 %} | Added support for `experimentalShadowDomSupport`.
 {% url "4.6.0" changelog#4-6-0 %} | Added support for `experimentalSourceRewriting`.
 {% url "4.5.0" changelog#4-5-0 %} | Added support for `experimentalComponentTesting`.
 {% url "4.3.0" changelog#4-3-0 %} | Added support for `experimentalGetCookiesSameSite`.