Riot-test-utils

This provides lightweight testing of Riot tags.

It is highly inspired by React-test-utils Enzyme, great testing utility for React.

Shallow-rendering is provided by Riot-shallowize including the limitation about transclusions.

Features:

• Shorter way to setup unit-testing of tags.
• Wrapper API of an instance of tags to inspect easily
• DOM Traversing API similar to jQuery
• jQuery integration
• Shallow-rendering.
• Snapshot testing

This library is being developing and have breaking changes even if minor update. Any contributions are welcome!

Installation

Install via npm:

npm install -D riot-test-utils

UMD module is also available. For example loading from CDN like jsdelivr is like:

<script src="https://cdn.jsdelivr.net/npm/[email protected]/riot.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/index.umd.min.js"></script>

Dependent packages riot-shallowize, simulate-event and other utilities are bundled in UMD.

Usage

Import as:

// es5/commonjs
var mount = require('riot-test-utils').mount;

// es6
import { mount } from 'riot-test-utils';

Create wrapper for the tag to test as:

var wrapper = mount('tag');

var wrapperWithOpts = mount('tag-with-opts', { title: 'RiotJS' });

and look outerHTML:

assert(wrapper.html() === '<tag data-is="tag"><p>Hello, world!</p></tag>');

Templating also works.

var wrapper = mount('<tag><p>{opts.greeting}</p></tag>', { greeting: 'Hello, world!' });

assert(wrapper.html() === '<tag data-is="tag"><p>Hello, world!</p></tag>');

Embedding style

We can write single tag source in the following style:

var wrapper = mount('<tag><p>Hello, world!</p></tag>');

Specify the name to test when you have multiple tags:

var wrapper = mount(
  [
    '<tag1><tag2 /></tag1>',
    '<tag2><p>Hello, world!</p></tag2>',
  ].join('\n'),
  'tag1'
);

Shallow rendering

This library provides great shallow-rendering feature as React-test-utils.

It truly separates your tests of one tag from the others.

For example:

var shallow = require('react-test-utils').shallow;

var wrapper = shallow(
  [
    '<inner><p>{opts.data}</p></inner>',
    '<outer><inner data={ opts.innerData }/></outer>'
  ].join('\n'),
  'outer',
  { innerData: 'Hello!' }
);

This is shallow rendered as:

assert(wrapper.html() === '<outer data-is="outer"><inner data="Hello!"></inner></outer>');

Of course, you can mount by name being registered.

var wrapper = shallow('outer', { innerData: 'Hello!' });

DOM testing

You can get DOM Element by root.

Then, you can inspect by DOM API or some utility like jQuery.

var wrapper = mount('tag', { greeting: 'Hellow, world' });

// find by DOM API
assert(wrapper.root.querySelector('p').textContent === 'Hellow, world' );

// find by jQuery
assert($(wrapper.root).find('p').text() === 'Hello, world');

And gather internal elements by find() method and inspect them.

const itemsWrapper = wrapper.find('ul.todo-list > li');

assert(itemsWrapper.length === 5);
assert(itemsWrapper.get(0).text() === 'Buy a car');

Snapshot testing

You can use toJSON() to use snapshot-testing to keep your tags.

With jest for example:

it('should match snapshot', function () {
  var wrapper = shallow('<tag><h1>Example:</h1><p>Hello, world!</p></tag>');

  expect(wrapper.toJSON()).toMatchSnapshot();
});

Then, you will see the following result if different:

  <tag
    data-is={
      Array [
        "tag"
      ]
    }
  >
-   Hello, world!
+   <h1>
+     Example:
+   </h1>
+   <p>
+     Hello, world!
+   </p>
  </tag>

Public API

Module

mount(tagName, [opts], [mountOptions])

mount(singleTagSource, [opts], [mountOptions])

mount(multipleTagSource, tagName, [opts], [mountOptions])

Mount a tag with full-rendering.

shallow(tagName, [opts], [mountOptions])

