Home › Testing › Vitest unit testing AGENTS.md

Vitest unit testing AGENTS.md

AGENTS.md for unit and component tests with Vitest 3 and Testing Library in Vite/TypeScript projects.

AGENTS.mdTesting

How to use

Save this as AGENTS.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

# AGENTS.md: Testing with Vitest

## Commands
- `npx vitest run` (CI) · `npx vitest <pattern>` (watch) · `npx vitest run --coverage`

## Where and how
- Tests sit next to code: `foo.ts` -> `foo.test.ts`. Component tests use `@testing-library/react` (or `/vue`, `/svelte`) with `@testing-library/user-event`.
- Arrange / act / assert, one behavior per test, and names that read as a sentence: `it('shows an error when the email is invalid')`.
- Query the DOM like a user: `getByRole`, `getByLabelText`. Use `findBy*` for async UI; avoid `container.querySelector`.
- Interact with `const user = userEvent.setup(); await user.click(...)`, not `fireEvent`.
- Mock at the boundary: network with MSW (`msw/node`), modules with `vi.mock` only for things you don't own. Reset with `vi.restoreAllMocks()` in `afterEach` (or `restoreMocks: true` in config).
- Time: `vi.useFakeTimers()` + `vi.setSystemTime()`; restore real timers after.
- Use `test.each` for tables of inputs.
- Snapshot tests only for small, stable output; review snapshot diffs instead of blindly updating with `-u`.

## Rules for agents
- When fixing a bug, write a failing test first, then the fix.
- Never delete, skip (`.skip`), or weaken an assertion to make a test pass. If a test looks wrong, say so.
- Don't test implementation details (internal state, private functions).

## Done
`npx vitest run` passes and new code paths have tests.