diff --git a/docs/docs/09.4-test-utils.md b/docs/docs/09.4-test-utils.md index 8c68fb9d70..d54af78276 100644 --- a/docs/docs/09.4-test-utils.md +++ b/docs/docs/09.4-test-utils.md @@ -9,70 +9,132 @@ next: clone-with-props.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) +### Simulate + +```javascript +Simulate.{eventName}({ReactComponent|DOMElement} element, object eventData) +``` + +Simulate an event dispatch on a React component instance or browser DOM node with optional `eventData` event data. **This is possibly the single most useful utility in `ReactTestUtils`.** + +Example usage: + +```javascript +React.addons.TestUtils.Simulate.click(myComponent); +React.addons.TestUtils.Simulate.change(myComponent); +React.addons.TestUtils.Simulate.keydown(myComponent, {key: "Enter"}); +``` + +`Simulate` has a method for every event that React understands. + +### renderIntoDocument + +```javascript +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) +### mockComponent -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) +```javascript +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) +### isComponentOfType -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`.** +```javascript +boolean isComponentOfType(ReactComponent instance, function componentClass) +``` -> 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. +Returns true if `instance` is an instance of a React `componentClass`. -Example usage: `React.addons.TestUtils.Simulate.click(myComponent)` +### isDOMComponent -`Simulate` has a method for every event that React understands. +```javascript +boolean isDOMComponent(ReactComponent instance) +``` + +Returns true if `instance` is a DOM component (such as a `
` or ``). + +### isCompositeComponent + +```javascript +boolean isCompositeComponent(ReactComponent instance)` +``` + +Returns true if `instance` is a composite component (created with `React.createClass()`) + +### isCompositeComponentWithType + +```javascript +boolean isCompositeComponentWithType(ReactComponent instance, function componentClass) +``` + +The combination of `isComponentOfType()` and `isCompositeComponent()`. + +### isTextComponent + +```javascript +boolean isTextComponent(ReactComponent instance) +``` + +Returns true if `instance` is a plain text component. + +### findAllInRenderedTree + +```javascript +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. + +### scryRenderedDOMComponentsWithClass + +```javascript +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`. + +### findRenderedDOMComponentWithClass + +```javascript +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. + +### scryRenderedDOMComponentsWithTag + +```javascript +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`. + +### findRenderedDOMComponentWithTag + +```javascript +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. + +### scryRenderedComponentsWithType + +```javascript +array scryRenderedComponentsWithType(ReactComponent tree, function componentClass) +``` + +Finds all instances of components with type equal to `componentClass`. + +### findRenderedComponentWithType + +```javascript +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.