npm - @percy/dom - Versions diffs - 1.17.0 → 1.19.1-alpha.0 - Mend

@percy/dom 1.17.0 → 1.19.1-alpha.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3) hide show

package/README.md CHANGED Viewed

@@ -71,7 +71,44 @@ Videos without a `poster` attribute will have the current frame of the video
 serialized into an image and set as the `poster` attribute automatically. This is
 to ensure videos have a stable image to display when screenshots are captured.
+### Shadow DOM
+Shadow dom  `#shadow-root (open)` is serialized into declarative shadow DOM (`<template shadowroot="open">`) form
+Shadow host element is annotated with special identifier attribute named `data-percy-shadow-host`. This identifier
+attribute may be used when passing `domTransformation`.
 ### Other elements
 _All other elements are not serialized._ The resulting cloned document is passed to any provided
 `domTransformation` option before the serialize function returns a DOM string.
+## Examples
+1. perform DOM transformations on serialized DOM
+this example contains scenario of nested shadow DOMs
+```js
+import serializeDOM from '@percy/dom';
+const domSnapshot = serializeDOM({
+    domTransformation: (documentElement) => {
+      function insertHelloHeader(root) {
+        h1 = document.createElement('h1');
+        h1.innerText = 'Inserted using dom transformations';
+        root.append(h1);
+        root.querySelectorAll('[data-percy-shadow-host]')
+          .forEach(
+            shadowHost => {
+              if (shadowHost?.shadowRoot)
+                insertHelloHeader(shadowHost.shadowRoot)
+            });
+      }
+      insertHelloHeader(documentElement);
+    }
+  });
+```

package/dist/bundle.js CHANGED Viewed

@@ -6,21 +6,6 @@
     process.env = process.env || {};
     process.env.__PERCY_BROWSERIFIED__ = true;
-    // Returns a mostly random uid.
-    function uid() {
-      return `_${Math.random().toString(36).substr(2, 9)}`;
-    }
-    // Marks elements that are to be serialized later with a data attribute.
-    function prepareDOM(dom) {
-      for (let elem of dom.querySelectorAll('input, textarea, select, iframe, canvas, video, style')) {
-        if (!elem.getAttribute('data-percy-element-id')) {
-          elem.setAttribute('data-percy-element-id', uid());
-        }
-      }
-      return dom;
-    }
     // Translates JavaScript properties of inputs into DOM attributes.
     function serializeInputElements(_ref) {
       let {
@@ -54,6 +39,18 @@
             cloneEl.setAttribute('value', elem.value);
         }
       }
+      // find inputs inside shadow host and recursively serialize them.
+      for (let shadowHost of dom.querySelectorAll('[data-percy-shadow-host]')) {
+        let percyElementId = shadowHost.getAttribute('data-percy-element-id');
+        let cloneShadowHost = clone.querySelector(`[data-percy-element-id="${percyElementId}"]`);
+        if (shadowHost.shadowRoot && cloneShadowHost.shadowRoot) {
+          serializeInputElements({
+            dom: shadowHost.shadowRoot,
+            clone: cloneShadowHost.shadowRoot
+          });
+        }
+      }
     }
     // Adds a `<base>` element to the serialized iframe's `<head>`. This is necessary when
@@ -75,13 +72,14 @@
         enableJavaScript
       } = _ref;
       for (let frame of dom.querySelectorAll('iframe')) {
+        var _clone$head;
         let percyElementId = frame.getAttribute('data-percy-element-id');
         let cloneEl = clone.querySelector(`[data-percy-element-id="${percyElementId}"]`);
         let builtWithJs = !frame.srcdoc && (!frame.src || frame.src.split(':')[0] === 'javascript');
         // delete frames within the head since they usually break pages when
         // rerendered and do not effect the visuals of a page
-        if (clone.head.contains(cloneEl)) {
+        if ((_clone$head = clone.head) !== null && _clone$head !== void 0 && _clone$head.contains(cloneEl)) {
           cloneEl.remove();
           // if the frame document is accessible and not empty, we can serialize it
@@ -114,6 +112,21 @@
           cloneEl.remove();
         }
       }
+      // find iframes inside shadow host and recursively serialize them.
+      for (let shadowHost of dom.querySelectorAll('[data-percy-shadow-host]')) {
+        let percyElementId = shadowHost.getAttribute('data-percy-element-id');
+        let cloneShadowHost = clone.querySelector(`[data-percy-element-id="${percyElementId}"]`);
+        if (shadowHost.shadowRoot && cloneShadowHost.shadowRoot) {
+          serializeFrames({
+            dom: shadowHost.shadowRoot,
+            clone: cloneShadowHost.shadowRoot,
+            warnings,
+            resources,
+            enableJavaScript
+          });
+        }
+      }
     }
     // Returns true if a stylesheet is a CSSOM-based stylesheet.
