@baselane/packs 0.1.4 → 0.1.5

package/packs/typescript-rules/rendered/.claude/skills/react-testing/SKILL.md

@@ -0,0 +1,422 @@
+---
+name: react-testing
+description: Use when writing or fixing tests for React components, hooks, or pages — React Testing Library query priority, userEvent, async assertions, MSW network mocking, accessibility assertions with axe, and the RTL-vs-Playwright decision boundary.
+---
+
+# React Testing
+
+Comprehensive React testing patterns for behavior-focused component tests, custom hook tests, accessibility assertions, and network-level mocking.
+
+## When to Activate
+
+- Writing tests for React components, custom hooks, or pages
+- Adding test coverage to legacy untested components
+- Migrating from Enzyme or class-component-era patterns to React Testing Library
+- Setting up Vitest or Jest for a new React project
+- Mocking HTTP requests in tests
+- Asserting accessibility violations
+- Deciding which tests belong in RTL vs Playwright Component Testing vs full E2E
+
+## Core Principle
+
+Test what the user sees and does, not implementation details.
+
+A test should:
+
+- Render the component with the same providers it has in production
+- Interact with it via accessible queries (role, label) and `userEvent`
+- Assert visible output and observable side effects (callback fired, request sent)
+
+A test should NOT:
+
+- Inspect component state, props passed to children, or which hooks were called
+- Mock React itself or framework hooks
+- Assert on the number of renders or DOM structure beyond what affects users
+
+## Library Choice
+
+| Runner | When | Note |
+|---|---|---|
+| **Vitest** | Vite, Remix, modern setups | Faster, native ESM, Jest-compatible API |
+| **Jest** | Next.js, CRA, established repos | Default for many React projects |
+| **Playwright Component Testing** | Real browser engine needed | Use when JSDOM lacks the required feature |
+| **Cypress Component Testing** | Real browser, Cypress already in use | Alternative to Playwright CT |
+
+Pick one. Do not run RTL + Vitest AND Playwright CT in the same repo unless you have a clear lane separation.
+
+## Query Priority
+
+React Testing Library exposes queries in three tiers — use top-down:
+
+1. **Accessible to everyone**: `getByRole`, `getByLabelText`, `getByPlaceholderText`, `getByText`, `getByDisplayValue`
+2. **Semantic**: `getByAltText`, `getByTitle`
+3. **Test IDs (escape hatch)**: `getByTestId`
+
+```tsx
+// Best
+screen.getByRole("button", { name: /save/i });
+
+// OK for inputs
+screen.getByLabelText("Email");
+
+// Last resort
+screen.getByTestId("save-btn");
+```
+
+Variants:
+
+- `getBy*` — throws if no match
+- `queryBy*` — returns `null` (use for "assert absence")
+- `findBy*` — async, returns a Promise (use for elements that appear after async work)
+
+## User Interaction with `userEvent`
+
+```tsx
+import userEvent from "@testing-library/user-event";
+
+test("submits the form", async () => {
+  const user = userEvent.setup();
+  const onSubmit = vi.fn();
+  render(<UserForm onSubmit={onSubmit} />);
+
+  await user.type(screen.getByLabelText("Email"), "user@example.com");
+  await user.click(screen.getByRole("button", { name: /save/i }));
+
+  expect(onSubmit).toHaveBeenCalledWith({ email: "user@example.com" });
+});
+```
+
+- Always `await` userEvent calls
+- Call `userEvent.setup()` once per test, reuse the returned `user`
+- `userEvent` simulates a real browser sequence; `fireEvent` dispatches a single synthetic event — prefer `userEvent`
+
+## Async Patterns
+
+```tsx
+// Element that appears after async work
+expect(await screen.findByText("Loaded")).toBeInTheDocument();
+
+// Side effect assertion
+await waitFor(() => expect(saveSpy).toHaveBeenCalled());
+
+// Element that should disappear
+await waitForElementToBeRemoved(() => screen.queryByText("Loading"));
+```
+
+Never `setTimeout` + assertion — flaky. Use the matchers above.
+
+## Network Mocking with MSW
+
+Mock Service Worker mocks at the network layer. The component, hooks, and fetch library all behave exactly as in production.
+
+### Setup
+
+```ts
+// test/setup.ts
+import { setupServer } from "msw/node";
+import { http, HttpResponse } from "msw";
+
+export const handlers = [
+  http.get("/api/users/:id", ({ params }) =>
+    HttpResponse.json({ id: params.id, name: "Alice" }),
+  ),
+  http.post("/api/users", async ({ request }) => {
+    const body = await request.json();
+    return HttpResponse.json({ id: "new-id", ...body }, { status: 201 });
+  }),
+];
+
+export const server = setupServer(...handlers);
+
+beforeAll(() => server.listen({ onUnhandledRequest: "error" }));
+afterEach(() => server.resetHandlers());
+afterAll(() => server.close());
+```
+
+Configure `onUnhandledRequest: "error"` so any unmocked request fails the test loudly — silent passes are worse than red.
+
+### Per-test override
+
+```tsx
+test("renders error on 500", async () => {
+  server.use(
+    http.get("/api/users/:id", () => new HttpResponse(null, { status: 500 })),
+  );
+  render(<UserPage id="1" />);
+  expect(await screen.findByText(/something went wrong/i)).toBeInTheDocument();
+});
+```
+
+## Provider Wrapping
+
+Wrap providers once in a `test-utils.tsx`:
+
+```tsx
+// test-utils.tsx
+import { render, RenderOptions } from "@testing-library/react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+export function renderWithProviders(
+  ui: React.ReactElement,
+  options?: RenderOptions,
+) {
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+
+  return render(
+    <QueryClientProvider client={queryClient}>
+      <ThemeProvider theme={lightTheme}>
+        <MemoryRouter>{ui}</MemoryRouter>
+      </ThemeProvider>
+    </QueryClientProvider>,
+    options,
+  );
+}
+
+export * from "@testing-library/react";
+```
+
+Then `import { renderWithProviders, screen } from "test-utils"` in every test file.
+
+## Custom Hook Testing
+
+```tsx
+import { renderHook, act } from "@testing-library/react";
+
+test("useCounter increments and decrements", () => {
+  const { result } = renderHook(() => useCounter(0));
+
+  expect(result.current.count).toBe(0);
+
+  act(() => result.current.increment());
+  expect(result.current.count).toBe(1);
+
+  act(() => result.current.decrement());
+  expect(result.current.count).toBe(0);
+});
+
+test("useCounter accepts initial value", () => {
+  const { result } = renderHook(() => useCounter(10));
+  expect(result.current.count).toBe(10);
+});
+
+test("useUser fetches user data", async () => {
+  // Instantiate QueryClient ONCE per test outside the wrapper so it survives re-renders.
+  // Creating it inside the wrapper closure resets cache state on every render, producing flaky tests.
+  const queryClient = new QueryClient({
+    defaultOptions: { queries: { retry: false } },
+  });
+  const wrapper = ({ children }: { children: React.ReactNode }) => (
+    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+  );
+
+  const { result } = renderHook(() => useUser("1"), { wrapper });
+
+  await waitFor(() => expect(result.current.isSuccess).toBe(true));
+  expect(result.current.data).toEqual({ id: "1", name: "Alice" });
+});
+```
+
+- Wrap state-changing calls in `act`
+- Test through the hook's public API only
+- For hooks that use context, pass a `wrapper`
+
+## Accessibility Assertions
+
+```tsx
+import { axe, toHaveNoViolations } from "jest-axe"; // or vitest-axe
+expect.extend(toHaveNoViolations);
+
+test("UserCard has no a11y violations", async () => {
+  const { container } = render(<UserCard user={mockUser} />);
+  expect(await axe(container)).toHaveNoViolations();
+});
+```
+
+Run axe in component tests for every interactive component. Catches:
+
+- Missing labels on form inputs
+- Invalid ARIA usage
+- Poor color contrast (limited — JSDOM has no real CSS engine, so this works for inline styles only; visual contrast belongs in Playwright)
+- Missing alt text on images
+- Heading order violations
+
+Cross-link: [skills/accessibility/SKILL.md](../accessibility/SKILL.md) for the broader a11y testing playbook.
+
+## When NOT to Use Snapshot Tests
+
+Snapshots of rendered output:
+
+- Break on every styling change
+- Get rubber-stamped during review
+- Test implementation detail (DOM structure), not behavior
+
+Acceptable snapshot uses:
+
+- Pure data serialization functions (`formatInvoice(invoice)` -> stable string)
+- Generated config files (e.g., webpack config output)
+
+For visual regression on components, use Playwright/Cypress screenshots or Percy/Chromatic — actual visual diffs, not DOM strings.
+
+## When to Reach for Playwright / Cypress
+
+JSDOM (used by Vitest/Jest) cannot:
+
+- Render real layout (flexbox, grid, viewport queries)
+- Run native browser animation, CSS transitions
+- Test scrolling behavior, drag-and-drop, paste from clipboard
+- Handle iframes, popups, downloads, cross-origin flows
+- Run real network in a controlled environment with full DevTools support
+
+For any of those, use Playwright Component Testing (component test in real browser) or full E2E. See [e2e-testing skill](../e2e-testing/SKILL.md).
+
+Decision boundary:
+
+- A hook, a presentational component, a form with logic -> RTL
+- A component whose layout matters or that uses browser APIs not in JSDOM -> Playwright CT
+- A full user flow across multiple pages -> Playwright/Cypress E2E
+
+## Coverage Targets
+
+| Layer | Target |
+|---|---|
+| Pure utilities | >=90% |
+| Custom hooks | >=85% |
+| Presentational components | >=80% — behavior, not lines |
+| Container components | >=70% — golden paths + error states |
+| Pages | E2E covered separately; smoke test minimum |
+
+Configure via `vitest.config.ts` / `jest.config.js`:
+
+```ts
+// vitest.config.ts
+test: {
+  coverage: {
+    provider: "v8",
+    reporter: ["text", "html", "lcov"],
+    thresholds: {
+      lines: 80,
+      functions: 80,
+      branches: 70,
+      statements: 80,
+    },
+  },
+}
+```
+
+## Anti-Patterns
+
+- `container.querySelector("...")` — bypasses accessibility queries, lets tests pass when real users would fail
+- Asserting on number of renders — implementation detail
+- `jest.mock("react", ...)` — never mock React. Refactor the component instead
+- Mocking child components by default — tests the integration, not isolation. Mock only when the child has heavy side effects
+- Ignoring `act()` warnings — they signal real bugs (state update after unmount, missing async wrapping)
+- Sharing mutable state across tests — flakes when test order changes
+- Tests that pass with `it.skip()` removed — your test does not actually assert what you think
+
+## TDD Workflow
+
+```
+RED     -> Write failing test for the next requirement
+GREEN   -> Write minimal component code to pass
+REFACTOR -> Improve the component, tests stay green
+REPEAT  -> Next requirement
+```
+
+For new components:
+
+1. Define the component's prop type and signature
+2. Write the first test for the simplest case
+3. Verify it fails for the right reason
+4. Implement just enough to pass
+5. Add the next test case
+6. Refactor when the third similar test reveals a pattern
+
+## Test Commands
+
+```bash
+# Vitest
+vitest                            # watch
+vitest run                        # one-shot
+vitest run --coverage             # with coverage
+vitest run path/to/file.test.tsx  # single file
+
+# Jest
+jest --watch
+jest --coverage
+jest path/to/file.test.tsx
+
+# CI mode
+CI=true vitest run --coverage
+```
+
+## Related
+
+- Rules: [rules/react/testing.md](../../rules/react/testing.md)
+- Skills: [react-patterns](../react-patterns/SKILL.md), [accessibility](../accessibility/SKILL.md), [e2e-testing](../e2e-testing/SKILL.md), [tdd-workflow](../tdd-workflow/SKILL.md)
+- Agents: `react-reviewer` (reviews test quality during code review), `tdd-guide` (enforces TDD process)
+- Commands: `/react-test`, `/react-review`
+
+## Examples
+
+### Form submission with MSW and userEvent
+
+```tsx
+test("submits user form and shows success", async () => {
+  server.use(
+    http.post("/api/users", () =>
+      HttpResponse.json({ id: "1", name: "Alice" }, { status: 201 }),
+    ),
+  );
+
+  const user = userEvent.setup();
+  renderWithProviders(<UserForm />);
+
+  await user.type(screen.getByLabelText("Name"), "Alice");
+  await user.type(screen.getByLabelText("Email"), "alice@example.com");
+  await user.click(screen.getByRole("button", { name: /save/i }));
+
+  expect(await screen.findByText(/saved successfully/i)).toBeInTheDocument();
+});
+```
+
+### Testing an error boundary
+
+```tsx
+function Broken() {
+  throw new Error("boom");
+}
+
+test("error boundary renders fallback", () => {
+  // Suppress React's console.error noise for the expected throw, then restore so
+  // the spy does not leak across tests and hide real errors elsewhere.
+  const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+  try {
+    render(
+      <ErrorBoundary fallback={<div>Something went wrong</div>}>
+        <Broken />
+      </ErrorBoundary>,
+    );
+
+    expect(screen.getByText("Something went wrong")).toBeInTheDocument();
+  } finally {
+    errorSpy.mockRestore();
+  }
+});
+```
+
+### Testing a Suspense boundary
+
+```tsx
+test("shows loading then content", async () => {
+  renderWithProviders(
+    <Suspense fallback={<div>Loading...</div>}>
+      <UserDetail id="1" />
+    </Suspense>,
+  );
+
+  expect(screen.getByText("Loading...")).toBeInTheDocument();
+  expect(await screen.findByText("Alice")).toBeInTheDocument();
+});
+```