From d3eebfac9a8c9c4296454ba7ffebafd39f2b82a3 Mon Sep 17 00:00:00 2001 From: Alex Krolick Date: Sat, 16 Feb 2019 15:24:34 -0800 Subject: [PATCH 1/2] Revert "Revert "feat(render): options.wrapper api + customRender usage"" This reverts commit c47aae0c8b92b71be73ac64cda0453f13c434642. --- docs/react-testing-library/api.md | 48 ++++++---- docs/react-testing-library/setup.md | 138 ++++++++++++++-------------- 2 files changed, 100 insertions(+), 86 deletions(-) diff --git a/docs/react-testing-library/api.md b/docs/react-testing-library/api.md index 1f381a7e9..107c2aed0 100644 --- a/docs/react-testing-library/api.md +++ b/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 - -
- -Expand to see documentation on the options +## `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,18 +73,26 @@ const { container } = render(, { }) ``` -**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. -
+### `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: @@ -88,7 +100,7 @@ The `render` method returns an object that has a few properties: 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 document. See [Queries](api-queries.md) for a complete list. @@ -222,6 +234,8 @@ fireEvent.click(getByText(/Click to increase/)) expect(firstRender).toMatchDiffSnapshot(asFragment()) ``` +--- + ## `cleanup` Unmounts React trees that were mounted with [render](#render). @@ -248,6 +262,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 diff --git a/docs/react-testing-library/setup.md b/docs/react-testing-library/setup.md index bd8d0fd3a..af59c5ba2 100644 --- a/docs/react-testing-library/setup.md +++ b/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 -
+Older versions of Jest + 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,17 +94,19 @@ 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 ( - {node} + {children} - , - options + ) } +const customRender = (ui, options) => + render(ui, { wrapper: AllTheProviders, ...options }) + // re-export everything export * from 'react-testing-library' @@ -105,9 +114,44 @@ export * from 'react-testing-library' 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. + +
+Workaround for Babel 6 + +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, +} +``` + +
+ +### 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(
{ui}
, 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).) - -
-Workaround - -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({node}) -} - -module.exports = { - ...rtl, - render: customRender, -} -``` - -
- ## Using without Jest If you're running your tests in the browser bundled with webpack (or similar) From 85a55a7c83e5ac4204ba6b97df2a0547d0bfed4a Mon Sep 17 00:00:00 2001 From: Alex Krolick Date: Sat, 16 Feb 2019 15:35:43 -0800 Subject: [PATCH 2/2] fix(render): default is document.body --- docs/react-testing-library/api.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/react-testing-library/api.md b/docs/react-testing-library/api.md index 107c2aed0..6daaa99e6 100644 --- a/docs/react-testing-library/api.md +++ b/docs/react-testing-library/api.md @@ -100,7 +100,8 @@ The `render` method returns an object that has a few properties: 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 document. +first argument bound to the [baseElement](#baseelement), which defaults to +`document.body`. See [Queries](api-queries.md) for a complete list.