{"id":13422587,"url":"https://github.com/pzavolinsky/react-unit","last_synced_at":"2025-08-18T17:08:24.740Z","repository":{"id":57346975,"uuid":"41921518","full_name":"pzavolinsky/react-unit","owner":"pzavolinsky","description":"Lightweight unit test library for ReactJS","archived":false,"fork":false,"pushed_at":"2018-02-19T17:58:15.000Z","size":259,"stargazers_count":193,"open_issues_count":3,"forks_count":15,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-07-22T15:51:17.006Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pzavolinsky.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-09-04T14:54:02.000Z","updated_at":"2024-08-12T19:19:08.000Z","dependencies_parsed_at":"2022-08-25T18:53:18.577Z","dependency_job_id":null,"html_url":"https://github.com/pzavolinsky/react-unit","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/pzavolinsky/react-unit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pzavolinsky%2Freact-unit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pzavolinsky%2Freact-unit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pzavolinsky%2Freact-unit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pzavolinsky%2Freact-unit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pzavolinsky","download_url":"https://codeload.github.com/pzavolinsky/react-unit/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pzavolinsky%2Freact-unit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271027687,"owners_count":24687082,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-18T02:00:08.743Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-30T23:00:48.326Z","updated_at":"2025-08-18T17:08:24.710Z","avatar_url":"https://github.com/pzavolinsky.png","language":"JavaScript","readme":"react-unit\n==========\n\nReact Unit is a lightweight unit test library for ReactJS with very few (js-only) dependencies.\n\nBy 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.).\n\nNote: for testing simple components you might also be interested in [react-cucumber](https://github.com/pzavolinsky/react-cucumber).\n\nInstallation\n------------\n\n```\nnpm install --save-dev react-unit\n```\n\nand then, in your tests:\n```javascript\nvar React = require('react');\nvar createComponent = require('react-unit');\n\ndescribe('MyComponent', () =\u003e {\n  it('should echo the value', () =\u003e {\n    var component = createComponent(\u003cMyComponent value=\"hello, world!\" /\u003e);\n\n    var input = component.findByQuery('input')[0];\n\n    expect(input.props.value).toBe('hello, world!');\n  });\n\n  it('should trigger events', () =\u003e {\n    var changedValue;\n    function onChange(e) { changedValue = e.target.value; }\n\n    var component = createComponent(\u003cMyComponent onChange={onChange} /\u003e);\n    var input = component.findByQuery('input')[0];\n\n    input.onChange({target:{value: 'hi, everyone!'}});\n\n    expect(changedValue).toBe('hi, everyone!');\n  });\n});\n```\n\nNote that, while this example is using Jasmine, `react-unit` should work with any other test language of your choice.\n\n\nUsage\n-----\n\nTo use `react-unit` just require the `createComponent` function:\n\n```javascript\nvar createComponent = require('react-unit');\n```\n\nThen use it to create your component:\n\n```javascript\nvar component = createComponent(\u003cMyComponent value=\"hello, world!\" /\u003e);\n```\n\nor (if, for some reason you are not into JSX):\n\n```javascript\nvar component = createComponent(React.createElement(MyComponent, { value: \"hello, world!\" }));\n```\n\nNow that you have a representation of your component you can use it to find actual HTML elements calling `findByQuery`:\n\n```javascript\nvar allInputs     = component.findByQuery('input');\nvar allRows       = component.findByQuery('.row');\nvar allFirstNames = component.findByQuery('[name=firstName]');\n```\n\nBy 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.\n\nIn addition to `findByQuery` you can use `findBy` to test every element using a custom function:\n\n```javascript\nvar all = component.findBy(function() { return true; }); // () =\u003e true\nvar moreThanTwo = component.findBy(function(c) { return c.props.value \u003e 2 });\n```\n\nTo find elements by their `ref` attribute, you can use the `findByRef` method:\n\n```javascript\nvar allMyRefs = component.findByRef('myRef');\n```\n\nIf you want to find a component using a component variable instead of a string expression, you can use `findByComponent`:\n\n```javascript\nvar component = createComponent.shallow(\u003cCompositeComponent /\u003e); // Note: the .shallow!\n// or var component = createComponent.interleaved(\u003cCompositeComponent /\u003e);\n\nvar children = component.findByComponent(ChildComponent);\n```\nNote that `findByComponent` only works with `shallow` and `interleaved` rendering modes. See [Rendering Modes](#rendering-modes) below for more details.\n\nIf you want to test event handling, you can bind a handler to your component:\n\n```javascript\nvar changeEvent;\nfunction handler(e) { changeEvent = e; }\nvar component = createComponent(\u003cMyComponent onChange={handler} /\u003e);\n```\n\nThen find and interact with any element in the component:\n\n```javascript\ncomponent.findByQuery('some selector')[0].onChange('some event');\n```\n\nFinally assert the event:\n\n```javascript\nexpect(changeEvent).toBe('some event');\n```\n\nIf at any point you want to inspect the rendered component you can use:\n\n```javascript\nconsole.log(component.dump());\n```\n\nAPI Reference\n-------------\n\n#### Creating components\n\n```javascript\n// createComponent :: ReactElement -\u003e Component\ncreateComponent = (reactElement) =\u003e Component\n```\nRenders `reactElement` using the deep rendering strategy (see [Rendering Modes](#rendering-modes) for more details). Returns the rendered `Component`.\n\nThis method produces a component tree that is somewhat similar to applying `ReactDOM.render`.\n\nFor example:\n```javascript\nvar createComponent = require('react-unit');\nvar component = createComponent(\u003cMyComponent /\u003e);\n```\nMore examples in [test/create-component.jsx](https://github.com/pzavolinsky/react-unit/blob/master/test/create-component.jsx).\n\n---\n\u003cbr\u003e\n\n```javascript\n// createComponent.shallow :: ReactElement -\u003e Component\ncreateComponent.shallow = (reactElement) =\u003e Component\n```\nRenders `reactElement` using the shallow rendering strategy (see [Rendering Modes](#rendering-modes) for more details). Returns the rendered `Component`.\n\nThis 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.\n\nFor example:\n```javascript\nvar createComponent = require('react-unit');\nvar component = createComponent.shallow(\u003cMyComponent /\u003e);\n```\nMore examples in [test/create-component-shallow.jsx](https://github.com/pzavolinsky/react-unit/blob/master/test/create-component-shallow.jsx).\n\n---\n\u003cbr\u003e\n\n```javascript\n// createComponent.interleaved :: ReactElement -\u003e Component\ncreateComponent.interleaved = (reactElement) =\u003e Component\n```\nRenders `reactElement` using the interleaved rendering strategy (see [Rendering Modes](#rendering-modes) for more details). Returns the rendered `Component`.\n\nThis method produces a component tree that interleaves react components and actual rendered components.\n\nFor example:\n```javascript\nvar createComponent = require('react-unit');\nvar component = createComponent.interleaved(\u003cMyComponent /\u003e);\n```\nMore examples in [test/create-component-interleaved.jsx](https://github.com/pzavolinsky/react-unit/blob/master/test/create-component-interleaved.jsx).\n\n---\n\u003cbr\u003e\n\n#### Finding components\n\n```javascript\n// findByQuery :: String -\u003e [Component]\ncomponent.findByQuery =\u003e (sizzleExpression) =\u003e [Components]\n```\nReturns all the descendant elements of `component` matching `sizzleExpression`.\n\nFor example:\n```javascript\nvar inputs = component.findByQuery('input');\n```\nMore examples in [test/find-by-query.jsx](https://github.com/pzavolinsky/react-unit/blob/master/test/find-by-query.jsx).\n\n---\n\u003cbr\u003e\n\n```javascript\n// findByComponent :: ReactElement -\u003e [Component]\ncomponent.findByComponent =\u003e (reactElement) =\u003e [Components]\n```\nReturns 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.\n\nFor example:\n```javascript\n// assuming: var MyItem = React.createClass({ ... });\nvar items = component.findByComponent(MyItem);\n```\nMore examples in [test/find-by-component.jsx](https://github.com/pzavolinsky/react-unit/blob/master/test/find-by-component.jsx).\n\n---\n\u003cbr\u003e\n\n```javascript\n// findBy :: (Component -\u003e bool) -\u003e [Component]\ncomponent.findBy =\u003e (fn) =\u003e [Components]\n```\nReturns all the descendant elements of `component` for whom `fn` returns `true`.\n\nFor example:\n```javascript\nvar moreThanTwos = component.findBy(c =\u003e c.props.value \u003e 2);\n```\nMore examples in [test/find-by.jsx](https://github.com/pzavolinsky/react-unit/blob/master/test/find-by.jsx).\n\n---\n\u003cbr\u003e\n\n```javascript\n// findByRef :: String -\u003e [Component]\ncomponent.findBy =\u003e (ref) =\u003e [Components]\n```\nReturns all the descendant elements of `component` matching the `ref` attribute.\n\nFor example:\n```javascript\nvar allMyRefs = component.findByRef('myRef');\n```\nMore examples in [test/find-by-ref.jsx](https://github.com/pzavolinsky/react-unit/blob/master/test/find-by-ref.jsx).\n\n---\n\u003cbr\u003e\n\n#### Inspecting components\n\n```javascript\n// dump :: () -\u003e String\ncomponent.dump =\u003e () =\u003e String\n```\nReturns a string representation of the pseudo-HTML of the component. This method is very useful for troubleshooting broken tests.\n\nFor example:\n```javascript\nvar html = component.dump();\n// or\nconsole.log(component.dump());\n```\n\n---\n\u003cbr\u003e\n\n```javascript\ncomponent.texts // :: [String]\ncomponent.text  // :: String\n```\nReturn 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('')`).\n\nSome examples in [test/text.jsx](https://github.com/pzavolinsky/react-unit/blob/master/test/text.jsx).\n\n---\n\u003cbr\u003e\n\n```javascript\n// key :: Object\ncomponent.props\n```\nThe `props` object of `component`.\n\n---\n\u003cbr\u003e\n\n```javascript\n// key :: String\ncomponent.key\n```\nThe `key` of `component`.\n\n---\n\u003cbr\u003e\n\n```javascript\n// ref :: String\ncomponent.ref\n```\nThe `ref` of `component`.\n\n---\n\u003cbr\u003e\n\n\nRendering Modes\n---------------\n\n#### Deep rendering (default behavior)\n\nBy default `react-unit` will use a deep (recursive) rendering strategy. This produces an output that is very similar to that of `ReactDOM.render`.\n\nFor example, given:\n\n```jsx\nvar Person = React.createClass({\n  render: function() {\n    var children = React.Children.map(this.props.children, (c,i) =\u003e \u003cli key={i}\u003e{c}\u003c/li\u003e);\n    return \u003cdiv\u003e\u003ch1\u003e{this.props.name}\u003c/h1\u003e\u003cul\u003e{children}\u003c/ul\u003e\u003c/div\u003e\n  }\n});\n```\n\nCalling `createComponent` in a composite component:\n\n```jsx\nvar component = createComponent(\n  \u003cPerson name=\"Homer\"\u003e\n    \u003cPerson name=\"Bart\"/\u003e\n    \u003cPerson name=\"Lisa\" /\u003e\n    \u003cPerson name=\"Maggie\" /\u003e\n  \u003c/Person\u003e);\n```\n\nResults in a representation of the following HTML:\n\n```html\n\u003cdiv\u003e\n  \u003ch1\u003eHomer\u003c/h1\u003e\n  \u003cul\u003e\n    \u003cli\u003e\n      \u003cdiv\u003e\u003ch1\u003eBart\u003c/h1\u003e\u003cul\u003e\u003c/ul\u003e\u003c/div\u003e\n    \u003c/li\u003e\n    \u003cli\u003e\n      \u003cdiv\u003e\u003ch1\u003eLisa\u003c/h1\u003e\u003cul\u003e\u003c/ul\u003e\u003c/div\u003e\n    \u003c/li\u003e\n    \u003cli\u003e\n      \u003cdiv\u003e\u003ch1\u003eMaggie\u003c/h1\u003e\u003cul\u003e\u003c/ul\u003e\u003c/div\u003e\n    \u003c/li\u003e\n  \u003c/ul\u003e\n\u003c/div\u003e\n```\n\nIn 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. `\u003cPerson/\u003e`) were erased from the HTML representation.\n\nIn the example above you find `Lisa` with:\n\n```jsx\nvar lisa = component.findByQuery('div \u003e ul \u003e li \u003e div \u003e h1')[1];\n```\n\nOn 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:\n\n```jsx\nvar persons = component.findByQuery('Person');\nexpect(persons.length).toEqual(0);\n```\n\n#### Shallow rendering\n\nSometimes 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.\n\nTo achieve this you can use `createComponent.shallow` as follows:\n\n```jsx\nvar component = createComponent.shallow(\n  \u003cPerson name=\"Homer\"\u003e\n    \u003cPerson name=\"Bart\"/\u003e\n    \u003cPerson name=\"Lisa\" /\u003e\n    \u003cPerson name=\"Maggie\" /\u003e\n  \u003c/Person\u003e);\n```\n\nAnd the result would be a representation of the following pseudo-HTML:\n\n```html\n\u003cdiv\u003e\n  \u003ch1\u003eHomer\u003c/h1\u003e\n  \u003cul\u003e\n    \u003cli\u003e\n      \u003cPerson name=\"Bart\"/\u003e\n    \u003c/li\u003e\n    \u003cli\u003e\n      \u003cPerson name=\"Lisa\"/\u003e\n    \u003c/li\u003e\n    \u003cli\u003e\n      \u003cPerson name=\"Maggie\"/\u003e\n    \u003c/li\u003e\n  \u003c/ul\u003e\n\u003c/div\u003e\n```\n\nTo find `Lisa` you could use any of the following:\n\n```jsx\nvar lisaByAttr         = component.findByQuery('Person[name=Lisa]')[0];\nvar lisaByTagAndOrder  = component.findByQuery('Person')[1];\nvar lisaByCompAndOrder = component.findByComponent(Person)[1];\n```\n\nAnd access the properties as usual:\n\n```jsx\nexpect(lisaByAttr.prop('name')).toEqual('Lisa');\n```\n\n#### Interleaved rendering\n\nThis 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.\n\nTo use interleaved rendering call `createComponent.interleaved` as follows:\n\n```jsx\nvar component = createComponent.interleaved(\n  \u003cPerson name=\"Homer\"\u003e\n    \u003cPerson name=\"Bart\"/\u003e\n    \u003cPerson name=\"Lisa\" /\u003e\n    \u003cPerson name=\"Maggie\" /\u003e\n  \u003c/Person\u003e);\n```\n\nThe result would be a representation of the following pseudo-HTML:\n\n```html\n\u003cPerson name=\"Homer\"\u003e\n  \u003cdiv\u003e\n    \u003ch1\u003eHomer\u003c/h1\u003e\n    \u003cul\u003e\n      \u003cli\u003e\n        \u003cPerson name=\"Bart\"\u003e\n          \u003cdiv\u003e\u003ch1\u003eBart\u003c/h1\u003e\u003cul\u003e\u003c/ul\u003e\u003c/div\u003e\n        \u003c/Person\u003e\n      \u003c/li\u003e\n      \u003cli\u003e\n        \u003cPerson name=\"Lisa\"\u003e\n          \u003cdiv\u003e\u003ch1\u003eLisa\u003c/h1\u003e\u003cul\u003e\u003c/ul\u003e\u003c/div\u003e\n        \u003c/Person\u003e\n      \u003c/li\u003e\n      \u003cli\u003e\n        \u003cPerson name=\"Maggie\"\u003e\n          \u003cdiv\u003e\u003ch1\u003eMaggie\u003c/h1\u003e\u003cul\u003e\u003c/ul\u003e\u003c/div\u003e\n        \u003c/Person\u003e\n      \u003c/li\u003e\n    \u003c/ul\u003e\n  \u003c/div\u003e\n\u003c/Person\u003e\n```\n\nAnd you can find components with:\n\n```jsx\nvar lisaComp    = component.findByQuery('Person[name=Lisa]')[0];\nvar lisaCompAlt = component.findByComponent(Person)[2];\n\nvar lisaName    = component.findByQuery('Person[name=Lisa] h1')[0];\nvar lisaNameAlt = lisaComp.findByQuery('h1')[0];\n```\n\nExcluding components\n--------------------\n\nUsing `exclude` you can now leave a component out of test as if it didn't exist.\n\n```jsx\n//single component\ncreateComponent.exclude(ChildComponent)(ParentComponent);\ncreateComponent.exclude(ChildComponent).shallow(ParentComponent);\ncreateComponent.exclude(ChildComponent).interleaved(ParentComponent);\n\n//multi components\ncreateComponent.exclude([ChildComponent1, ChildComponent2])(ParentComponent);\ncreateComponent.exclude([ChildComponent1, ChildComponent2]).shallow(ParentComponent);\ncreateComponent.exclude([ChildComponent1, ChildComponent2]).interleaved(ParentComponent);\n```\n\nMocking components\n------------------\n\nUsing `mock` you can now replace a component with another\n\n```jsx\n//single mock\ncreateComponent.mock(Actual, Mock)(ParentComponent);\n\n//multi mock\ncreateComponent\n  .mock(Actual1, Mock1)\n  .mock(Actual2, Mock2)(ParentComponent);\n```\n\nImplicit context\n----------------\n\nIf 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`:\n\n```jsx\ncreateComponent.withContext({ key: value})(\u003cMyComponentWithContext /\u003e);\n```\n\n\nMore info\n---------\n\n\nNote 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.\n\nFor more examples on how to test **events** refer to [test/events.jsx](https://github.com/pzavolinsky/react-unit/blob/master/test/events.jsx).\n\nFor 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).\n\nFor 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).\n","funding_links":[],"categories":["Dev Tools","Uncategorized","JavaScript","Unit Testing"],"sub_categories":["Test","Uncategorized","Assertion"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpzavolinsky%2Freact-unit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpzavolinsky%2Freact-unit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpzavolinsky%2Freact-unit/lists"}