add Shadow DOM / LitElement recipe (#501)

43081j · chrisbreiding · bahmutov · web-flow · commit b6b95df0c3f6 · 2020-06-08T17:28:07.000-04:00
Co-authored-by: Chris Breiding &lt;chrisbreiding@gmail.com&gt;
Co-authored-by: Gleb Bahmutov &lt;gleb.bahmutov@gmail.com&gt;
diff --git a/README.md b/README.md
@@ -30,6 +30,7 @@ Recipe | Description
 [Evaluate performance metrics](./examples/testing-dom__performance-metrics) | Utilize Cypress to monitor a website
 [Root style](./examples/testing-dom__root-style) | Trigger input color change that modifies CSS variable
 [Select widgets](./examples/testing-dom__select2) | Working with `<select>` elements and [Select2](https://select2.org/) widgets
+[Lit Elements](./examples/testing-dom__lit-element) | Testing Lit Elements with Shadow DOM
 
 ## Logging in recipes
 
diff --git a/circle.yml b/circle.yml
@@ -237,6 +237,8 @@ jobs:
     <<: *defaults
   testing-dom__hover-hidden-elements:
     <<: *defaults
+  testing-dom__lit-element:
+    <<: *defaults
   testing-dom__tab-handling-links:
     <<: *defaults
   testing-dom__wait-for-resource:
@@ -428,6 +430,9 @@ all_jobs: &all_jobs
   - testing-dom__hover-hidden-elements:
       requires:
         - build
+  - testing-dom__lit-element:
+      requires:
+        - build
   - testing-dom__tab-handling-links:
       requires:
         - build
@@ -537,6 +542,7 @@ all_jobs: &all_jobs
         - testing-dom__drag-drop
         - testing-dom__form-interactions
         - testing-dom__hover-hidden-elements
+        - testing-dom__lit-element
         - testing-dom__tab-handling-links
         - testing-dom__wait-for-resource
         - testing-dom__csv-table
diff --git a/examples/testing-dom__lit-element/.eslintrc.json b/examples/testing-dom__lit-element/.eslintrc.json
@@ -0,0 +1,11 @@
+{
+  "plugins": [
+    "@cypress/dev"
+  ],
+  "extends": [
+    "plugin:@cypress/dev/general"
+  ],
+  "env": {
+    "browser": true
+  }
+}
diff --git a/examples/testing-dom__lit-element/README.md b/examples/testing-dom__lit-element/README.md
@@ -0,0 +1,4 @@
+# lit-element
+> Testing page with lit-element components that use Shadow DOM
+
+- Test simple shadow DOM assertions in [lit-elements](https://lit-element.polymer-project.org/)
diff --git a/examples/testing-dom__lit-element/cypress.json b/examples/testing-dom__lit-element/cypress.json
@@ -0,0 +1,6 @@
+{
+  "pluginsFile": false,
+  "supportFile": false,
+  "fixturesFolder": false,
+  "experimentalShadowDomSupport": true
+}
diff --git a/examples/testing-dom__lit-element/cypress/.eslintrc.json b/examples/testing-dom__lit-element/cypress/.eslintrc.json
@@ -0,0 +1,8 @@
+{
+  "plugins": [
+    "@cypress/dev"
+  ],
+  "extends": [
+    "plugin:@cypress/dev/tests"
+  ]
+}
diff --git a/examples/testing-dom__lit-element/cypress/integration/shadow-tests.ts b/examples/testing-dom__lit-element/cypress/integration/shadow-tests.ts
@@ -0,0 +1,42 @@
+/// <reference types="cypress" />
+
+describe('element-one', () => {
+  beforeEach(() => {
+    cy.visit('/index.html')
+  })
+
+  it('renders a button', () => {
+    cy
+    .get('element-one')
+    .shadow()
+    .find('button')
+    .should('exist')
+  })
+
+  it('renders a message on button click', () => {
+    cy
+    .get('element-one')
+    .shadow()
+    .find('button')
+    .click()
+
+    cy
+    .get('element-one')
+    .shadow()
+    .find('p')
+    .then((node) => {
+      expect(node.text()).to.equal('I am element 1!')
+    })
+  })
+})
+
+describe('element-two', () => {
+  it('renders a default slot', () => {
+    cy
+    .get('element-two')
+    .find('.container > slot', { includeShadowDom: true })
+    .then(($slot) => {
+      expect($slot[0].assignedElements()[0]).to.equal(cy.$$('element-two > p')[0])
+    })
+  })
+})
diff --git a/examples/testing-dom__lit-element/elements.js b/examples/testing-dom__lit-element/elements.js
@@ -0,0 +1,32 @@
+import { LitElement, html } from 'https://unpkg.com/lit-element/lit-element.js?module'
+
+window.customElements.define('element-one', class extends LitElement {
+  static get properties () {
+    return {
+      _message: {
+        type: String,
+      },
+    }
+  }
+
+  _onClick () {
+    this._message = 'I am element 1!'
+  }
+
+  render () {
+    return html`
+      <p>${this._message || ''}</p>
+      <button @click=${this._onClick}>Click me</button>
+    `
+  }
+})
+
+window.customElements.define('element-two', class extends LitElement {
+  render () {
+    return html`
+      <div class="container">
+        <slot></slot>
+      </div>
+    `
+  }
+})
diff --git a/examples/testing-dom__lit-element/index.html b/examples/testing-dom__lit-element/index.html
@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <script type="module" src="./elements.js"></script>
+  </head>
+  <body>
+    <element-one></element-one>
+    <div class="container-2">
+      <element-two>
+        <p>Testing 123</p>
+      </element-two>
+    </div>
+  </body>
+</html>
diff --git a/examples/testing-dom__lit-element/package.json b/examples/testing-dom__lit-element/package.json
@@ -0,0 +1,13 @@
+{
+  "name": "unit-test-lit-element",
+  "version": "1.0.0",
+  "description": "Load and unit test lit-element projects",
+  "scripts": {
+    "cypress:open": "../../node_modules/.bin/cypress open",
+    "cypress:run": "../../node_modules/.bin/cypress run",
+    "start": "echo there is no web server to start in this project",
+    "test:ci": "npm run cypress:run",
+    "test:ci:firefox": "npm run cypress:run -- --browser firefox",
+    "test:ci:windows": "bin-up cypress run"
+  }
+}
diff --git a/examples/testing-dom__shadow-dom/README.md b/examples/testing-dom__shadow-dom/README.md
@@ -1,6 +1,46 @@
-# Testing shadow DOM
+# Shadow DOM
 
-Currently it is not yet supported out of the box, so you can use any of the custom commands below:
+Cypress natively supports traversing shadow DOM trees, both from a component testing point of view, and an application testing point of view.
 
-- [cypress-shadow-dom](https://github.com/abramenal/cypress-shadow-dom)
-- [cypress-daywalker](https://github.com/JaySunSyn/cypress-daywalker)
+## Explicitly traversing shadow DOM
+
+If you are testing components, or you simply prefer writing explicit selectors, you may traverse into any given shadow DOM tree like so:
+
+```javascript
+cy
+.get('my-element')
+.shadow()
+.find('button')
+.click()
+
+/*
+  <my-element>
+    #shadow-root
+      <button>Click me!</button>
+  </my-element>
+*/
+```
+
+## Ignoring shadow boundaries
+
+Alternatively, you may use the `includeShadowDom: true` option when traversing the DOM to look beyond each shadow root's boundary:
+
+```javascript
+cy
+.get('button', { includeShadowDom: true })
+.click()
+
+/*
+  <my-element>
+    #shadow-root
+      <button>Click me!</button>
+  </my-element>
+*/
+```
+
+This effectively treats the DOM as if shadow boundaries do not exist and will traverse into them like any other elements.
+
+The following commands support the `includeShadowDom` option:
+
+* `cy.get()`
+* `cy.find()`
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -55,6 +55,7 @@
     "jquery": "3.4.0",
     "json-server": "0.14.0",
     "jsonwebtoken": "8.5.1",
+    "lit-element": "2.3.1",
     "lodash": "4.17.13",
     "minimist": "1.2.3",
     "morgan": "1.9.1",
