Update docs for test utils add ons change #9331

flarnie · 2017-04-04T23:29:11Z

Wanted to get this up so I can get any corrections. Continuing to work on the rest of the document updates, which I can either push on separate branches as they are finished or on one branch/PR that gets updated as I go. I assume we will hold off merging until the actual 15.5 release happens.

Updating all references and docs on the React.addons.TestUtils and the
shallow renderer to refer to the correct targets.

Instead of:

const React = require('react');

// ...
React.addons.Testutils
// or

const ReactTestUtils = require('react-addons-test-utils');

we now show:

const ReactTestUtils = require('react-dom/test-utils');

And for shallow renderer, instead of:

const shallowRenderer = TestUtils.createRenderer();

we now show:

const shallowRenderer = require('react-test-renderer/shallow');

Also did a commit to update the incorrect or missing 'prev' and 'next' attributes on the 'add-ons' doc pages.

Updating all references and docs on the `React.addons.TestUtils` and the shallow renderer to refer to the correct targets. Instead of: ``` const React = require('react'); // ... React.addons.Testutils // or const ReactTestUtils = require('react-addons-test-utils'); ``` we now show: ``` const ReactTestUtils = require('react-dom/test-utils'); ``` And for shallow renderer, instead of: ``` const shallowRenderer = TestUtils.createRenderer(); ``` we now show: ``` const shallowRenderer = require('react-test-renderer/shallow'); ```

These flags are used to set arrow links to easily navigate through the documents. They were wrong or missing in some of the 'add-ons' pages and this bothered me when manually testing the updates from the previous commit.

gaearon · 2017-04-04T23:32:10Z

What do you think it the right thing to do for other addons? Given they're 15-only. I'm thinking maybe move their docs to Gists and set up permanent redirects so they're gone from the website but keep working.

bvaughn · 2017-04-04T23:34:19Z

docs/docs/addons-shallow-renderer.md

