feat(render): options.wrapper api + customRender usage (testing-library#39)

- Adds docs for render option "wrapper": testing-library/react-testing-library#303 - Reorganizes the API and Setup pages for rtl slightly to add better heading structure for the right navbar. Accidentally got remotes mixed up - this reverts the revert that prematurely merged the change. This reverts commit c47aae0.

Author: alexkrolick

docs/react-testing-library/api.md

@@ -6,6 +6,12 @@ title: API
 `react-testing-library` re-exports everything from `dom-testing-library` as well
 as these methods:
 
+- [`render`](#act)
+- [`cleanup`](#cleanup)
+- [`act`](#act)
+
+---
+
 ## `render`
 
 ```typescript
@@ -44,19 +50,17 @@ test('renders a message', () => {
 > The [cleanup](#cleanup) function should be called between tests to remove the
 > created DOM nodes and keep the tests isolated.
 
-### `render` Options
-
-<details>
-
-<summary>Expand to see documentation on the options</summary>
+## `render` Options
 
 You wont often need to specify options, but if you ever do, here are the
 available options which you could provide as a second argument to `render`.
 
-**container**: By default, `react-testing-library` will create a `div` and
-append that div to the `document.body` and this is where your react component
-will be rendered. If you provide your own HTMLElement `container` via this
-option, it will not be appended to the `document.body` automatically.
+### `container`
+
+By default, `react-testing-library` will create a `div` and append that div to
+the `document.body` and this is where your react component will be rendered. If
+you provide your own HTMLElement `container` via this option, it will not be
+appended to the `document.body` automatically.
 
 For Example: If you are unit testing a `tablebody` element, it cannot be a child
 of a `div`. In this case, you can specify a `table` as the render `container`.
@@ -69,26 +73,35 @@ const { container } = render(<TableBody {...props} />, {
 })
 ```
 
-**baseElement**: If the `container` is specified, then this defaults to that,
-otherwise this defaults to `document.documentElement`. This is used as the base
-element for the queries as well as what is printed when you use `debug()`.
+### `baseElement`
+
+If the `container` is specified, then this defaults to that, otherwise this
+defaults to `document.documentElement`. This is used as the base element for the
+queries as well as what is printed when you use `debug()`.
+
+### `hydrate`
 
-**hydrate**: If hydrate is set to true, then it will render with
+If hydrate is set to true, then it will render with
 [ReactDOM.hydrate](https://reactjs.org/docs/react-dom.html#hydrate). This may be
 useful if you are using server-side rendering and use ReactDOM.hydrate to mount
 your components.
 
-</details>
+### `wrapper`
 
----
+Pass a React Component as the `wrapper` option to have it rendered around the
+inner element. This is most useful for creating reusable custom render functions
+for common data providers. See [setup](setup.md#custom-render) for examples.
+
+## `render` Result
 
 The `render` method returns an object that has a few properties:
 
 ### `...queries`
 
 The most important feature of `render` is that the queries from
 [dom-testing-library](api-queries.md) are automatically returned with their
-first argument bound to the rendered container.
+first argument bound to the [baseElement](#baseelement), which defaults to
+`document.body`.
 
 See [Queries](api-queries.md) for a complete list.
 
@@ -222,6 +235,8 @@ fireEvent.click(getByText(/Click to increase/))
 expect(firstRender).toMatchDiffSnapshot(asFragment())
 ```
 
+---
+
 ## `cleanup`
 
 Unmounts React trees that were mounted with [render](#render).
@@ -248,6 +263,8 @@ that you configure your test framework to run a file before your tests which
 does this automatically. See the [setup](./setup) section for guidance on how to
 set up your framework.
 
+---
+
 ## `act`
 
 This is a light wrapper around the

docs/react-testing-library/setup.md

@@ -8,19 +8,22 @@ sidebar_label: Setup
 demonstrated in the example above). However, there are some things you can do
 when configuring your testing framework to reduce some boilerplate. In these
 docs we'll demonstrate configuring Jest, but you should be able to do similar
-things with any testing framework (react-testing-library does not require that
-you use Jest).
+things with [any testing framework](#using-without-jest) (react-testing-library
+does not require that you use Jest).
 
 ## Global Config
 
-There are several options you can add to your global test config that simplify
-the setup and teardown of tests in individual files. For example, you can ensure
-[`cleanup`](./api#cleanup) is called after each test and import additional
-assertions.
+Adding options to your global test config can simplify the setup and teardown of
+tests in individual files.
 
-To do this with Jest 24 and up, you can add the
+### Cleanup
+
+You can ensure [`cleanup`](./api#cleanup) is called after each test and import
+additional assertions by adding it to the setup configuration in Jest.
+
+In Jest 24 and up, add the
 [`setupFilesAfterEnv`](https://jestjs.io/docs/en/configuration.html#setupfilesafterenv-array)
-option to your Jest config.
+option to your Jest config:
 
 ```javascript
 // jest.config.js
@@ -33,10 +36,10 @@ module.exports = {
 }
 ```
 
-### Older versions of Jest
-
 <details>
 
+<summary>Older versions of Jest</summary>
+
 Jest versions 23 and below use the
 [`setupTestFrameworkScriptFile`](https://jestjs.io/docs/en/23.x/configuration#setuptestframeworkscriptfile-string)
 option in your Jest config instead of `setupFilesAfterEnv`. This setup file can
@@ -72,7 +75,11 @@ It's often useful to define a custom render method that includes things like
 global context providers, data stores, etc. To make this available globally, one
 approach is to define a utility file that re-exports everything from
 `react-testing-library`. You can replace react-testing-library with this file in
-all your imports.
+all your imports. See [below](#comfiguring-jest-with-test-utils) for a way to
+make your test util file accessible without using relative paths.
+
+The example below sets up data providers using the
+[`wrapper`](api.md#render-options) option to `render`.
 
 ```diff
 // my-component.test.js
@@ -87,27 +94,64 @@ import { ThemeProvider } from 'my-ui-lib'
 import { TranslationProvider } from 'my-i18n-lib'
 import defaultStrings from 'i18n/en-x-default'
 
-const customRender = (node, options) => {
- return render(
+const AllTheProviders = ({ children }) => {
+ return (
  <ThemeProvider theme="light">
  <TranslationProvider messages={defaultStrings}>
- {node}
+ {children}
  </TranslationProvider>
- </ThemeProvider>,
- options
+ </ThemeProvider>
  )
 }
 
+const customRender = (ui, options) =>
+ render(ui, { wrapper: AllTheProviders, ...options })
+
 // re-export everything
 export * from 'react-testing-library'
 
 // override render method
 export { customRender as render }
 ```
 
-To make this file accessible without using relative imports, add the folder
-containing the file to the Jest `moduleDirectories` option. Note: this will make
-_all_ the .js files in that directory importable without `../`.
+> **Note**
+>
+> Babel versions lower than 7 throw an error when trying to override the named
+> export in the example above. See
+> [#169](https://github.com/kentcdodds/react-testing-library/issues/169) and the
+> workaround below.
+
+<details>
+<summary>Workaround for Babel 6</summary>
+
+You can use CommonJS modules instead of ES modules, which should work in Node:
+
+```js
+// test-utils.js
+const rtl = require('react-testing-library')
+
+const customRender = (ui, options) =>
+ rtl.render(ui, {
+ myDefaultOption: 'something',
+ ...options,
+ })
+
+module.exports = {
+ ...rtl,
+ render: customRender,
+}
+```
+
+</details>
+
+### Configuring Jest with Test Utils
+
+To make your custom test file accessible in your Jest test files without using
+relative imports (`../../test-utils`), add the folder containing the file to the
+Jest `moduleDirectories` option.
+
+This will make all the `.js` files in the test-utils directory importable
+without `../`.
 
 ```diff
 // my-component.test.js
@@ -128,9 +172,11 @@ module.exports = {
 }
 ```
 
-If your project is based on top of Create React App, to make the file accessible
-without using relative imports, you just need to create a `.env` file in the
-root of your project with the following configuration:
+### Jest and Create React App
+
+If your project is based on top of Create React App, to make the `test-utils`
+file accessible without using relative imports, you just need to create a `.env`
+file in the root of your project with the following configuration:
 
 ```
 // Create React App project structure
@@ -151,54 +197,6 @@ $ app
 NODE_PATH=src/utils
 ```
 
-There is the case when you want to wrap your components in a `Provider`, this
-might cause conflicts when `rerender`ed. To achieve this, we suggest the
-`rerender` should be implemented the same way custom queries, by changing the
-return value of the customRender.
-
-```js
-// test-utils.js
-
-const customRender = (ui, options) => {
- const rendered = render(<div>{ui}</div>, options)
- return {
- ...rendered,
- rerender: newUi =>
- customRender(newUi, {
- container: rendered.container,
- baseElement: rendered.baseElement,
- }),
- }
-}
-```
-
-### Export Issue with Babel Versions Lower Than 7
-
-Babel versions lower than 7 throw an error when trying to override the named
-export in the example above. (See
-[#169](https://github.com/kentcdodds/react-testing-library/issues/169).)
-
-<details>
-<summary>Workaround</summary>
-
-You can use CommonJS modules instead of ES modules, which should work in Node:
-
-```js
-// test-utils.js
-const rtl = require('react-testing-library')
-
-const customRender = (node, options) => {
- return rtl.render(<Something>{node}</Something>)
-}
-
-module.exports = {
- ...rtl,
- render: customRender,
-}
-```
-
-</details>
-
 ## Using without Jest
 
 If you're running your tests in the browser bundled with webpack (or similar)