react-unit ========== React Unit is a lightweight unit test library for ReactJS with very few (js-only) dependencies. By using `react-unit` you can run your ReactJS unit tests directly from node or gulp without having to install any heavyweight external dependencies (such as `jsdom`, `phantomjs`, the python runtime, etc.). Note: for testing simple components you might also be interested in [react-cucumber](https://github.com/pzavolinsky/react-cucumber). Installation ------------ ``` npm install --save-dev react-unit ``` and then, in your tests: ```javascript var React = require('react'); var createComponent = require('react-unit'); describe('MyComponent', () => { it('should echo the value', () => { var component = createComponent(); var input = component.findByQuery('input')[0]; expect(input.props.value).toBe('hello, world!'); }); it('should trigger events', () => { var changedValue; function onChange(e) { changedValue = e.target.value; } var component = createComponent(); var input = component.findByQuery('input')[0]; input.onChange({target:{value: 'hi, everyone!'}}); expect(changedValue).toBe('hi, everyone!'); }); }); ``` Note that, while this example is using Jasmine, `react-unit` should work with any other test language of your choice. Usage ----- To use `react-unit` just require the `createComponent` function: ```javascript var createComponent = require('react-unit'); ``` Then use it to create your component: ```javascript var component = createComponent(); ``` or (if, for some reason you are not into JSX): ```javascript var component = createComponent(React.createElement(MyComponent, { value: "hello, world!" })); ``` Now that you have a representation of your component you can use it to find actual HTML elements calling `findByQuery`: ```javascript var allInputs = component.findByQuery('input'); var allRows = component.findByQuery('.row'); var allFirstNames = component.findByQuery('[name=firstName]'); ``` By now you probably noted that `findByQuery` takes something suspiciously similar to jQuery selectors. This is not an innocent coincidence, `react-unit` is bundled with the amazing [jQuery Sizzle](https://github.com/jquery/sizzle) to allow you to search your react DOM using query selectors. In addition to `findByQuery` you can use `findBy` to test every element using a custom function: ```javascript var all = component.findBy(function() { return true; }); // () => true var moreThanTwo = component.findBy(function(c) { return c.props.value > 2 }); ``` To find elements by their `ref` attribute, you can use the `findByRef` method: ```javascript var allMyRefs = component.findByRef('myRef'); ``` If you want to find a component using a component variable instead of a string expression, you can use `findByComponent`: ```javascript var component = createComponent.shallow(); // Note: the .shallow! // or var component = createComponent.interleaved(); var children = component.findByComponent(ChildComponent); ``` Note that `findByComponent` only works with `shallow` and `interleaved` rendering modes. See [Rendering Modes](#rendering-modes) below for more details. If you want to test event handling, you can bind a handler to your component: ```javascript var changeEvent; function handler(e) { changeEvent = e; } var component = createComponent(); ``` Then find and interact with any element in the component: ```javascript component.findByQuery('some selector')[0].onChange('some event'); ``` Finally assert the event: ```javascript expect(changeEvent).toBe('some event'); ``` If at any point you want to inspect the rendered component you can use: ```javascript console.log(component.dump()); ``` API Reference ------------- #### Creating components ```javascript // createComponent :: ReactElement -> Component createComponent = (reactElement) => Component ``` Renders `reactElement` using the deep rendering strategy (see [Rendering Modes](#rendering-modes) for more details). Returns the rendered `Component`. This method produces a component tree that is somewhat similar to applying `ReactDOM.render`. For example: ```javascript var createComponent = require('react-unit'); var component = createComponent(); ``` More examples in [test/create-component.jsx](https://github.com/pzavolinsky/react-unit/blob/master/test/create-component.jsx). ---
```javascript // createComponent.shallow :: ReactElement -> Component createComponent.shallow = (reactElement) => Component ``` Renders `reactElement` using the shallow rendering strategy (see [Rendering Modes](#rendering-modes) for more details). Returns the rendered `Component`. This method produces a shallow component tree. That is, it renders the root component and all the children HTML nodes, stopping at the first child component level. For example: ```javascript var createComponent = require('react-unit'); var component = createComponent.shallow(); ``` More examples in [test/create-component-shallow.jsx](https://github.com/pzavolinsky/react-unit/blob/master/test/create-component-shallow.jsx). ---
```javascript // createComponent.interleaved :: ReactElement -> Component createComponent.interleaved = (reactElement) => Component ``` Renders `reactElement` using the interleaved rendering strategy (see [Rendering Modes](#rendering-modes) for more details). Returns the rendered `Component`. This method produces a component tree that interleaves react components and actual rendered components. For example: ```javascript var createComponent = require('react-unit'); var component = createComponent.interleaved(); ``` More examples in [test/create-component-interleaved.jsx](https://github.com/pzavolinsky/react-unit/blob/master/test/create-component-interleaved.jsx). ---
#### Finding components ```javascript // findByQuery :: String -> [Component] component.findByQuery => (sizzleExpression) => [Components] ``` Returns all the descendant elements of `component` matching `sizzleExpression`. For example: ```javascript var inputs = component.findByQuery('input'); ``` More examples in [test/find-by-query.jsx](https://github.com/pzavolinsky/react-unit/blob/master/test/find-by-query.jsx). ---
```javascript // findByComponent :: ReactElement -> [Component] component.findByComponent => (reactElement) => [Components] ``` Returns all the descendant elements of `component` of type `reactElement`. Note that `findByComponent` only works with `shallow` and `interleaved` rendering modes. See [Rendering Modes](#rendering-modes) below for more details. For example: ```javascript // assuming: var MyItem = React.createClass({ ... }); var items = component.findByComponent(MyItem); ``` More examples in [test/find-by-component.jsx](https://github.com/pzavolinsky/react-unit/blob/master/test/find-by-component.jsx). ---
```javascript // findBy :: (Component -> bool) -> [Component] component.findBy => (fn) => [Components] ``` Returns all the descendant elements of `component` for whom `fn` returns `true`. For example: ```javascript var moreThanTwos = component.findBy(c => c.props.value > 2); ``` More examples in [test/find-by.jsx](https://github.com/pzavolinsky/react-unit/blob/master/test/find-by.jsx). ---
```javascript // findByRef :: String -> [Component] component.findBy => (ref) => [Components] ``` Returns all the descendant elements of `component` matching the `ref` attribute. For example: ```javascript var allMyRefs = component.findByRef('myRef'); ``` More examples in [test/find-by-ref.jsx](https://github.com/pzavolinsky/react-unit/blob/master/test/find-by-ref.jsx). ---
#### Inspecting components ```javascript // dump :: () -> String component.dump => () => String ``` Returns a string representation of the pseudo-HTML of the component. This method is very useful for troubleshooting broken tests. For example: ```javascript var html = component.dump(); // or console.log(component.dump()); ``` ---
```javascript component.texts // :: [String] component.text // :: String ``` Return the text of all the descendant elements of `component`. `texts` is a flat array containing the texts of every descendant element in depth order. `text` behaves like `DOMNode.textContent` (i.e. `component.texts.join('')`). Some examples in [test/text.jsx](https://github.com/pzavolinsky/react-unit/blob/master/test/text.jsx). ---
```javascript // key :: Object component.props ``` The `props` object of `component`. ---
```javascript // key :: String component.key ``` The `key` of `component`. ---
```javascript // ref :: String component.ref ``` The `ref` of `component`. ---
Rendering Modes --------------- #### Deep rendering (default behavior) By default `react-unit` will use a deep (recursive) rendering strategy. This produces an output that is very similar to that of `ReactDOM.render`. For example, given: ```jsx var Person = React.createClass({ render: function() { var children = React.Children.map(this.props.children, (c,i) =>

{c}

); return

{this.props.name}

{children}

} }); ``` Calling `createComponent` in a composite component: ```jsx var component = createComponent( ); ``` Results in a representation of the following HTML: ```html

Homer

Bart
Lisa
Maggie

``` In other words, the output is the HTML that results of calling the render method of every component. Note that, as a side-effect of deep rendering, component tags (e.g. ``) were erased from the HTML representation. In the example above you find `Lisa` with: ```jsx var lisa = component.findByQuery('div > ul > li > div > h1')[1]; ``` On the flip side, you cannot use `findByQuery` to find your components because, after rendering, they were replaced by the HTML they generate in their `render` method: ```jsx var persons = component.findByQuery('Person'); expect(persons.length).toEqual(0); ``` #### Shallow rendering Sometimes you might want to stop rendering after the first level of components. In true unit test spirit you would like to just test a component assuming the components it depends upon are working. To achieve this you can use `createComponent.shallow` as follows: ```jsx var component = createComponent.shallow( ); ``` And the result would be a representation of the following pseudo-HTML: ```html

Homer

``` To find `Lisa` you could use any of the following: ```jsx var lisaByAttr = component.findByQuery('Person[name=Lisa]')[0]; var lisaByTagAndOrder = component.findByQuery('Person')[1]; var lisaByCompAndOrder = component.findByComponent(Person)[1]; ``` And access the properties as usual: ```jsx expect(lisaByAttr.prop('name')).toEqual('Lisa'); ``` #### Interleaved rendering This rendering mode is similar to the deep mode above with the exception that components are NOT erased form the HTML representation. This means that you can mix and match HTML tags and react components in your `findByQuery` selectors. To use interleaved rendering call `createComponent.interleaved` as follows: ```jsx var component = createComponent.interleaved( ); ``` The result would be a representation of the following pseudo-HTML: ```html

Homer

Bart
Lisa
Maggie

``` And you can find components with: ```jsx var lisaComp = component.findByQuery('Person[name=Lisa]')[0]; var lisaCompAlt = component.findByComponent(Person)[2]; var lisaName = component.findByQuery('Person[name=Lisa] h1')[0]; var lisaNameAlt = lisaComp.findByQuery('h1')[0]; ``` Excluding components -------------------- Using `exclude` you can now leave a component out of test as if it didn't exist. ```jsx //single component createComponent.exclude(ChildComponent)(ParentComponent); createComponent.exclude(ChildComponent).shallow(ParentComponent); createComponent.exclude(ChildComponent).interleaved(ParentComponent); //multi components createComponent.exclude([ChildComponent1, ChildComponent2])(ParentComponent); createComponent.exclude([ChildComponent1, ChildComponent2]).shallow(ParentComponent); createComponent.exclude([ChildComponent1, ChildComponent2]).interleaved(ParentComponent); ``` Mocking components ------------------ Using `mock` you can now replace a component with another ```jsx //single mock createComponent.mock(Actual, Mock)(ParentComponent); //multi mock createComponent .mock(Actual1, Mock1) .mock(Actual2, Mock2)(ParentComponent); ``` Implicit context ---------------- If you want to test components that use React's implicit [context](https://facebook.github.io/react/docs/context.html) you can pass the context to the rendered components by calling `withContext`: ```jsx createComponent.withContext({ key: value})(); ``` More info --------- Note that testing **stateful** components require additional effort. See [test/stateful.jsx](https://github.com/pzavolinsky/react-unit/blob/master/test/stateful.jsx) for more details. For more examples on how to test **events** refer to [test/events.jsx](https://github.com/pzavolinsky/react-unit/blob/master/test/events.jsx). For more examples on finding elements by **query selectors** refer to [test/find-by-query.jsx](https://github.com/pzavolinsky/react-unit/blob/master/test/find-by-query.jsx). For more examples on finding element using a **custom function** refer to [test/find-by.jsx](https://github.com/pzavolinsky/react-unit/blob/master/test/find-by.jsx).

{this.props.name}

Homer

Bart

Lisa

Maggie

Homer

Homer

Bart

Lisa

Maggie

	Stars	Issues	Version	Updated	Created
enzyme	19,953	283	3.11.0	5 years ago	9 years ago
jest-cli	44,071	352	29.7.0	a year ago	10 years ago
react-unit	193	3	3.0.3	7 years ago	9 years ago
redux-ava			2.2.0	8 years ago	9 years ago

enzyme vs jest-cli vs react-unit vs redux-ava

Downloads in past1 Month3 Months6 Months1 Year2 Years5 YearsAll time

Stats

Sick of boring JavaScript newsletters?

Downloads in past