From e095116cd825aa1ce08f7951c731558ddce6ae43 Mon Sep 17 00:00:00 2001 From: petehunt Date: Mon, 17 Feb 2014 10:43:00 -0800 Subject: [PATCH 1/2] 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. From b22ba84b1deb6fd6f4307d7fc8a59653e780f953 Mon Sep 17 00:00:00 2001 From: petehunt Date: Tue, 18 Feb 2014 22:57:41 -0800 Subject: [PATCH 2/2] fix docs --- docs/09.4-test-utils.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/09.4-test-utils.md b/docs/09.4-test-utils.md index e1337950..b685787e 100644 --- a/docs/09.4-test-utils.md +++ b/docs/09.4-test-utils.md @@ -7,11 +7,11 @@ 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. +`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 is the only function that requires a DOM.** +Render a component into a detached DOM node in the document. **This function requires a DOM.** #### boolean isComponentOfType(ReactComponent instance, function componentClass) @@ -67,9 +67,11 @@ Pass a mocked component module to this method to augment it with useful methods #### 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`.** +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. +> 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)`