React Testing Library

# React Testing Library API Reference

## render()

```ts
import { render } from '@testing-library/react'

const result = render(ui, options?)
```

### Basic Usage

```tsx
import { render, screen } from "@testing-library/react";

test("renders greeting", () => {
  render(<Greeting name="World" />);
  expect(screen.getByText("Hello, World!")).toBeInTheDocument();
});
```

### Render Options

```ts
render(<Component />, {
  container: document.body.appendChild(document.createElement("div")),
  baseElement: document.body,
  hydrate: false,
  legacyRoot: false, // React 17 mode (not available in React 19+)
  wrapper: AllProviders,
  queries: { ...queries, ...customQueries },
  reactStrictMode: true,
  // React 19 error handlers
  onCaughtError: (error, errorInfo) => {},
  onRecoverableError: (error, errorInfo) => {},
});
```

| Option               | Description                                      |
| -------------------- | ------------------------------------------------ |
| `container`          | DOM element to render into                       |
| `baseElement`        | Element for queries (default: document.body)     |
| `hydrate`            | Use ReactDOM.hydrate for SSR                     |
| `legacyRoot`         | Use React 17 rendering (not in React 19+)        |
| `wrapper`            | Component to wrap around rendered element        |
| `queries`            | Custom queries to use                            |
| `reactStrictMode`    | Enable React StrictMode                          |
| `onCaughtError`      | Callback for errors caught by Error Boundary     |
| `onRecoverableError` | Callback for errors React automatically recovers |

### Render Result

```ts
const {
  container, // DOM container element
  baseElement, // Base element for queries
  debug, // console.log(prettyDOM())
  rerender, // Re-render with new props
  unmount, // Unmount component
  asFragment, // Get DocumentFragment snapshot
  ...queries // All query functions bound to baseElement
} = render(<Component />);
```

### React Error Handlers (v16.2.0+)

Handle errors in tests with React 19 error callbacks:

```tsx
test("catches error boundary errors", () => {
  const errors: Error[] = [];

  render(<ComponentWithErrorBoundary />, {
    onCaughtError: (error, errorInfo) => {
      errors.push(error);
      console.log("Caught:", error.message);
      console.log("Component stack:", errorInfo.componentStack);
    },
  });

  // Trigger error and verify
  fireEvent.click(screen.getByRole("button", { name: /throw/i }));
  expect(errors).toHaveLength(1);
});

test("handles recoverable errors", () => {
  const recoverableErrors: Error[] = [];

  render(<HydratedComponent />, {
    hydrate: true,
    onRecoverableError: (error, errorInfo) => {
      recoverableErrors.push(error);
    },
  });

  expect(recoverableErrors).toHaveLength(0);
});
```

---

## screen

Pre-bound queries for document.body:

```ts
import { render, screen } from "@testing-library/react";

render(<Component />);

// All queries available
screen.getByRole("button");
screen.queryByText("Loading");
screen.findByLabelText("Email");

// Debug
screen.debug();
screen.debug(screen.getByRole("button"));

// Playground URL
screen.logTestingPlaygroundURL();
```

---

## rerender()

Update props without remounting:

```tsx
const { rerender } = render(<Counter count={1} />);
expect(screen.getByText("Count: 1")).toBeInTheDocument();

rerender(<Counter count={2} />);
expect(screen.getByText("Count: 2")).toBeInTheDocument();
```

---

## unmount()

```ts
const { unmount } = render(<Component />);
unmount();
// Component is now unmounted, container is empty
```

---

## asFragment()

Create snapshot of current DOM state:

```tsx
const { asFragment } = render(<Component />);

const firstRender = asFragment();
fireEvent.click(screen.getByRole("button"));

// Snapshot diff
expect(firstRender).toMatchDiffSnapshot(asFragment());
```

---

## cleanup()

Unmounts all rendered components. Called automaticall