README.md

@percy/dom

Serializes a document's DOM into a DOM string suitable for re-rendering.

• Usage
  • ES6 imports
  • Browser injection
  • Options
• Serialized Content
  • Input elements
  • Frame elements
  • CSSOM rules
  • Canvas elements
  • Video elements
  • Other elements

Usage

ES6 imports

import serializeDOM from '@percy/dom';

// optional arguments shown with defaults
const domSnapshot = serializeDOM(options)

Browser injection

// via puppeteer
await page.addScriptTag({ path: require.resolve('@percy/dom') })
const domSnapshot = await page.evaluate(() => PercyDOM.serialize(options))

Options

• enableJavaScript — When true, does not serialize some DOM elements
• domTransformation — Function to transform the DOM after serialization
• disableShadowDOM — disable shadow DOM capturing, usually to be used when enableJavascript: true
• reshuffleInvalidTags — moves DOM tags which are outside </body> to its inside to make the DOM compliant.

Serialized Content

The following serialization happens to a cloned instance of the document in order.

Input elements

Input elements (input, textarea, select) are serialized by setting respective DOM attributes to their matching JavaScript property counterparts. For example checked, selected, and value.

Frame elements

Frame elements are serialized when they are CORS accessible and if they haven't been built by JavaScript when JavaScript is enabled. They are serialized by recursively serializing the iframe's own document element.

CSSOM rules

When JavaScript is not enabled, CSSOM rules are serialized by iterating over and appending each rule to a new stylesheet inserted into the document's head.

Canvas elements

Canvas elements' drawing buffers are serialized as data URIs and the canvas elements are replaced with image elements. The image elements reference the serialized data URI and have the same HTML attributes as their respective canvas elements. The image elements also have a max-width of 100% to accomidate responsive layouts in situations where canvases may be expected to resize with JS.

Video elements

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

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);
    }
  });