@@ -137,14 +150,20 @@
     function serializeCSSOM(_ref) {
       let {
         dom,
-        clone
+        clone,
+        warnings
       } = _ref;
       for (let styleSheet of dom.styleSheets) {
         if (isCSSOM(styleSheet)) {
           let styleId = styleSheet.ownerNode.getAttribute('data-percy-element-id');
+          if (!styleId) {
+            let attributes = Array.from(styleSheet.ownerNode.attributes).map(attr => `${attr.name}: ${attr.value}`);
+            warnings.add(`stylesheet with attributes - [ ${attributes} ] - was not serialized`);
+            continue;
+          }
           let cloneOwnerNode = clone.querySelector(`[data-percy-element-id="${styleId}"]`);
           if (styleSheetsMatch(styleSheet, cloneOwnerNode.sheet)) continue;
-          let style = clone.createElement('style');
+          let style = document.createElement('style');
           style.type = 'text/css';
           style.setAttribute('data-percy-element-id', styleId);
           style.setAttribute('data-percy-cssom-serialized', 'true');
@@ -153,6 +172,18 @@
           cloneOwnerNode.remove();
         }
       }
+      // find stylesheets inside shadow host and recursively serialize them.
+      for (let shadowHost of dom.querySelectorAll('[data-percy-shadow-host]')) {
+        let percyElementId = shadowHost.getAttribute('data-percy-element-id');
+        let cloneShadowHost = clone.querySelector(`[data-percy-element-id="${percyElementId}"]`);
+        if (shadowHost.shadowRoot && cloneShadowHost.shadowRoot) {
+          serializeCSSOM({
+            dom: shadowHost.shadowRoot,
+            clone: cloneShadowHost.shadowRoot
+          });
+        }
+      }
     }
     // Creates a resource object from an element's unique ID and data URL
@@ -197,7 +228,8 @@
         resources.add(resource);
         // create an image element in the cloned dom
-        let img = clone.createElement('img');
+        // TODO: this works, verify if this is fine?
+        let img = document.createElement('img');
         // use a data attribute to avoid making a real request
         img.setAttribute('data-percy-serialized-attribute-src', resource.url);
@@ -217,9 +249,27 @@
         // insert the image into the cloned DOM and remove the cloned canvas element
         let cloneEl = clone.querySelector(`[data-percy-element-id=${percyElementId}]`);
-        cloneEl.parentElement.insertBefore(img, cloneEl);
+        // `parentElement` for elements directly under shadow root is `null` -> Incase of Nested Shadow DOM.
+        if (cloneEl.parentElement) {
+          cloneEl.parentElement.insertBefore(img, cloneEl);
+        } else {
+          clone.insertBefore(img, cloneEl);
+        }
         cloneEl.remove();
       }
+      // find canvas inside shadow host and recursively serialize them.
+      for (let shadowHost of dom.querySelectorAll('[data-percy-shadow-host]')) {
+        let percyElementId = shadowHost.getAttribute('data-percy-element-id');
+        let cloneShadowHost = clone.querySelector(`[data-percy-element-id="${percyElementId}"]`);
+        if (shadowHost.shadowRoot && cloneShadowHost.shadowRoot) {
+          serializeCanvas({
+            dom: shadowHost.shadowRoot,
+            clone: cloneShadowHost.shadowRoot,
+            resources
+          });
+        }
+      }
     }
     // Captures the current frame of videos and sets the poster image
