Add ReactTestRenderer documentations (#10692)
* Add ReactTestRenderer documentations * Add TestRenderer documentations * TestRenderer is not experiment * Add a link for jsdom * Use ES Modules syntax * Twaek * Add a Link component * Use Jest assertions * Move a documentation for createNodeMock to Idea section * Renamed * Tweak * Rename * More explicit * Add a usecase for createNodeMock
Toru Kobayashi committed
Sep 26, 2017 at 16:30 UTC
b9d55695e14416f8affa248021fb617e661e52e8
2 files changed
+285
docs/_data/nav_docs.yml
+2
@@ -75,3 +75,5 @@
75
title: Test Utilities
76
- id: shallow-renderer
77
title: Shallow Renderer
78
+ - id: test-renderer
79
+ title: Test Renderer
docs/docs/reference-test-renderer.md
new
+283
@@ -0,0 +1,283 @@
1
+---
2
+id: test-renderer
3
+title: Test Renderer
4
+permalink: docs/test-renderer.html
5
+layout: docs
6
+category: Reference
7
+---
8
+
9
+**Importing**
10
+
11
+```javascript
12
+import TestRenderer from 'react-test-renderer'; // ES6
13
+const TestRenderer = require('react-test-renderer'); // ES5 with npm
14
+```
15
+
16
+## Overview
17
+
18
+This package provides a React renderer that can be used to render React components to pure JavaScript objects, without depending on the DOM or a native mobile environment.
19
+
20
+Essentially, this package makes it easy to grab a snapshot of the platform view hierarchy (similar to a DOM tree) rendered by a React DOM or React Native component without using a browser or [jsdom](https://github.com/tmpvar/jsdom).
21
+
22
+Example:
23
+
24
+```javascript
25
+import TestRenderer from 'react-test-renderer';
26
+
27
+function Link(props) {
28
+ return <a href={props.page}>{props.children}</a>;
29
+}
30
+
31
+const testRenderer = TestRenderer.create(
32
+ <Link page="https://www.facebook.com/">Facebook</Link>
33
+);
34
+
35
+console.log(testRenderer.toJSON());
36
+// { type: 'a',
37
+// props: { href: 'https://www.facebook.com/' },
38
+// children: [ 'Facebook' ] }
39
+```
40
+
41
+You can use Jest's snapshot testing feature to automatically save a copy of the JSON tree to a file and check in your tests that it hasn't changed: [Learn more about it](http://facebook.github.io/jest/blog/2016/07/27/jest-14.html).
42
+
43
+You can also traverse the output to find specific nodes and make assertions about them.
44
+
45
+```javascript
46
+import TestRenderer from 'react-test-renderer';
47
+
48
+function MyComponent() {
49
+ return (
50
+ <div>
51
+ <SubComponent foo="bar" />
52
+ <p className="my">Hello</p>
53
+ </div>
54
+ )
55
+}
56
+
57
+function SubComponent() {
58
+ return (
59
+ <p className="sub">Sub</p>
60
+ );
61
+}
62
+
63
+const testRenderer = TestRenderer.create(<MyComponent />);
64
+const testInstance = testRenderer.root;
65
+
66
+expect(testInstance.findByType(SubComponent).props.foo).toBe('bar');
67
+expect(testInstance.findByProps({className: "sub"}).children).toEqual(['Sub']);
68
+```
69
+
70
+### TestRenderer
71
+
72
+* [`TestRenderer.create()`](#TestRenderer.create)
73
+
74
+### TestRenderer instance
75
+
76
+* [`testRenderer.toJSON()`](#testRenderer.toJSON)
77
+* [`testRenderer.toTree()`](#testRenderer.toTree)
78
+* [`testRenderer.update()`](#testRenderer.update)
79
+* [`testRenderer.unmount()`](#testRenderer.unmount)
80
+* [`testRenderer.getInstance()`](#testRenderer.getInstance)
81
+* [`testRenderer.root`](#testRenderer.root)
82
+
83
+### TestInstance
84
+
85
+* [`testInstance.find()`](#testInstance.find)
86
+* [`testInstance.findByType()`](#testInstance.findByType)
87
+* [`testInstance.findByProps()`](#testInstance.findByProps)
88
+* [`testInstance.findAll()`](#testInstance.findAll)
89
+* [`testInstance.findAllByType()`](#testInstance.findAllByType)
90
+* [`testInstance.findAllByProps()`](#testInstance.findAllByProps)
91
+* [`testInstance.instance`](#testInstance.instance)
92
+* [`testInstance.type`](#testInstance.type)
93
+* [`testInstance.props`](#testInstance.props)
94
+* [`testInstance.parent`](#testInstance.parent)
95
+* [`testInstance.children`](#testInstance.children)
96
+
97
+## Reference
98
+
99
+### `TestRenderer.create()`
100
+
101
+```javascript
102
+TestRenderer.create(element, options);
103
+```
104
+
105
+Create a TestRenderer instance with a passed element, which has the following methods and properties.
106
+
107
+### `testRenderer.toJSON()`
108
+
109
+```javascript
110
+testRenderer.toJSON()
111
+```
112
+
113
+Return a JSON object representing the element.
114
+
115
+### `testRenderer.toTree()`
116
+
117
+```javascript
118
+testRenderer.toTree()
119
+```
120
+
121
+Return a tree object representing the element.
122
+
123
+### `testRenderer.update()`
124
+
125
+```javascript
126
+testRenderer.update(element)
127
+```
128
+
129
+Update the element with a passed element.
130
+
131
+### `testRenderer.unmount()`
132
+
133
+```javascript
134
+testRenderer.unmount()
135
+```
136
+
137
+Unmount the element from testRenderer.
138
+
139
+### `testRenderer.getInstance()`
140
+
141
+```javascript
142
+testRenderer.getInstance()
143
+```
144
+
145
+Return a root container instance.
146
+
147
+### `testRenderer.root`
148
+
149
+```javascript
150
+testRenderer.root
151
+```
152
+
153
+`root` is a testInstance, which has the following methods and properties.
154
+
155
+### `testInstance.find()`
156
+
157
+```javascript
158
+testInstance.find(test)
159
+```
160
+
161
+Find a descendant testInstance that `test(testInstance)` is `true`.
162
+
163
+### `testInstance.findByType()`
164
+
165
+```javascript
166
+testInstance.findByType(type)
167
+```
168
+
169
+Find a descendant testInstance that matches the provided type.
170
+
171
+### `testInstance.findByProps()`
172
+
173
+```javascript
174
+testInstance.findByProps(props)
175
+```
176
+
177
+Find a descendant testInstance that matches the provided props.
178
+
179
+### `testInstance.findAll()`
180
+
181
+```javascript
182
+testInstance.findAll(test)
183
+```
184
+
185
+Find all descendant testInstances that `test(testInstance)` is `true`.
186
+
187
+### `testInstance.findAllByType()`
188
+
189
+```javascript
190
+testInstance.findAllByType(type)
191
+```
192
+
193
+Find all descendant testInstances that matches the provided type.
194
+
195
+### `testInstance.findAllByProps()`
196
+
197
+```javascript
198
+testInstance.findAllByProps(props)
199
+```
200
+
201
+Find all descendant testInstances that matches the provided props.
202
+
203
+### `testInstance.instance`
204
+
205
+```javascript
206
+testInstance.instance
207
+```
208
+
209
+`instance` is a component instance of the testInstance.
210
+
211
+### `testInstance.type`
212
+
213
+```javascript
214
+testInstance.type
215
+```
216
+
217
+`type` is a Component type of the testInstance.
218
+
219
+### `testInstance.props`
220
+
221
+```javascript
222
+testInstance.props
223
+```
224
+
225
+`props` is a props object of the testInstance.
226
+
227
+### `testInstance.parent`
228
+
229
+```javascript
230
+testInstance.parent
231
+```
232
+
233
+`parent` is a parent testInstance.
234
+
235
+### `testInstance.children`
236
+
237
+```javascript
238
+testInstance.children
239
+```
240
+
241
+`children` is children of the testInstance.
242
+
243
+## Ideas
244
+
245
+You can pass `createNodeMock` function to `TestRenderer.create` as the option, which allows for custom mock refs.
246
+`createNodeMock` accepts the current element and should return a mock ref object.
247
+This is useful when you test a component rely on refs.
248
+
249
+```javascript
250
+import TestRenderer from 'react-test-renderer';
251
+
252
+class MyComponent extends React.Component {
253
+ constructor(props) {
254
+ super(props);
255
+ this.input = null;
256
+ }
257
+ componentDidMount() {
258
+ this.input.focus();
259
+ }
260
+ render() {
261
+ return <input type="text" ref={el => this.input = el} />
262
+ }
263
+}
264
+
265
+let focused = false;
266
+TestRenderer.create(
267
+ <MyComponent />,
268
+ {
269
+ createNodeMock: (element) => {
270
+ if (element.type === 'input') {
271
+ // mock a focus function
272
+ return {
273
+ focus: () => {
274
+ focused = true;
275
+ }
276
+ };
277
+ }
278
+ return null;
279
+ }
280
+ }
281
+);
282
+expect(focused).toBe(true);
283
+```