# test-setup

## Purpose

`test-setup.ts` is the per-worker bootstrap file referenced by `vitest.config.ts`'s
`setupFiles`. It registers `@testing-library/jest-dom`'s custom matchers
(`toBeInTheDocument`, `toHaveAttribute`, `toHaveTextContent`, ...) onto Vitest's
`expect`, and it installs a global `afterEach` hook that runs
`@testing-library/react`'s `cleanup()` so each test starts with a fresh DOM tree.

The auto-cleanup that ships with `@testing-library/react` is gated on
`globalThis.afterEach` being present at import time, which is not the case under
Vitest's `globals: false` mode used by this package — hence the explicit hook here.

## Features

- Loads `@testing-library/jest-dom/vitest` (Vitest-native matcher extension).
- Installs an `afterEach` hook to call `cleanup()`.
- Runs once per worker process; idempotent across re-imports.

## Usage: Basic

The file is referenced by `vitest.config.ts`:

```ts
setupFiles: ["@suaveplan/testing/polyfills", "./src/test-setup.ts"],
```

Consumers do not import it directly.

## Usage: Advanced

To add another test-time global (e.g. a fake `localStorage` reset), extend this file:

```ts
import { afterEach } from "@suaveplan/testing/runner";
import { cleanup } from "@testing-library/react";

afterEach(() => {
    cleanup();
    localStorage.clear();
});
```

## API Reference

This module exports nothing. Side effects only.

## Implementation Notes

The `@testing-library/jest-dom/vitest` entry point automatically calls
`expect.extend(matchers)` for Vitest's `expect` singleton, which is why no explicit
`expect.extend` call is needed here. Importing the package root instead (without
`/vitest`) would attach the matchers to Jest's globals — wrong runtime for this
package, and a silent no-op under Vitest because the matchers never see the right
`expect`. The two import order also matters: jest-dom must be loaded before any
test file executes so the matcher patches are visible when the first test runs.
Listing this file second in `setupFiles` (after the polyfills bootstrap) preserves
that order.