@@ -227,7 +277,8 @@
       let {
         dom,
         clone,
-        resources
+        resources,
+        warnings
       } = _ref;
       for (let video of dom.querySelectorAll('video')) {
         // if the video already has a poster image, no work for us to do
@@ -241,7 +292,9 @@
         canvas.getContext('2d').drawImage(video, 0, 0, width, height);
         try {
           dataUrl = canvas.toDataURL();
-        } catch {}
+        } catch (e) {
+          warnings.add(`data-percy-element-id="${videoId}" : ${e.toString()}`);
+        }
         // if the canvas produces a blank image, skip
         if (!dataUrl || dataUrl === 'data:,') continue;
@@ -253,6 +306,154 @@
         // use a data attribute to avoid making a real request
         cloneEl.setAttribute('data-percy-serialized-attribute-poster', resource.url);
       }
+      // find video inside shadow host and recursively serialize them.
+      for (let shadowHost of dom.querySelectorAll('[data-percy-shadow-host]')) {
+        let percyElementId = shadowHost.getAttribute('data-percy-element-id');
+        let cloneShadowHost = clone.querySelector(`[data-percy-element-id="${percyElementId}"]`);
+        if (shadowHost.shadowRoot && cloneShadowHost.shadowRoot) {
+          serializeVideos({
+            dom: shadowHost.shadowRoot,
+            clone: cloneShadowHost.shadowRoot,
+            resources,
+            warnings
+          });
+        }
+      }
+    }
+    // Returns a mostly random uid.
+    function uid() {
+      return `_${Math.random().toString(36).substr(2, 9)}`;
+    }
+    function markElement(domElement) {
+      var _domElement$tagName;
+      // Mark elements that are to be serialized later with a data attribute.
+      if (['input', 'textarea', 'select', 'iframe', 'canvas', 'video', 'style'].includes((_domElement$tagName = domElement.tagName) === null || _domElement$tagName === void 0 ? void 0 : _domElement$tagName.toLowerCase())) {
+        if (!domElement.getAttribute('data-percy-element-id')) {
+          domElement.setAttribute('data-percy-element-id', uid());
+        }
+      }
+      // add special marker for shadow host
+      if (domElement.shadowRoot) {
+        if (!domElement.getAttribute('data-percy-shadow-host')) {
+          domElement.setAttribute('data-percy-shadow-host', '');
+        }
+        if (!domElement.getAttribute('data-percy-element-id')) {
+          domElement.setAttribute('data-percy-element-id', uid());
+        }
+      }
+    }
+    /**
+     * Custom deep clone function that replaces Percy's current clone behavior.
+     * This enables us to capture shadow DOM in snapshots. It takes advantage of `attachShadow`'s mode option set to open
+     * https://developer.mozilla.org/en-US/docs/Web/API/Element/attachShadow#parameters
+     */
+    // returns document fragment
+    const deepClone = host => {
+      // clones shadow DOM and light DOM for a given node
+      let cloneNode = (node, parent) => {
+        let walkTree = (nextn, nextp) => {
+          while (nextn) {
+            cloneNode(nextn, nextp);
+            nextn = nextn.nextSibling;
+          }
+        };
+        // mark the node before cloning
+        markElement(node);
+        let clone = node.cloneNode();
+        parent.appendChild(clone);
+        // clone shadow DOM
+        if (node.shadowRoot) {
+          // create shadowRoot
+          if (clone.shadowRoot) {
+            // it may be set up in a custom element's constructor
+            clone.shadowRoot.innerHTML = '';
+          } else {
+            clone.attachShadow({
+              mode: 'open'
+            });
+          }
+          // clone stylesheets in shadowRoot
+          for (let sheet of node.shadowRoot.adoptedStyleSheets) {
+            let cssText = Array.from(sheet.rules).map(rule => rule.cssText).join('\n');
+            let style = document.createElement('style');
+            style.appendChild(document.createTextNode(cssText));
+            clone.shadowRoot.prepend(style);
+          }
+          // clone dom elements
+          walkTree(node.shadowRoot.firstChild, clone.shadowRoot);
+        }
+        // clone light DOM
+        walkTree(node.firstChild, clone);
+      };
+      let fragment = document.createDocumentFragment();
+      cloneNode(host, fragment);
+      return fragment;
+    };
+    /**
+     * Deep clone a document while also preserving shadow roots and converting adoptedStylesheets to <style> tags.
+     */
+    const cloneNodeAndShadow = doc => {
+      let mockDocumentFragment = deepClone(doc.documentElement);
+      // convert document fragment to document object
+      let cloneDocument = doc.cloneNode();
+      // dissolve document fragment in clone document
+      cloneDocument.appendChild(mockDocumentFragment);
+      return cloneDocument;
+    };
+    /**
+     * Use `getInnerHTML()` to serialize shadow dom as <template> tags. `innerHTML` and `outerHTML` don't do this. Buzzword: "declarative shadow dom"
+     */
+    const getOuterHTML = docElement => {
+      // firefox doesn't serialize shadow DOM, we're awaiting API's by firefox to become ready and are not polyfilling it.
+      if (!docElement.getInnerHTML) {
+        return docElement.outerHTML;
+      }
+      // chromium gives us declarative shadow DOM serialization API
+      let innerHTML = docElement.getInnerHTML({
+        includeShadowRoots: true
+      });
+      docElement.textContent = '';
+      return docElement.outerHTML.replace('</html>', `${innerHTML}</html>`);
+    };
+    // we inject declarative shadow dom polyfill to allow shadow dom to load in non chromium infrastructure browsers
+    // Since only chromium currently supports declarative shadow DOM - https://caniuse.com/declarative-shadow-dom
+    function injectDeclarativeShadowDOMPolyfill(ctx) {
+      let clone = ctx.clone;
+      let scriptEl = clone.createElement('script');
+      scriptEl.setAttribute('id', '__percy_shadowdom_helper');
+      scriptEl.setAttribute('data-percy-injected', true);
+      scriptEl.innerHTML = `
+      function reversePolyFill(root=document){
+        root.querySelectorAll('template[shadowroot]').forEach(template => {
+          const mode = template.getAttribute('shadowroot');
+          const shadowRoot = template.parentNode.attachShadow({ mode });
+          shadowRoot.appendChild(template.content);
+          template.remove();
+        });
+        root.querySelectorAll('[data-percy-shadow-host]').forEach(shadowHost => reversePolyFill(shadowHost.shadowRoot));
+      }
+      if (["interactive", "complete"].includes(document.readyState)) {
+        reversePolyFill();
+      } else {
+        document.addEventListener("DOMContentLoaded", () => reversePolyFill());
+      }
+    `.replace(/(\n|\s{2}|\t)/g, '');
+      clone.body.appendChild(scriptEl);
     }
     // Returns a copy or new doctype for a document.
