Docs for onCaughtError, onRecoverableError and how to test error boundaries

Author: eps1lon

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)

docs/react-testing-library/faq.mdx

@@ -81,6 +81,54 @@ as part of the `change` method call.
 
 <details>
 
+<summary>How do I test error boundaries</summary>
+
+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 <div>Something went wrong</div>
+    }
+    return this.props.children
+  }
+}
+
+test('error boundary catches error', () => {
+  const {container} = render(
+    <ErrorBoundary>
+      <BrokenComponent />
+    </ErrorBoundary>,
+  )
+  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(<App />, {onCaughtError: () => {}})`
+`onCaughtError` is not supported in React 18.
+:::
+
+</details>
+
+<details>
+
 <summary>Can I write unit tests with this library?</summary>
 
 Definitely yes! You can write unit and integration tests with this library. See