---
name: write-tests
description: Write tests for a specific file — unit and integration tests with Vitest, Testing Library, accessible queries, and AAA pattern.
disable-model-invocation: true
argument-hint: "[file-path]"
context: fork
agent: test-engineer
---

# Write Tests

Write comprehensive tests for `$ARGUMENTS`.

## Steps

1. **Read the target file** and understand:
   - What it does (component, service, utility, API handler)
   - Its dependencies and side effects
   - Edge cases and error paths

2. **Read project context:**
   - Check `RECOMMENDATIONS.md` for testing stack decisions
   - Look at existing test files for patterns and conventions
   - Check test config (vitest.config, playwright.config)

3. **Write tests following these rules:**

   **Structure:**
   - AAA pattern (Arrange → Act → Assert)
   - Behavior-focused names: `it('displays error when API fails')`
   - Group by concern: `describe('when user is logged in', ...)`
   - Co-locate with source file: `Component.test.tsx` next to `Component.tsx`

   **Queries (for React components):**
   - `getByRole` → `getByLabelText` → `getByText` → `getByTestId` (last resort)
   - Use `userEvent` over `fireEvent`

   **Mocking:**
   - MSW for HTTP APIs
   - `vi.mock()` only for third-party services
   - Real implementations for internal logic
   - Deterministic test data via factories

   **Coverage:**
   - Happy path
   - Error states
   - Empty/loading states
   - Edge cases (null, undefined, empty arrays, boundary values)
   - Accessibility: keyboard interaction, ARIA states

4. **No arbitrary waits** — use `waitFor`, `findBy`, or proper async handling.

5. **Output:** working test file, ready to run with `vitest`.