shallow(singleTagSource, [opts], [mountOptions])

shallow(multipleTagSource, tagName, [opts], [mountOptions])

Mount a tag with shallow-rendering.

They return RiotWrapper.

Parameters of mount/shallow

| Parameter | Type | Description | | ----------------- | ------ | ------------------------------------------------------------ | | tagName | String | name of tag to test. You need to have loaded the tag somewhere without singleTagSource or multipleTagSource. | | singleTagSource | String | content of one tag to test. | | multipleTagSource | String | content of tags including one to test. It requires tagName too. | | opts | Object | tag interface | | mountOptions | Object | Options to mount. It has one optional property attachTo. See below. |

mountOptions.attachedTo

An option to specify the element to mount on.

Example

<div>
  <span id="app"></span>
</div>
<script>
var span = document.getElementById('id');
var wrapper = mount('my-tag', { attachTo: span });
</script>

RiotWrapper

Wrapper of tag instance to be mounted or shallow-mounted.

instance

Get TagInstance of root.

root

Get root DOM Element.

It is equivalent to instance.root.

opts

Get opts, including "data-is" attribute added during rendering.

It is equivalent to instance.opts.

parent

Get the parent tag instance.

It is equivalent to instance.parent and always null.

tags

Get nested tags.

It is equivalent to instance.tags.

refs

Get refs.

It is equivalent to instance.refs.

on(event, callback)

one(event, callback)

trigger(event, ...args)

off(event, [callback])

All the observable methods.

It is equivalent to instance,on() and the others but returns the wrapper itself.

Note: this is always the unwrapped instance in callbacks.

isMounted

Get the flag if the tag is mounted or not.

It is equivalent to instance.isMounted.

mount()

Mount the tag.

Note it is already mounted initially.

It is equivalent to instance.mount().

unmount([keepTheParent])

Unmount the tag.

It is equivalent to instance.unmount().

update([data])

Update the tag and its children.

It is equivalent to instance.update().

mixin(mixin)

Apply mixin to the tag.

It is equivalent to instance.mixin().

find(selector)

Find internal elements by CSS selector.

This returns WeakWrapper

html()

Get outer HTML by string.

text()

Get internal concatenated text.

toJSON()

Get json form to create snapshot

simulate(eventType, [options])

Fire event.

For example:

wrapper.simulate('click');

wrapper.simulate('keyup', { key: 'a', keyCode: 97, metaKey: true });

All the events are listed in source.

WeakWrapper

Wrapper of DOM elements to be found.

instance

Tag instance. This always returns null.

root

Throws unless wrapped elements are single.

length

Get number of wrapped elements.

get([index])

Get wrapped element(s) as Element or array of Element.

find(selector)

Find more under the wrapped element(s) by CSS selector.

text()

html()

toJSON()

Contents APIs above are supported as well as RiotWrapper, but first two methods throws unless single.

simulate(eventType, [options])

Fire event.

If wrapper has multiple elements, it fires each element in the order of appearance.

jQuery integration

You can use some methods to inspect DOM of jQuery integrated with RiotWrapper and ShallowWrapper.

Check Riot-test-utils-jquery out.

Enzyme integration

Check Riot-enzyme out, but nearly archived.

Requirement

• JavaScript runtime, ES5 compatible at least and supports:
  • Symbol for snapshot testing.
• DOM Environment like real browsers or jsdom and supports:
  • querySelectorAll and compareDocumentPosition for finding(IE9 is dropped!).

TODO

• [x] Event simulated
• [x] Deep rendering
• [ ] Compiler options to set parsers
• [x] Implement update.
• [ ] To test the attributes of root opts
• [ ] Full-featured finding API.
• [x] More efficient API for multiple tags to compile once shared and use anywhere.
• [ ] Other testing utility.
• [x] Finding API on querySelctorAll similar to jQuery or Cheerio like Enzyme
• [ ] To promote results of find() if they are actually tag instances.