From f398603872af30094a6117bc05aa766e280e88c2 Mon Sep 17 00:00:00 2001 From: Maciej Jastrzebski Date: Mon, 19 Sep 2022 18:01:22 +0200 Subject: [PATCH 1/6] docs: document `render` options --- website/docs/API.md | 41 +++++++++++++++++++++++++++++++++++------ 1 file changed, 35 insertions(+), 6 deletions(-) diff --git a/website/docs/API.md b/website/docs/API.md index f297591fe..a3077f28d 100644 --- a/website/docs/API.md +++ b/website/docs/API.md @@ -6,6 +6,10 @@ title: API ### Table of contents: - [`render`](#render) + - [`render` options](#render-options) + - [`wrapper` option](#wrapper-option) + - [`createNodeMock` option](#createnodemock-option) + - [`unstable_validateStringsRenderedWithinText` option](#unstable_validatestringsrenderedwithintext-option) - [`...queries`](#queries) - [Example](#example) - [`update`](#update) @@ -53,12 +57,7 @@ Defined as: ```jsx function render( component: React.Element, - options?: { - /* A React Component that renders `component` as children */ - wrapper?: React.ComponentType, - /* You won't often use this, but it's helpful when testing refs */ - createNodeMock: (element: React.Element) => any, - } + options?: RenderOptions, ): RenderResult {} ``` @@ -86,6 +85,36 @@ Latest `render` result is kept in [`screen`](#screen) variable that can be impor Using `screen` instead of destructuring `render` result is recommended approach. See [this article](https://kentcdodds.com/blog/common-mistakes-with-react-testing-library#not-using-screen) from Kent C. Dodds for more details. ::: +### `render` options + +The behavior of `render` method can be customized by passing various options: + +#### `wrapper` option + +```ts +wrapper?: React.ComponentType, +``` + +This options allows you to wrap tested component, passed as the first option to the `render()` function, in additional wrapper component. This is most useful for creating reusable custom render functions for common data providers. + +#### `createNodeMock` option + +```ts +createNodeMock: (element: React.Element) => any, +``` + +This options allows you to pass `createNodeMock` option to `ReactTestRenderer.create()` method in order to allow for custom mock refs. You can learn more about this options from [React Test Renderer documentation]([TestRenderer.create()](https://reactjs.org/docs/test-renderer.html#ideas)). + +#### `unstable_validateStringsRenderedWithinText` option + +This experimental options allows you to replicate React Native behavior of throwing `Invariant Violation: Text strings must be rendered within a component` error when you try to render `string` value under component different than `` component, e.g. under ``. + +This check is not enforced by React Test Renderer and hence by default React Native Testing Library also does not check this. That might result in runtime errors when running your code on a device, while the code works without errors in tests. + +:::note +This options is experimental, in some cases it might not work as intended, and its behavior might change without observing [SemVer](https://semver.org/) requirements for breaking changes. +::: + ### `...queries` The most important feature of `render` is providing a set of helpful queries that allow you to find certain elements in the view hierarchy. From 417370178998af72dd6b67d68a83fa65f02c63ea Mon Sep 17 00:00:00 2001 From: Maciej Jastrzebski Date: Mon, 19 Sep 2022 18:05:12 +0200 Subject: [PATCH 2/6] docs: tweaks --- website/docs/API.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/website/docs/API.md b/website/docs/API.md index a3077f28d..e5ebd8f2e 100644 --- a/website/docs/API.md +++ b/website/docs/API.md @@ -100,13 +100,17 @@ This options allows you to wrap tested component, passed as the first option to #### `createNodeMock` option ```ts -createNodeMock: (element: React.Element) => any, +createNodeMock?: (element: React.Element) => any, ``` -This options allows you to pass `createNodeMock` option to `ReactTestRenderer.create()` method in order to allow for custom mock refs. You can learn more about this options from [React Test Renderer documentation]([TestRenderer.create()](https://reactjs.org/docs/test-renderer.html#ideas)). +This options allows you to pass `createNodeMock` option to `ReactTestRenderer.create()` method in order to allow for custom mock refs. You can learn more about this options from [React Test Renderer documentation](https://reactjs.org/docs/test-renderer.html#ideas). #### `unstable_validateStringsRenderedWithinText` option +```ts +unstable_validateStringsRenderedWithinText?: boolean; +``` + This experimental options allows you to replicate React Native behavior of throwing `Invariant Violation: Text strings must be rendered within a component` error when you try to render `string` value under component different than `` component, e.g. under ``. This check is not enforced by React Test Renderer and hence by default React Native Testing Library also does not check this. That might result in runtime errors when running your code on a device, while the code works without errors in tests. From 44b1b4c28dd55a19d88f4597f7d803ab69c1a37b Mon Sep 17 00:00:00 2001 From: Maciej Jastrzebski Date: Mon, 19 Sep 2022 22:14:53 +0200 Subject: [PATCH 3/6] Update website/docs/API.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Michał Pierzchała --- website/docs/API.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/API.md b/website/docs/API.md index e5ebd8f2e..4df4e83e1 100644 --- a/website/docs/API.md +++ b/website/docs/API.md @@ -87,7 +87,7 @@ Using `screen` instead of destructuring `render` result is recommended approach. ### `render` options -The behavior of `render` method can be customized by passing various options: +The behavior of `render` method can be customized by passing various options as a second argument of `RenderOptions` type: #### `wrapper` option From b1be9226b8038d5c560b18e7ffecaef99af01f38 Mon Sep 17 00:00:00 2001 From: Maciej Jastrzebski Date: Mon, 19 Sep 2022 22:15:01 +0200 Subject: [PATCH 4/6] Update website/docs/API.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Michał Pierzchała --- website/docs/API.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/API.md b/website/docs/API.md index 4df4e83e1..e3130b4e3 100644 --- a/website/docs/API.md +++ b/website/docs/API.md @@ -95,7 +95,7 @@ The behavior of `render` method can be customized by passing various options as wrapper?: React.ComponentType, ``` -This options allows you to wrap tested component, passed as the first option to the `render()` function, in additional wrapper component. This is most useful for creating reusable custom render functions for common data providers. +This options allows you to wrap tested component, passed as the first option to the `render()` function, in additional wrapper component. This is most useful for creating reusable custom render functions for common React Context providers. #### `createNodeMock` option From adc4aec72f5f8d65bba48c648d1c2fa57a3645ad Mon Sep 17 00:00:00 2001 From: Maciej Jastrzebski Date: Mon, 19 Sep 2022 22:15:11 +0200 Subject: [PATCH 5/6] Update website/docs/API.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Michał Pierzchała --- website/docs/API.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/API.md b/website/docs/API.md index e3130b4e3..7e1ba75fe 100644 --- a/website/docs/API.md +++ b/website/docs/API.md @@ -111,7 +111,7 @@ This options allows you to pass `createNodeMock` option to `ReactTestRenderer.cr unstable_validateStringsRenderedWithinText?: boolean; ``` -This experimental options allows you to replicate React Native behavior of throwing `Invariant Violation: Text strings must be rendered within a component` error when you try to render `string` value under component different than `` component, e.g. under ``. +This **experimental** option allows you to replicate React Native behavior of throwing `Invariant Violation: Text strings must be rendered within a component` error when you try to render `string` value under components different than ``, e.g. under ``. This check is not enforced by React Test Renderer and hence by default React Native Testing Library also does not check this. That might result in runtime errors when running your code on a device, while the code works without errors in tests. From 3264fe17b5e39ab1bfe31262012be695dad1fc38 Mon Sep 17 00:00:00 2001 From: Maciej Jastrzebski Date: Mon, 19 Sep 2022 22:19:21 +0200 Subject: [PATCH 6/6] docs: tweaks --- website/docs/API.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/website/docs/API.md b/website/docs/API.md index 7e1ba75fe..12487b519 100644 --- a/website/docs/API.md +++ b/website/docs/API.md @@ -111,14 +111,14 @@ This options allows you to pass `createNodeMock` option to `ReactTestRenderer.cr unstable_validateStringsRenderedWithinText?: boolean; ``` -This **experimental** option allows you to replicate React Native behavior of throwing `Invariant Violation: Text strings must be rendered within a component` error when you try to render `string` value under components different than ``, e.g. under ``. - -This check is not enforced by React Test Renderer and hence by default React Native Testing Library also does not check this. That might result in runtime errors when running your code on a device, while the code works without errors in tests. - :::note This options is experimental, in some cases it might not work as intended, and its behavior might change without observing [SemVer](https://semver.org/) requirements for breaking changes. ::: +This **experimental** option allows you to replicate React Native behavior of throwing `Invariant Violation: Text strings must be rendered within a component` error when you try to render `string` value under components different than ``, e.g. under ``. + +This check is not enforced by React Test Renderer and hence by default React Native Testing Library also does not check this. That might result in runtime errors when running your code on a device, while the code works without errors in tests. + ### `...queries` The most important feature of `render` is providing a set of helpful queries that allow you to find certain elements in the view hierarchy.