An opinionated, framework-agnostic library for Test-Driven Development of Web Components.
How to write tests
Both return Promise which is fulfilled when specific set of actions
(typically assertions) pass without throwing exception. If this doesn’t
happen before the
timeout expires, the Promise will fail with the last
In both cases, the action is executed for the first time straight off, in a synchronous way.
waitFor(assertion, timeout = 500, pollingInterval = 10)
will re-execute the
assertion sequentially (as specified by the
pollingInterval in miliseconds), until it either passes or the
function waitForDom(domRoot, assertion, timeout = 500)
assertion is related to the state of the DOM (contained in
domRoot) and, therefore, will be retried every time the relevant subtree
return waitFor(() => expect(someVariable).to.equal(666), 1000); return waitForDom(document.body, (dom) => expect(dom.querySelector('#myId')).not.to.be.null);
Locating your DOM parts:
selectDom(container: Element, attrName: string = 'data-automation-id')
Returns DOM selector function for the
container, using attribute
DOM selector is a function accepting one or more string identifiers.
const select = selectDOM(document.body, 'my-id'); const element = select('panel1', 'button-ok');
This code will find, inside the document body, element with attribute “myId” containing word “panel1” and inside it element with the same attribute containing word “button-ok”.
element will be null, if such path cannot be resolved (“button-ok” or
even “panel1” cannot be found).
select will throw an exception, if the path is ambiguous
(e.g., “panel1” contains more than one “button-ok”).
Often, components have parts which are sometimes present, sometimes absent, depending on their configuration or state. As there are many possibilities how such “re-appearance” can be implemented, this kit provides a matcher that abstracts such internal implementation away.
expect(element).to.be.present(); expect(element).to.be.absent(); expect(element).not.to.be.present(); expect(element).not.to.be.absent();
“Presence” is defined as follows:
- “element” is not null
- “element” is an instance of
- some part of “element” has real size (defined as
heightare greater than zero)
(This definition is inspired by jQuery’s
:visible selector, but not
necessarily compliant with it.)
Using layout matchers, component developers can implement tests which assert relations between various parts of the component in terms of position in the document. Layout matchers abstract away the actual DOM structure and CSS rules, as they are based solely on absolute location of bounding rectangles. With the right combination of layout matchers, one should be able describe most of spatial relationships within components.
The parts are passed as references to
Tests of layout matchers should provide exhaustive examples on how to use the matchers.
.insideOf(x) asserts that the subject is completely within the boundaries of element
.outsideOf(x) asserts the the subject is completely outside the boundaries of element
If the subject is partly inside and partly outside, none of the matchers passes.
Box properties of an element (
bottom) can be measured
and asserted with numeric matchers, such as:
Elements can also be compared with
At the same time, numeric comparisons will still work:
bottom will be compared as numbers. So
bottom = 50 will still be “below”
bottom = 100, even though
visually it will, of course, appear “above”.
.horizontallyAligned("left" | "center" | "right, tolerance = 0.0)
.verticallyAligned("top" | "center" | "bottom", tolerance = 0.0)
The alignment matchers assert that all elements within a list are properly aligned with each other, with optional tolerance range.
expect([button1, button2, button3]).to.be.verticallyAligned("top", 1.5);
.inHorizontalSequence(tolerance = 1.0)
.inVerticalSequence(tolerance = 1.0)
Asserts that all elements within a list form uninterrupted sequence, one adjacent to the other, without gaps.
expect([button1, button2, button3]).to.be.inHorizontalSequence(10.0);