react-maybe-matchers v0.0.1

React Maybe Matchers for Jasmine

Tests using the React test utilities directly are both difficult to read and inconvenient to type. These matchers are intended to to make it easier to write tests and to understand what they are doing later.

DSL for React tests

This is an example of the kinds of expectations you can write with react-maybe-matchers.

  expect(component).toBeAComponent (which) ->
    which.contains.tags("div")
         .with.cssClass("my-class")
         .and.text("contents")
         .exactly(2).times
         .result()

Literate Source Code

This project is written in literate Coffeescript. Literate programming (LP) is a style of programming introduced by Donald Knuth and famously used in the TeX text processing system.

You can browse the source code for this project.

Dependencies

react-maybe-matchers is currently built against Jasmine 2.3.2 and React 0.14.3. Other versions may work, but have not been tested. The React version is probably quite flexible as long as you have one with the test utils. Unfortunately this is unlikely the case for Jasmine as they have changed the way matchers work in some versions of the library. A more complete compatibility list will be made soon.

Installation

We have not yet added react-maybe-matchers to NPM, but you can still install it. If you are using NPM, you can install with the following entry in the devDependencies section of your package.json file:

"react-maybe-matchers": "git://github.com/ygt-mikekchar/react-maybe-matchers.git#master",

If you wish to use the code directly (for example in a submodule in your project), simply require lib/ReactMaybeMatchers.js.

Usage

To use custom matchers in Jasmine, you have to do a little bit of set up. Here is the typical way to set it up (in Coffeescript):

React = require("react")
ReactTestUtils = require('react-addons-test-utils')
ReactMaybeMatchers = require("../src/ReactMaybeMatchers.litcoffee")

describe "some wonderful thing", ->
  beforeEach ->
    new ReactMaybeMatchers(ReactTestUtils).addTo(jasmine)

API

There is only one one top level matcher. It is called toBeAComponent. To use it, you simply make an expectation on a React component and pass a matcher function.

  expect(component).toBeAComponent(matcherFn)

toBeAComponent will run matcherFn passing it a ComponentQuery object

Component Query

ComponentQuery allows you to search for component or DOM node rendered by a React component. Currently implemented:

• tags(tagname): Search for a DOM node with a specific HTML tag. Returns a DomComponentFilter.
• cssClass(className): Search for any DOM node with a given CSS class name. Returns a DomComponentFilter.
• type(componentClass): Search for React components of a given class. Returns a ComponentFilter.

A ComponentQuery will return a ComponentFilter or DomComponentFilter to allow you to further refine your search.

For fluent use of English, ComponentQuery defines:

• contains

This allows you to write an expectation like:

  expect(component).toBeAComponent (which) ->
    which.contains.tags("h1")
         .result()

Component Filter

ComponentFilter allows you to filter a collection of React components. Currently implemented:

• cssClass(cssClass): Filters all the contained nodes for those with a specific css class.
• exactly(num): Matches if the number of nodes is num. Does not match otherwise

DomComponentFilter includes the above but also implements:

• cssClass(cssClass): Filters all the contained nodes for those with a specific css class.
• text(string): Filters all the contained nodes for those which contain a string.

For fluent use of English, ComponentFilter and DomComponentFilter define:

• with
• and
• time
• times

Difference between ComponentQuery and ComponentFilter

Keep in mind that ComponentQuery drills down into the tree and finds a collection of components. ComponentFilter works on that collection of components or DOM nodes and does not drill down further.

License

react-maybe-matchers is distributed under the MIT licence.

Tests

The tests can be run in your browser.

Under Development

react-maybe-matchers is currently under development, but is very slightly useful now. Please feel free to submit issues or pull requests.