@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, restructuring it so that it can be easily compared:

• whitespace and newlines are normalized
• tags and attributes are printed on individual lines
• comments are removed
• style, script and svg contents are removed

Additional options can be configured.

Basic usage

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

const leftTree = getDiffableHTML(`
  <div>foo</div>
`);
const rightTree = getDiffableHTML(`
  <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 { getDiffableHTML } from '@open-wc/semantic-dom-diff';

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

const rightTree = getDiffableHTML(`
  <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 { getDiffableHTML } from '@open-wc/semantic-dom-diff';

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

const rightTree = getDiffableHTML(`
  <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 { getDiffableHTML } from '@open-wc/semantic-dom-diff';

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

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

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

Ignoring children

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 { getDiffableHTML } from '@open-wc/semantic-dom-diff';

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

const rightTree = getDiffableHTML(`
  <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);