teaspoon will not be updated to support React v16+. As of the recent release of enzyme v3, the differences between it and teaspoon have shrunk to almost complete API parity (baring a few things), Given that enzyme is more widely used and maintained it makes sense to switch to that going forward rather than continute to maintain teaspoon and it's underlying pieces. Thanks for using teaspoon ya'll!
Just the right amount of abstraction for writing clear, and concise React component tests.
Table of Contents generated with DocToc
- Getting Started
- Testing patterns
- Adding collection methods and pseudo selectors
- API
- Rendering
- Utility methods and properties
$.selector=> selector (alias: $.s)$.dom(instance) => HTMLElement$.compileSelector(selector) => (node) => bool$.defaultContext(context: ?object) => (node) => bool$.fn.length$.fn.unwrap() => Element|Instance|HTMLElement$.fn.get() => Array(alias: toArray())$.fn.tap() => function(Collection)$.fn.end() => Collection$.fn.each(Function iteratorFn)$.fn.map(Function iteratorFn)$.fn.reduce(Function iteratorFn, [initialValue]) -> Collection$.fn.reduceRight(Function iteratorFn) -> Collection$.fn.some(Function iteratorFn) -> bool$.fn.every(Function iteratorFn) -> bool$.instance.fn.dom -> HTMLElement
- Accessors
- Traversal methods
$.fn.find(selector)$.fn.filter(selector)$.fn.is(selector) -> Bool$.fn.children([selector])$.fn.parent([selector])$.fn.parents([selector])$.fn.closest([selector])$.fn.first([selector])$.fn.last([selector])$.fn.only()$.fn.single(selector)$.fn.any([selector])$.fn.none([selector])$.fn.text()
- Events
To get started install teaspoon via npm:
npm i --save-dev teaspoonTeaspoon is test environment agnostic, so you can (and should) bring your own test runner and frameworks. If you plan on doing normal component rendering (not just shallow rendering) you will also need a DOM environment, whether that's a browser, headless browser, or jsdom.
Like jQuery teaspoon exports a function that creates a collection of nodes; except in this case you select React elements instead of DOM nodes.
import $ from 'teaspoon';
let $div = $(<div />);
$div.length // 1
$div[0] // ReactElement{ type: 'div', props: {} ... }Since there is no globally accessible "document" of React elements like there is of DOM nodes, you need to start by selecting a tree. Once you have a tree you can query it with css selectors and jQuery-like methods.
let elements = (
<MyComponent>
<MyInput/>
<MyInput/>
<div className='fun-div'>
</MyComponent>
);
let $elements = $(elements);
$elements.find('div.fun-div').length // 1
$elements.find(MyInput).length // 2Along with plain ol' ReactElements you can also use teaspoon to traverse a rendered component tree. Teaspoon also does a bunch of work under the hood to normalize the traversal behavior of DOM components, Custom Components, and Stateless function Components.
let Greeting = props => <div>hello <strong>{props.name}</strong></div>;
let instance = ReactDOM.render(<Greeting name='John' />, mountNode)
let $instance = $(instance);
$instance.find('strong').text() // "John"That's nice but a bit verbose, luckily teaspoon lets you switch between both collection types (element and instance) nice and succinctly.
let Greeting = props => <div>hello <strong>{props.name}</strong></div>;
// renders `<Greeting/>` into the DOM and returns an collection of instances
let $elements = $(<Greeting />).render();
$elements.find('strong').text() // "John"
$elements.unmount() // removes the mounted component and returns a collection of elements
//or with shallow rendering
$elements.shallowRender()
.find('strong').text() // "John"The supported selector syntax is subset of standard css selectors:
- classes:
.foo - attributes:
div[propName="hi"]ordiv[boolProp] >: direct descendantdiv > .foo+: adjacent sibling selector~: general sibling selector:has(): parent selectordiv:has(a.foo):not(): negation:first-child:last-child:textmatches "text" (renderable) nodes, which may be a non string value (like a number):dommatches only DOM components:compositematches composite (user defined) components:contains(some text)matches nodes that have a text node descendant containing the provided text:textContent(some text)matches whose text content matches the provided text
Selector support is derived from the underlying selector engine: bill. New minor versions of bill are released independent of teaspoon, so you can always check there to see what is supported on the cutting edge.
Unlike normal css selectors, React elements and components often have prop values, and component types that are
not serializable to a string; components are often best selected by their actual class and not a name, and
prop values can complex objects such as a date prop equaling new Date().
For components, we've already seen that you can use the function name or the displayName, but
sometimes they aren't available. A less brittle approach is to select by the function itself. You can
use a tagged template string.
via the $.selector (also aliased as $.s) function for writing complex selectors like so:
$.s`div > ${Greeting}`
// select components with `start` props _strictly_ equal to `min`
let min = 10
$.s`[start=${min}]`If you don't want to use the newer syntax you can also call the selector function directly like:
$.s('div > ', Greeting, '.foo') // equivalent to: $.s`div > ${Greeting}.foo`Use can use these complex selectors in any place a selector is allowed:
let Name = props => <strong>{props.name}</strong>;
let Time = props => <em>{props.date.toLocaleString()}</em>
let Greeting = props => <div>hello <Name {...props} /> its: <Time {...props} /></div>;
let now = new Date();
let $inst = $(<Greeting name='John' date={now} />);
$inst
.render()
.find($.s`${Greeting} > strong`)
.text()
$inst
.shallowRender()
.find($.s`${Time}[date=${now}]`)
.only() As far as testing libraries go teaspoon has fairly few opinions about how to do stuff, so you can adapt whatever
testing practices and patterns you like. However there are some patterns and paths that fall out naturally from
teaspoon's API.
tap() provides a way to quickly step in the middle of a chain of queries and
collections to make a quick assertion. Below we quickly make a few changes to the component props and
check that the rendered output is what we'd expect.
let Greeting = props => <div>hello <strong>{props.name}</strong></div>;
$(<Greeting name='rikki-tikki-tavi'/>)
.render()
.tap(collection => {
collection
.first('div > :text')
.unwrap()
.should.equal('hello rikki-tikki-tavi')
})
.props('name', 'Nagaina')
.tap(collection => {
collection
.first('div > :text')
.unwrap()
.should.equal('hello Nagaina')
})
.unmount()An age old struggle with testing HTML output is that tests are usually not very resilient to DOM structure changes. You may move a save button into (or out of) some div that your test used to find the button, breaking the test. A classic technique to avoid this is the just use css classes, however it can be hard to distinguish between styling classes, and testing hooks.
In a React environment we can do one better, adding test specific attribute. This is a pattern taken up by libraries like
react-test-tree, and while teaspoon doesn't specifically "support"
that style of selection, its selector engine is more than powerful enough to allow that pattern of querying.
You can choose any prop name you like, but we recommend picking one that isn't likely to collide with a
component's "real" props. In this example let's use _testID.
let Greeting = props => <div>hello <strong _testID='name'>{props.name}</strong></div>;
$(<Greeting name='Betty' />)
.render()
.find('[_testID=name]')
.text()
.should.equal('Betty')You can adapt and expand this pattern however your team likes, maybe just using the single testing prop or a few. You can also add some helper methods or pseudo selectors to help codify enforce your teams testing conventions.
Teaspoon has a few conditional requires in order to support versions of React across major versions. This tends to
mean webpack warns about missing files, even when they aren't actually bugs. You can ignore the warnings or add an extra
bit of config to silence them.
/* webpack.config.js */
// ...
externals: {
// use for react 15.4.+
'react/lib/ReactMount': true,
// use for React any version below that
'react-dom/lib/ReactMount': true,
}
// ...Teaspoon also allows extending itself and adding new pseudo selectors using a fairly straight forward API.
To add a new method for all collection types add it to $.fn
(or $.prototype if the jQuery convention bothers you).
// Returns all DOM node descendants and filters by a selector
$.fn.domNodes = function(selector) {
return this
.find(':dom')
.filter(selector)
}
// also works with shallowRender()
$(<MyComponent />).render().domNodes('.foo')If you want to make a method only available to either instance of element collections you can extend
$.instance.fn or $.element.fn following the same pattern as above.
For new pseudo selectors you can use the createPseudo API which provides
a hook into the css selector engine used by teaspoon: bill. Pseudo selectors do
introduce a new object not extensively covered here, the Node. A Node is a light abstraction that
encapsulates both component instances and React elements, in order to provide a common traversal API across tree types.
You can read about them and their properties here.
// input:name(email)
$.createPseudo('name', function (name) {
// return a function that matches against elements or instances
return function (node) {
return $(node).is(`[name=${name}]`)
}
})
// We want to test if an element has a sibling that matches
// a selector e.g. :nextSibling(.foo)
$.createPseudo('nextSibling', function (selector) {
// turning the selector into a matching function up front
// is a bit more performant, alternatively we could just do $(node).is(selector);
let matcher = $.compileSelector(selector)
return function (node) {
let sibling = node.nextSibling;
return sibling != null && matcher(sibling)
}
})Teaspoon does what it can to abstract away the differences between element and instance collections into a common API, however everything doesn't coalesce nicely, so some methods are only relevant and available for collections of instances and some for collections of elements.
Methods that are common to both collections are listed as: $.fn.methodName
Whereas methods that are specific to a collection type are
listed as: $.instance.fn.methodName and $.element.fn.methodName respectively
Renders the first element of the Collection into the DOM using ReactDom.render. By default
the component won't be added to the page document, you can pass true as the first parameter to render into the
document.body. Additionally you can provide your own DOM node to mount the component into and/or a context object.
render() returns a new InstanceCollection
let elements = (
<MyComponent>
<div className='fun-div'>
</MyComponent>
);
let $elements = $(elements).render();
// accessible by document.querySelectorAll
$elements = $(elements).render(true);
// mount the component to the <span/>
$elements = $(elements).render(document.createElement('span'));Use the React shallow renderer utilities to shallowly render the first element of the collection.
let MyComponent ()=> <div>Hi there!</div>
$(<MyComponent/>)
.find('div')
.length // 0
$(<MyComponent/>)
.shallowRender()
.find('div')
.length // 1Since shallow collections are not "live" in the same way a real rendered component tree is, you may need to manually update the root collection to flush changes (such as those triggered by a child component).
In general you may not have to ever use update() since teaspoon tries to take care of all that for
you by spying on the componentDidUpdate life-cycle hook of root component instance.
Unmount the current tree and remove it from the DOM. unmount() returns an
ElementCollection of the root component element.
let $inst = $(<Greeting name='John' date={now} />);
let rendered = $inst.render();
//do some stuff...then:
rendered.unmount()The methods are shared by both Element and Instance Collections.
Selector creation function.
Returns the DOM nodes for a component instance, if it exists.
Compiles a selector into a function that matches a node
You can globally set a context object to be used for each and all renders,
shallow or otherwise. This is helpful for context that is available to all
levels of the application, like the router, i18n context, or a Redux Store.
The length of the collection.
Unwraps a collection of a single item returning the item. Equivalent to $el[0]; throws when there
is more than one item in the collection.
$(<div><strong>hi!</strong></div>)
.find('strong')
.unwrap() // -> <strong>hi!</strong>Returns a real JavaScript array of the collection items.
Run an arbitrary function against the collection, helpful for making assertions while chaining.
$(<MyComponent/>).render()
.prop({ name: 'John '})
.tap(collection =>
expect(collection.children().length).to.equal(2))
.find('.foo')Exits a chain, by returning the previous collection
$(<MyComponent/>).render()
.find('ul')
.single()
.end()
.find('div')An analog to Array.prototype.forEach; iterates over the collection calling the iteratorFn
with each item, index, and collection.
$(<MyComponent/>).render()
.find('div')
.each((node, index, collection)=>{
//do something
})An analog to Array.prototype..map; maps over the collection calling the iteratorFn
with each item, index, and collection.
$(<MyComponent/>).render()
.find('div')
.map((node, index, collection) => {
//do something
})An analog to Array.prototype..reduce, returns a new reduced teaspoon Collection
$(<MyComponent/>).render()
.find('div')
.reduce((current, node, index, collection)=>{
return current + ', ' + node.textContent
}, '')An analog to Array.prototype.reduceRight.
An analog to Array.prototype.some.
An analog to Array.prototype.every.
Returns the DOM nodes for each item in the Collection, if the exist
Set or get props from a component or element.
Setting props can only be done on root collections given the reactive nature of data flow in react trees (or on any element of a tree that isn't rendered).
.props(): retrieve all props.props(propName): retrieve a single prop.props(propName, propValue): update a single prop value.props(newProps): mergenewPropsinto the current set of props.
Set or get state from a component or element. In shallowly rendered trees only the root component can be stateful.
.state(): retrieve state.state(stateName): retrieve a single state value.state(stateName, stateValue, [callback]): update a single state value.state(newState, [callback]): mergenewStateinto the current state.
Set or get state from a component or element. In shallowly rendered trees only the root component can have context.
.context(): retrieve context.context(String contextName): retrieve a single context value.context(String contextName, Any contextValue, [Function callback]): update a single context value.context(Object newContext, [Function callback]): replace current context.
Search all descendants of the current collection, matching against the provided selector.
$(
<div>
<ul>
<li>item 1</li>
</ul>
</div>
).find('ul > li')Filter the current collection matching against the provided selector.
let $list = $([
<li>1</li>,
<li className='foo'>2</li>,
<li>3</li>,
]);
$list.filter('.foo').length // 1Test if each item in the collection matches the provided selector.
Return the children of the current selection, optionally filtered by those matching a provided selector.
note: rendered "Composite" components will only ever have one child since Components can only return a single node.
let $list = $(
<ul>
<li>1</li>
<li className='foo'>2</li>
<li>3</li>
</ul>
);
$list.children().length // 3
$list.children('.foo').length // 1Get the parent of each node in the current collection, optionally filtered by a selector.
Get the ancestors of each node in the current collection, optionally filtered by a selector.
For each node in the set, get the first element that matches the selector by testing the element and traversing up through its ancestors.
return the first item in a collection, alternatively search all collection descendants matching the provided selector and return the first match.
return the last item in a collection, alternatively search all collection descendants matching the provided selector and return the last match.
Assert that the current collection as only one item.
let $list = $(
<ul>
<li>1</li>
<li className='foo'>2</li>
<li>3</li>
</ul>
);
$list.find('li').only() // Error! Matched more than one <li/>
$list.find('li.foo').only().length // 1Find assert that only item matches the provided selector.
let $list = $(
<ul>
<li>1</li>
<li className='foo'>2</li>
<li>3</li>
</ul>
);
$list.single('li') // Error! Matched more than one <li/>
$list.single('.foo').length // 1Assert that the collection contains one or more nodes. Optionally search by a provided selector.
let $list = $(
<ul>
<li>1</li>
<li className='foo'>2</li>
<li>3</li>
</ul>
);
$list.any('p') // Error!
$list.any('li').length // 3Assert that the collection contains no nodes. Optionally search by a provided selector.
let $list = $(
<ul>
<li>1</li>
<li className='foo'>2</li>
<li>3</li>
</ul>
);
$list.none('li') // Error!
$list.none('p').length // 0Return the text content of the matched Collection.
let $els = $(<div>Hello <strong>John</strong></div)
$els.text() // "Hello John"Utilities for triggering and testing events on rendered and shallowly rendered components.
Trigger a "synthetic" React event on the collection items. works just like ReactTestUtils.simulate
$(<Component/>).render()
.trigger('click', { target: { value: 'hello ' } }).Simulates (poorly) event triggering for shallow collections. The method looks for a prop
following the convention 'on[EventName]': trigger('click') calls props.onClick(), and re-renders the root collection
Events don't bubble and don't have a proper event object.
$(<Component/>).shallowRender()
.find('button')
.trigger('click', { target: { value: 'hello ' } }).