@@ -275,7 +476,7 @@
     // Serializes and returns the cloned DOM as an HTML string
     function serializeHTML(ctx) {
-      let html = ctx.clone.documentElement.outerHTML;
+      let html = getOuterHTML(ctx.clone.documentElement);
       // replace serialized data attributes with real attributes
       html = html.replace(/ data-percy-serialized-attribute-(\w+?)=/ig, ' $1=');
       // include the doctype with the html string
@@ -298,8 +499,8 @@
         warnings: new Set(),
         enableJavaScript
       };
-      ctx.dom = prepareDOM(dom);
-      ctx.clone = ctx.dom.cloneNode(true);
+      ctx.dom = dom;
+      ctx.clone = cloneNodeAndShadow(ctx.dom);
       serializeInputElements(ctx);
       serializeFrames(ctx);
       serializeVideos(ctx);
@@ -314,6 +515,7 @@
           console.error('Could not transform the dom:', err.message);
         }
       }
+      injectDeclarativeShadowDOMPolyfill(ctx);
       let result = {
         html: serializeHTML(ctx),
         warnings: Array.from(ctx.warnings),

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@percy/dom",
-  "version": "1.17.0",
+  "version": "1.19.1-alpha.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -34,5 +34,5 @@
   "devDependencies": {
     "interactor.js": "^2.0.0-beta.10"
   },
-  "gitHead": "b7b2403047ea6208de71c73232df8a5375781a30"
+  "gitHead": "1a95e827ef2fb7e6f2c7a7a5a90d265185f31fc2"
 }