diff --git a/docs/react-testing-library/api.mdx b/docs/react-testing-library/api.mdx index a6a969ebb..06149fed6 100644 --- a/docs/react-testing-library/api.mdx +++ b/docs/react-testing-library/api.mdx @@ -12,6 +12,8 @@ as these methods: - [`baseElement`](#baseelement) - [`hydrate`](#hydrate) - [`legacyRoot`](#legacyroot) + - [`onCaughtError`](#oncaughterror) + - [`onRecoverableError`](#onrecoverableerror) - [`wrapper`](#wrapper) - [`queries`](#queries) - [`render` Result](#render-result) @@ -27,6 +29,8 @@ as these methods: - [`renderHook`](#renderhook) - [`renderHook` Options](#renderhook-options) - [`initialProps`](#initialprops) + - [`onCaughtError`](#oncaughterror) + - [`onRecoverableError`](#onrecoverableerror) - [`wrapper`](#wrapper-1) - [`renderHook` Result](#renderhook-result) - [`result`](#result) @@ -120,6 +124,16 @@ React 17 (i.e. [`ReactDOM.render`](https://react.dev/reference/react-dom/render)) then you should enable this option by setting `legacyRoot: true`. +### `onCaughtError` + +Callback called when React catches an error in an Error Boundary. +Behaves the same as [`onCaughtError` in `ReactDOMClient.createRoot`](https://react.dev/reference/react-dom/client/createRoot#parameters). + +### `onRecoverableError` + +Callback called when React automatically recovers from errors. +Behaves the same as [`onRecoverableError` in `ReactDOMClient.createRoot`](https://react.dev/reference/react-dom/client/createRoot#parameters). + ### `wrapper` Pass a React Component as the `wrapper` option to have it rendered around the @@ -403,6 +417,16 @@ test('returns logged in user', () => { > } > ``` +### `onCaughtError` + +Callback called when React catches an error in an Error Boundary. +Behaves the same as [`onCaughtError` in `ReactDOMClient.createRoot`](https://react.dev/reference/react-dom/client/createRoot#parameters). + +### `onRecoverableError` + +Callback called when React automatically recovers from errors. +Behaves the same as [`onRecoverableError` in `ReactDOMClient.createRoot`](https://react.dev/reference/react-dom/client/createRoot#parameters). + ### `renderHook` Options `wrapper` See [`wrapper` option for `render`](#wrapper) diff --git a/docs/react-testing-library/faq.mdx b/docs/react-testing-library/faq.mdx index 1d93c926d..b04fb46a2 100644 --- a/docs/react-testing-library/faq.mdx +++ b/docs/react-testing-library/faq.mdx @@ -81,6 +81,54 @@ as part of the `change` method call.
+How do I test error boundaries + +To test if an error boundary successfully catches an error, you should make sure that if the fallback of the boundary is displayed when a child threw. + +Here's an example of how you can test an error boundary: + +```jsx +import React from 'react' +import {render, screen} from '@testing-library/react' + +class ErrorBoundary extends React.Component { + state = {error: null} + static getDerivedStateFromError(error) { + return {error} + } + render() { + const {error} = this.state + if (error) { + return
Something went wrong
+ } + return this.props.children + } +} + +test('error boundary catches error', () => { + const {container} = render( + + + , + ) + expect(container.textContent).toEqual('Something went wrong.') +}) + +If the error boundary did not catch the error, the test would fail since the `render` call would throw the error the Component produced. + + +:::info +React 18 will call `console.error` with an extended error message. +React 19 will call `console.warn` with an extended error message. + +To disable the additional `console.warn` call in React 19, you can provide a custom `onCaughtError` callback e.g. `render(, {onCaughtError: () => {}})` +`onCaughtError` is not supported in React 18. +::: + +
+ +
+ Can I write unit tests with this library? Definitely yes! You can write unit and integration tests with this library. See