diff --git a/docs/_data/nav_docs.yml b/docs/_data/nav_docs.yml index 90f13a30748f6..cc1bf2012931b 100644 --- a/docs/_data/nav_docs.yml +++ b/docs/_data/nav_docs.yml @@ -45,6 +45,8 @@ title: Two-Way Binding Helpers - id: class-name-manipulation title: Class Name Manipulation + - id: test-utils + title: Test Utilities - id: examples title: Examples - title: Reference diff --git a/docs/docs/09-addons.md b/docs/docs/09-addons.md index e1181ab0527b2..76172786708e9 100644 --- a/docs/docs/09-addons.md +++ b/docs/docs/09-addons.md @@ -9,8 +9,9 @@ next: animation.html `React.addons` is where we park some useful utilities for building React apps. **These should be considered experimental** but will eventually be rolled into core or a blessed utilities library: -- `ReactTransitions`, for dealing with animations and transitions that are usually not simple to implement, such as before a component's removal. -- `ReactLink`, to simplify the coordination between user's form input data and and the component's state. -- `classSet`, for manipulating the DOM `class` string a bit more cleanly. +- [`ReactTransitions`](animation.html), for dealing with animations and transitions that are usually not simple to implement, such as before a component's removal. +- [`ReactLink`](two-way-binding-helpers.html), to simplify the coordination between user's form input data and and the component's state. +- [`classSet`](class-name-manipulation.html), for manipulating the DOM `class` string a bit more cleanly. +- [`ReactTestUtils`](test-utils.html), simple helpers for writing test cases (unminified build only). To get the add-ons, use `react-with-addons.js` (and its minified counterpart) rather than the common `react.js`. diff --git a/docs/docs/09.3-class-name-manipulation.md b/docs/docs/09.3-class-name-manipulation.md index 9db1b0216ea74..ca2e1fdee00dc 100644 --- a/docs/docs/09.3-class-name-manipulation.md +++ b/docs/docs/09.3-class-name-manipulation.md @@ -4,7 +4,7 @@ title: Class Name Manipulation layout: docs permalink: class-name-manipulation.html prev: two-way-binding-helpers.html -next: examples.html +next: test-utils.html --- `classSet()` is a neat utility for easily manipulating the DOM `class` string. diff --git a/docs/docs/09.4-test-utils.md b/docs/docs/09.4-test-utils.md new file mode 100644 index 0000000000000..b685787e4d803 --- /dev/null +++ b/docs/docs/09.4-test-utils.md @@ -0,0 +1,78 @@ +--- +id: test-utils +title: Test Utilities +layout: docs +permalink: test-utils.html +prev: class-name-manipulation.html +next: examples.html +--- + +`React.addons.TestUtils` makes it easy to test React components in the testing framework of your choice (we use [Jasmine](http://pivotal.github.io/jasmine/) with [jsdom](https://github.com/tmpvar/jsdom)). + +#### ReactComponent renderIntoDocument(ReactComponent instance) + +Render a component into a detached DOM node in the document. **This function requires a DOM.** + +#### boolean isComponentOfType(ReactComponent instance, function componentClass) + +Returns true if `instance` is an instance of a React `componentClass`. + +#### boolean isDOMComponent(ReactComponent instance) + +Returns true if `instance` is a DOM component (such as a `
` or ``). + +#### boolean isCompositeComponent(ReactComponent instance)` + +Returns true if `instance` is a composite component (created with `React.createClass()`) + +#### boolean isCompositeComponentWithType(ReactComponent instance, function componentClass) + +The combination of `isComponentOfType()` and `isCompositeComponent()`. + +#### boolean isTextComponent(ReactComponent instance) + +Returns true if `instance` is a plain text component. + +#### array findAllInRenderedTree(ReactComponent tree, function test) + +Traverse all components in `tree` and accumulate all components where `test(component)` is true. This is not that useful on its own, but it's used as a primitive for other test utils. + +#### array scryRenderedDOMComponentsWithClass(ReactCompoennt tree, string className) + +Finds all instance of components in the rendered tree that are DOM components with the class name matching `className`. + +#### ReactComponent findRenderedDOMComponentWithClass(ReactComponent tree, string className) + +Like `scryRenderedDOMComponentsWithClass()` but expects there to be one result, and returns that one result, or throws exception if there is any other number of matches besides one. + +#### array scryRenderedDOMComponentsWithTag(ReactComponent tree, string tagName) + +Finds all instance of components in the rendered tree that are DOM components with the tag name matching `tagName`. + +#### ReactComponent findRenderedDOMComponentWithTag(ReactComponent tree, string tagName) + +Like `scryRenderedDOMComponentsWithTag()` but expects there to be one result, and returns that one result, or throws exception if there is any other number of matches besides one. + +#### array scryRenderedComponentsWithType(ReactComponent tree, function componentClass) + +Finds all instances of components with type equal to `componentClass`. + +#### ReactComponent findRenderedComponentWithType(ReactComponent tree, function componentClass) + +Same as `scryRenderedComponentsWithType()` but expects there to be one result and returns that one result, or throws exception if there is any other number of matches besides one. + +#### object mockComponent(function componentClass, string? tagName) + +Pass a mocked component module to this method to augment it with useful methods that allow it to be used as a dummy React component. Instead of rendering as usual, the component will become a simple `
` (or other tag if `mockTagName` is provided) containing any provided children. + +#### Simulate.{eventName}({ReactComponent|DOMElement} element, object nativeEventData) + +Simulate an event dispatch on a React component instance or browser DOM node with optional `nativeEventData` event data. **This is possibly the single most useful utility in `ReactTestUtils`.** + +> Note: +> +> This helper is used to simulate browser events, so synthetic React events like `change` are not available. If you want to test `change`, simulate the underlying `input` browser event. + +Example usage: `React.addons.TestUtils.Simulate.click(myComponent)` + +`Simulate` has a method for every event that React understands. diff --git a/src/browser/ReactWithAddons.js b/src/browser/ReactWithAddons.js index 23aa4c6d40105..6310ff54a270d 100644 --- a/src/browser/ReactWithAddons.js +++ b/src/browser/ReactWithAddons.js @@ -42,5 +42,9 @@ React.addons = { cloneWithProps: cloneWithProps }; +if (__DEV__) { + React.addons.TestUtils = require('ReactTestUtils'); +} + module.exports = React;