+
+Shallow rendering lets you render a component "one level deep" and assert facts about what its render method returns, without worrying about the behavior of child components, which are not instantiated or rendered. This does not require a DOM.
+
+ - [`createRenderer()`](#createrenderer)


What's this refer to? Maybe accidentally left over from before?

Yup - you are right, I had guessed that we were not using 'createRenderer' any more. Will fix.

bvaughn · 2017-04-04T23:36:51Z

docs/docs/addons-shallow-renderer.md

+Then you can assert:
+
+```javascript
+const renderer = ReactTestUtils.createRenderer();


This is the old way of doing things. The new way should be:

const ReactShallowRenderer = require('react-test-renderer/shallow'); const renderer = new ReactShallowRenderer();

Thanks - will fix.

flarnie · 2017-04-04T23:59:23Z

"What do you think it the right thing to do for other addons? Given they're 15-only. I'm thinking maybe move their docs to Gists and set up permanent redirects so they're gone from the website but keep working."

That seems ok to me, and in that case we would want warnings that they are "legacy" and won't be supported past v15.5.

For now we could also just remove them from the side-nav to unblock the 15.5 release, and then move them to gists and set up the redirects.

Missed this when updating the docs for the changes to shallow-renderer in React 15.5.

bvaughn

I think I'm seeing a pointer problem.

shallow-compare next points to two-way-binding-helpers but two-way-binding-helpers previous points to pure-render-mixin. (It should point back to shallow-compare).

Similarly, two-way-binding-helpers next points to perf but perf previous points to create-fragment. (Should point back to two-way-binding-helpers.)

bvaughn · 2017-04-05T17:50:45Z

docs/docs/addons-shallow-renderer.md

+
+```javascript
+import shallowRenderer from 'react-test-renderer/shallow'; // ES6
+var shallowRenderer = require('react-test-renderer/shallow'); // ES5 with npm


nit: I think we might want to rename these to ReactShallowRenderer to reduce ambiguity between what's returned by the import (the class) and the instance you render with.

import ReactShallowRenderer from 'react-test-renderer/shallow'; // ES6 var ReactShallowRenderer = require('react-test-renderer/shallow'); // ES5 with npm

I should have mentioned this before. Sorry.

It's cool - will fix.

@bvaughn

Thanks @bvaughn for catching this

We should show using the same variable names between code samples.

bvaughn

👍

gaearon · 2017-04-05T19:26:20Z

docs/docs/addons-shallow-renderer.md

+
+Shallow rendering lets you render a component "one level deep" and assert facts about what its render method returns, without worrying about the behavior of child components, which are not instantiated or rendered. This does not require a DOM.
+
+ - [`shallowRenderer.render()`](#shallowrenderer.render)


Let's change these to say ReactShallowRenderer too? Or maybe drop React there and just ShallowRenderer.

The pattern we show first is

const ReactShallowRenderer = require('react-test-renderer/shallow'); const renderer = new ReactShallowRenderer();

It makes sense to reserve the UpperCamelCase for the class itself, and for instances of the class use lowerSnakeCase. What we need still is consistency between the naming of the instances. I would vote for shallowRenderer instead of renderer.

Ah I see. Thanks for explaining.

We should use the same variable name for the same thing across examples. `renderer` -> `shallowRenderer`.

**what is the change?:** - Remove outdated 'shallow renderer' docs on 'test utils' page, and point to the updated 'shallow renderer' docs. - Re-add a link to the updated 'shallow renderer' docs on the main navigation. **why make this change?:** This was already approved in facebook#9331 which was then cherry-picked to https://github.com/facebook/react/pull/9359/commits and landed on master. I'm not sure why some of these changes didn't persist. For now just adding back the changes we need. **test plan:** Manually inspected website - will insert screenshots. **issue:**

@gaearon

* Add 'Test Utils' docs back to main navigation **why make this change?:** We accidentally removed this - still supporting the use of Test Utilities, so we should have them in the docs. **test plan:** Manually tested the website - will insert a screenshot. **issue:** #9651 * Move test-utils docs to reference section **what is the change?:** Moved from 'advanced guides' to 'reference' **why make this change?:** It makes more sense as a reference **test plan:** Visual inspection (flarnie may add a screenshot) **issue:** * Add back the shallow renderer docs and remove outdated docs **what is the change?:** - Remove outdated 'shallow renderer' docs on 'test utils' page, and point to the updated 'shallow renderer' docs. - Re-add a link to the updated 'shallow renderer' docs on the main navigation. **why make this change?:** This was already approved in #9331 which was then cherry-picked to https://github.com/facebook/react/pull/9359/commits and landed on master. I'm not sure why some of these changes didn't persist. For now just adding back the changes we need. **test plan:** Manually inspected website - will insert screenshots. **issue:** * Further improvements to 'shallow rendering' and 'test utils' docs Thanks @gaearon for the improvements! **what is the change?:** - Remove <hr/> from end of 'shallow rendering' docs - 'documents' -> 'documentation' - Move 'shallow rendering' redirection section to top of 'test utils' docs - Add intro sentence about testing to 'shallow rendering' docs **why make this change?:** Documentation helps people learn. **test plan:** Visual inspection

@gaearon

* Add 'Test Utils' docs back to main navigation **why make this change?:** We accidentally removed this - still supporting the use of Test Utilities, so we should have them in the docs. **test plan:** Manually tested the website - will insert a screenshot. **issue:** #9651 * Move test-utils docs to reference section **what is the change?:** Moved from 'advanced guides' to 'reference' **why make this change?:** It makes more sense as a reference **test plan:** Visual inspection (flarnie may add a screenshot) **issue:** * Add back the shallow renderer docs and remove outdated docs **what is the change?:** - Remove outdated 'shallow renderer' docs on 'test utils' page, and point to the updated 'shallow renderer' docs. - Re-add a link to the updated 'shallow renderer' docs on the main navigation. **why make this change?:** This was already approved in #9331 which was then cherry-picked to https://github.com/facebook/react/pull/9359/commits and landed on master. I'm not sure why some of these changes didn't persist. For now just adding back the changes we need. **test plan:** Manually inspected website - will insert screenshots. **issue:** * Further improvements to 'shallow rendering' and 'test utils' docs Thanks @gaearon for the improvements! **what is the change?:** - Remove <hr/> from end of 'shallow rendering' docs - 'documents' -> 'documentation' - Move 'shallow rendering' redirection section to top of 'test utils' docs - Add intro sentence about testing to 'shallow rendering' docs **why make this change?:** Documentation helps people learn. **test plan:** Visual inspection (cherry picked from commit 114b9c5)

@gaearon

* Add 'Test Utils' docs back to main navigation **why make this change?:** We accidentally removed this - still supporting the use of Test Utilities, so we should have them in the docs. **test plan:** Manually tested the website - will insert a screenshot. **issue:** #9651 * Move test-utils docs to reference section **what is the change?:** Moved from 'advanced guides' to 'reference' **why make this change?:** It makes more sense as a reference **test plan:** Visual inspection (flarnie may add a screenshot) **issue:** * Add back the shallow renderer docs and remove outdated docs **what is the change?:** - Remove outdated 'shallow renderer' docs on 'test utils' page, and point to the updated 'shallow renderer' docs. - Re-add a link to the updated 'shallow renderer' docs on the main navigation. **why make this change?:** This was already approved in #9331 which was then cherry-picked to https://github.com/facebook/react/pull/9359/commits and landed on master. I'm not sure why some of these changes didn't persist. For now just adding back the changes we need. **test plan:** Manually inspected website - will insert screenshots. **issue:** * Further improvements to 'shallow rendering' and 'test utils' docs Thanks @gaearon for the improvements! **what is the change?:** - Remove <hr/> from end of 'shallow rendering' docs - 'documents' -> 'documentation' - Move 'shallow rendering' redirection section to top of 'test utils' docs - Add intro sentence about testing to 'shallow rendering' docs **why make this change?:** Documentation helps people learn. **test plan:** Visual inspection (cherry picked from commit 114b9c5)

flarnie added 2 commits April 4, 2017 16:17

Update the 'prev' and 'next' attributes of 'add-ons' docs

505893b

These flags are used to set arrow links to easily navigate through the documents. They were wrong or missing in some of the 'add-ons' pages and this bothered me when manually testing the updates from the previous commit.

flarnie added the Documentation: needs merge to stable label Apr 4, 2017

flarnie added this to the 15-hipri milestone Apr 4, 2017

flarnie requested review from bvaughn and acdlite April 4, 2017 23:29

facebook-github-bot added the CLA Signed label Apr 4, 2017

bvaughn suggested changes Apr 4, 2017

View reviewed changes

Update syntax for instantiating shallow renderer

b280771

Missed this when updating the docs for the changes to shallow-renderer in React 15.5.

bvaughn suggested changes Apr 5, 2017

View reviewed changes

flarnie added 2 commits April 5, 2017 11:54

Fix pointers in addons docs

b1d522f

Thanks @bvaughn for catching this

Make example of shallow renderer more consistent

3421294

We should show using the same variable names between code samples.

bvaughn approved these changes Apr 5, 2017

View reviewed changes

gaearon reviewed Apr 5, 2017

View reviewed changes

Make names in example even more consistent

cea1fe9

We should use the same variable name for the same thing across examples. `renderer` -> `shallowRenderer`.

flarnie mentioned this pull request Apr 7, 2017

All doc updates forv15.5 #9359

Merged

2 tasks

acdlite closed this Apr 7, 2017

acdlite removed the Documentation: needs merge to stable label Apr 7, 2017

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update docs for test utils add ons change #9331

Update docs for test utils add ons change #9331

flarnie commented Apr 4, 2017

gaearon commented Apr 4, 2017

bvaughn Apr 4, 2017

flarnie Apr 4, 2017

bvaughn Apr 4, 2017

flarnie Apr 4, 2017

flarnie commented Apr 4, 2017

bvaughn left a comment •

edited

Loading

bvaughn Apr 5, 2017

flarnie Apr 5, 2017

bvaughn left a comment

gaearon Apr 5, 2017

flarnie Apr 5, 2017

gaearon Apr 5, 2017

gaearon Apr 5, 2017


		Shallow rendering lets you render a component "one level deep" and assert facts about what its render method returns, without worrying about the behavior of child components, which are not instantiated or rendered. This does not require a DOM.

		- [`createRenderer()`](#createrenderer)


		Shallow rendering lets you render a component "one level deep" and assert facts about what its render method returns, without worrying about the behavior of child components, which are not instantiated or rendered. This does not require a DOM.

		- [`shallowRenderer.render()`](#shallowrenderer.render)

Update docs for test utils add ons change #9331

Update docs for test utils add ons change #9331

Conversation

flarnie commented Apr 4, 2017

gaearon commented Apr 4, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

flarnie commented Apr 4, 2017

bvaughn left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bvaughn left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

bvaughn left a comment •

edited

Loading