From e095116cd825aa1ce08f7951c731558ddce6ae43 Mon Sep 17 00:00:00 2001 From: petehunt Date: Mon, 17 Feb 2014 10:43:00 -0800 Subject: [PATCH] Add ReactTestUtils to addons --- _data/nav_docs.yml | 2 + docs/09-addons.md | 7 +-- docs/09.3-class-name-manipulation.md | 2 +- docs/09.4-test-utils.md | 76 ++++++++++++++++++++++++++++ 4 files changed, 83 insertions(+), 4 deletions(-) create mode 100644 docs/09.4-test-utils.md diff --git a/_data/nav_docs.yml b/_data/nav_docs.yml index 90f13a30..cc1bf201 100644 --- a/_data/nav_docs.yml +++ b/_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/09-addons.md b/docs/09-addons.md index e1181ab0..76172786 100644 --- a/docs/09-addons.md +++ b/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/09.3-class-name-manipulation.md b/docs/09.3-class-name-manipulation.md index 9db1b021..ca2e1fde 100644 --- a/docs/09.3-class-name-manipulation.md +++ b/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/09.4-test-utils.md b/docs/09.4-test-utils.md new file mode 100644 index 00000000..e1337950 --- /dev/null +++ b/docs/09.4-test-utils.md @@ -0,0 +1,76 @@ +--- +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/)). All functions except for `renderIntoDocument()` work without a browser DOM. + +#### ReactComponent renderIntoDocument(ReactComponent instance) + +Render a component into a detached DOM node in the document. **This is the only function that 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 uses React's event system so it works outside of the browser. **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.