DOM Test Utils
Modern utility libray for testing web apps and components. dom-test-utils
works with anything compatible with the browser. Web components and lit-html are first class citizens.
Note: this project is still in a development phase. Based on feedback, there may be breaking changes to the API.
Basics
Set up test HTML fixtures and compare the result with what you expect:
;; const fixture = ; // fails test with error: attribute [class="foo"] was changed to attribute [class="bar"], at: section > h1fixture;
Integrates easily with web components. Set up a fixture, await async rendering and compare against shadow dom instead of light dom:
;; const fixture = await ; // fixture.component will give access to your web component's instanceconsole; // the fixture will compare the given HTML with the component's shadow rootfixture;
Supports HTML as string, as well as any valid lit-html render value:
// stringconst fixture = await ; // template stringconst fixture = await ; // lit templateconst fixture = await ; // dom nodeconst component = document;const fixture = await ;
Compares dom trees based on semantic equality. Attribute and class order don't matter. Whitespace, newlines and non-visual elements like styles and script are ignored. A descriptive error message is printed when two dom trees are not equal.
; // considered equal; const a = ` <section> <div id="foo"> <div></div> </div> </section>`; const b = ` <section> <div> <span></span> </div> </section>`; // throws error: tag <div> was changed to tag <span>, at: section > div#foo > div;
Workflow
When building dynamic web components, you want to make sure the rendered DOM stays the way you want. Instead of writing manual queries and assertions, you can store a 'snapshot' of the rendered DOM and write tests that given a certain state of your component the dom is still the way you expect. This is similar to Jest snapshots, expect that it works for plain HTML / web components. This can be written by hand, but tooling similar to https://jestjs.io/docs/en/snapshot-testing can automate this process in the future.
API Docs
Test fixtures
Simple fixtures
Set up test fixtures for a piece of HTML:
; const template = ` <section> <h1>Lorem ipsum</h1> <p> Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. </p> </section>`; // set up the HTML fixtureconst fixture = ; // query dom nodes in the fixturefixture; // print the rendered DOMconsole;
To avoid memory leaks, make sure to call teardown()
after you finish testing:
const fixture = ; fixture;
Async fixtures
Most frameworks or web component libraries do some kind of async/batched rendering. Creating fixtures is therefore async by default:
; const template = ` <my-element></my-element>`; const fixture = await ;
lit-html fixtures
dom-test-utils
uses lit-html to render the fixtures, and therefore accepts (besides strings) any valid lit-html
render variable:
Templates:
const fixture = await ;
Dom elements:
const element = document;const fixture = await ;
Arrays:
const templates = html`` html`` html``;const fixture = await ;
Comparing and diffing DOM trees
You can use dom-test-utils
for comparing and diffing DOM trees. Trees are compared semantically, not literally. This means that it is lenient with differences in attribute order, whitespace, newlines etc. Only visual HTML is compared, styles and script tags are ignored.
Within tests, the most convenient way is to the assertDOMEquals
method on the test fixture. This will throw a descriptive error when the trees are not equal:
const fixture = await ; // will not throwfixture; // throws an errorfixture;
You can use expectEquals
for BDD naming conventions.
assertDOMEquals
and expectEquals
accepts the same input as test fixture: strings, lit templates, dom nodes etc.
You can also use assertDOMEquals()
directly:
;const fixture = await ; // will not throwfixture; // throws an errorfixture;
getDOMDiff()
can also be used directly:
; const leftTree = html` foo`;const rightTree = html` bar`; // Diff will be an object if there is a difference, otherwise undefinedconst diff = ;
Inspiration
This project was heavily inspired by existing libraries. The intent is to create a standalone library based on modern APIs, and not coupled to any (testing) framework.