@open-wc/semantic-dom-diff

Semantic Dom Diff

Part of Open Web Components

Open Web Components provides a set of defaults, recommendations and tools to help facilitate your web component project. Our recommendations include: developing, linting, testing, building, tooling, demoing, publishing and automating.

Manual Setup

yarn add @open-wc/semantic-dom-diff --dev

semantic-dom-diff exports a function which takes a string of HTML, and returns a string of HTML. It restructures given HTML string, returning it in a format which can be used for comparison:

• whitespace and newlines are normalized
• tags and attributes are printed on individual lines
• comments, style and script tags are removed
• additional tags and attributes can optionally be ignored

Basic usage

import { getDiffableSemanticHTML } from '@open-wc/semantic-dom-diff';

const leftTree = getDiffableSemanticHTML(`
  <div>foo</div>
`);
const rightTree = getDiffableSemanticHTML(`
  <div>bar</div>
`);

// use any string comparison tool, for example chai:
expect(leftTree).to.equal(rightTree);

Ignoring tags and attributes

When working with libraries or custom elements there might be parts of the rendered HTML which is random or otherwise outside of your control. In those cases, you might want to ignore certain attributes or tags entirely. This is possible by passing an options object.

Ignoring an attribute

import { getDiffableSemanticHTML } from '@open-wc/semantic-dom-diff';

const leftTree = getDiffableSemanticHTML(`
  <div data-my-attribute="someRandomlyGeneratedDataInAnAttribute">
    foo
  </div>
`, { ignoreAttributes: ['data-my-attribute'] });

const rightTree = getDiffableSemanticHTML(`
  <div>
    foo
  </div>
`);

// this test will pass, the attribute is ignored
expect(leftTree).to.equal(rightTree);

Ignoring an attribute only for certain tags

Randomly generated ids are often used, throwing off your diffs. You can ignore attributes on specific tags:

import { getDiffableSemanticHTML } from '@open-wc/semantic-dom-diff';

const leftTree = getDiffableSemanticHTML(`
  <div>
    <input id="someRandomlyGeneratedId">
  </div>
`, { ignoreAttributes: [{ tags: ['input'], attributs: ['id'] }] });

const rightTree = getDiffableSemanticHTML(`
  <div>
    <input>
  </div>
`);

// this test will pass, the id attribute is ignored
expect(leftTree).to.equal(rightTree);

Ignoring a tag

Similarly you can tell the diff to ignore certain tags entirely:

import { getDiffableSemanticHTML } from '@open-wc/semantic-dom-diff';

const leftTree = getDiffableSemanticHTML(`
  <div>
    <my-custom-element><my-custom-element>
    foo
  </div>
`, { ignoreTags: ['my-custom-element'] });

const rightTree = getDiffableSemanticHTML(`
  <div>
    foo
  </div>
`);

// this test will pass, the tag is ignored completely
expect(leftTree).to.equal(rightTree);

Ignoring light dom

When working with web components you may find that they sometimes render to their light dom, for example to meet some accessibility requirements. We don't want to ignore the tag completely, as we would then not be able to test if we did render the tag. We can ignore just it's light dom:

import { getDiffableSemanticHTML } from '@open-wc/semantic-dom-diff';

const leftTree = getDiffableSemanticHTML(`
  <div>
    <my-custom-input id="myInput">
      <input id="inputRenderedInLightDom">
      Some text rendered in the light dom
    </my-custom-input>
    foo
  </div>
`, { ignoreLightDom: ['my-custom-element'] });

const rightTree = getDiffableSemanticHTML(`
  <div>
    <my-custom-input id="myInput"></my-custom-input>
    foo
  </div>
`);

// this test will pass, the light dom of my-custom-input is ignored, but we can still test
// to see if the tag is placed properly
expect(leftTree).to.equal(rightTree);