README

bore

Enzyme-like testing utility built for the DOM and Web Components, that works both on the server and in browsers.

npm install @skatejs/bore --save-dev

Usage

Bore makes testing the DOM simpler in the same way Enzyme makes testing React simpler. It's built with Web Components in mind and follows similar conventions to Enzyme, but the APIs won't map 1:1.

/* @jsx h */

import mount from '@skatejs/bore';
import { h } from '@skatejs/val';

const wrapper = mount(
  <div>
    <span />
  </div>
);

// "span"
console.log(wrapper.one('span').node.localName);

You don't have to use @skatejs/val but it makes creating DOM a lot easier than using the native imperative APIs.

Testing with Jest / JSDOM / Node

Currently JSDOM doesn't have web component support, so you're limited to testing non-web-component DOM in JSDOM and Jest's default configuration.

To test your web components in Node or Jest, you'll have to use @skatejs/ssr. More information there.

Notes about web components

Since web components are an extension of the HTML standard, Bore inherently works with it. However there are a few things that it does underneath the hood that should be noted.

The custom element polyfill, if detected, is supported by calling flush() after mounting the nodes so things appear synchronous.
Nodes are mounted to a fixture that is always kept in the DOM (even if it's removed, it will put itself back). This is so that custom elements can go through their natural lifecycle.
The fixture is cleaned up on every mount, so there's no need to cleanup after your last mount.
The attachShadow() method is overridden to always provide an open shadow root so that there is always a shadowRoot property and it can be queried against.

API

There's no distinction between shallow rendering and full rendering as there's no significant performance implications and Shadow DOM negates the need for the distinction.

`mount(htmlOrNode)`

The mount function takes a node, or a string - and converts it to a node - and returns a wrapper around it.

/** @jsx h */

import mount from '@skatejs/bore';
import { h } from '@skatejs/val';

mount(
  <div>
    <span />
  </div>
);

Wrapper API

A wrapper is returned when you call mount():

const wrapper = mount(
  <div>
    <span />
  </div>
);

The wrapper contains several methods and properties that you can use to test your DOM.

`node`

Returns the node the wrapper is representing.

// div
mount(<div />).node.localName;

`all(query)`

You can search using pretty much anything and it will return an array of wrapped nodes that matched the query.

Element constructors

You can use element constructors to search for nodes in a tree.

mount(
  <div>
    <span />
  </div>
).all(HTMLSpanElement);

Since custom elements are just extensions of HTML elements, you can do it in the same exact way:

class MyElement extends HTMLElement {}
customElements.define('my-element', MyElement);

mount(
  <div>
    <my-element />
  </div>
).all(MyElement);

Custom filtering function

Custom filtering functions are simply functions that take a single node argument.

mount(
  <div>
    <span />
  </div>
).all(node => node.localName === 'span');

Diffing node trees

You can mount a node and search using a different node instance as long as it looks the same.

mount(
  <div>
    <span />
  </div>
).all(<span />);

The node trees must match exactly, so this will not work.

mount(
  <div>
    <span>test</span>
  </div>
).all(<span />);

Using an object as criteria

You can pass an object and it will match the properties on the object to the properties on the element.

mount(
  <div>
    <span id="test" />
  </div>
).all({ id: 'test' });

The objects must completely match, so this will not work.

mount(
  <div>
    <span id="test" />
  </div>
).all({ id: 'test', somethingElse: true });

Selector

You can pass a string and it will try and use it as a selector.

mount(
  <div>
    <span id="test" />
  </div>
).all('#test');

`one(query)`

Same as all(query) but only returns a single wrapped node.

mount(
  <div>
    <span />
  </div>
).one(<span />);

`has(query)`

Same as all(query) but returns true or false if the query returned results.

mount(
  <div>
    <span />
  </div>
).has(<span />);

`wait([then])`

The wait() function returns a promise that waits for a shadow root to be present. Even though Bore ensures the constructor and connectedCallback are called synchronously, your component may not have a shadow root right away, for example, if it were to have an async renderer that automatically creates a shadow root. An example of this is Skate's renderer.

mount(<MyComponent />)
  .wait()
  .then(doSomething);

A slightly more concise form of the same thing could look like:

mount(<MyComponent />).wait(doSomething);

`waitFor(funcReturnBool[, options = { delay: 1 }])`

Similar to wait(), waitFor(callback) will return a Promise that polls the callback at the specified delay. When it returns truthy, the promise resolves with the wrapper as the value.

mount(<MyElement />).waitFor(wrapper => wrapper.has(<div />));

This is very usefull when coupled with a testing framework that supports promises, such as Mocha:

describe('my custom element', () => {
  it('should have an empty div', () => {
    return mount(<MyComponent />).waitFor(w => w.has(<div />));
  });
});

Usage no npm install needed!