Cursor Rule: Testing Conventions

Auto-attached .cursor/rules/testing.mdc that loads when test files are in context and fixes naming, structure, mocking, and flakiness rules.

License: CC0-1.0 · By waxmark · v1 · 2026-11-02

Share on X

Add a trust badge to your README

[![Waxmark](https://waxmark.app/api/badge/cursor-rule-testing-conventions)](https://waxmark.app/items/cursor-rule-testing-conventions/scan)
Report
---
description: Conventions for unit, integration, and end-to-end tests
globs: **/*.test.ts, **/*.test.tsx, **/*.spec.ts, **/*.spec.tsx, e2e/**/*.ts, tests/**/*
alwaysApply: false
---

# Testing conventions

Runner: {{TEST_RUNNER}}. Run a single file with `{{TEST_COMMAND}} <path>` while iterating and the whole suite with `{{TEST_COMMAND}}` before finishing. E2E: `{{E2E_COMMAND}}`.

## Placement and naming

- Unit tests sit next to the source as `<name>.test.ts(x)`. Integration tests go in `tests/integration/`. E2E specs go in `e2e/<flow>.spec.ts`.
- `describe` names the unit under test (`describe('parseConfig')`); `it`/`test` names the behavior as a sentence: `it('returns defaults when the file is missing')`. No "should".
- One behavior per test. If a test has more than one logical assertion group, split it.
- Test data builders live in `tests/factories/`; use them instead of inline object literals longer than three fields.

## Structure

- Arrange, act, assert, separated by a blank line. No logic (loops, conditionals) inside a test body; use `test.each` for tables.
- Prefer `toEqual`/`toStrictEqual` on whole objects over several `toBe` assertions on fields.
- Assert on observable behavior (return values, rendered output, calls to collaborators), not on private state or implementation order.
- A new test must fail before the fix and pass after. When fixing a bug, write the failing test first and keep it.

## Mocking

- Mock at module boundaries we own (`vi.mock('@/lib/api/client')`), never third-party internals or `fetch` directly.
- Prefer hand-written fakes to auto-mocks when the collaborator has behavior (a queue, a repository). Put them in `tests/fakes/`.
- Reset mocks between tests (`vi.restoreAllMocks()` in `afterEach`, or `restoreMocks: true` in config). No shared mutable state across tests.
- Time: use `vi.useFakeTimers()` and `vi.setSystemTime(new Date('2026-01-01T00:00:00Z'))`; never depend on the real clock.
- Randomness: inject the RNG or seed it; never assert on unseeded random output.

## UI tests

- `@testing-library`: query by role first (`getByRole('button', { name: /save/i })`), then label, then text. `getByTestId` only when no accessible query exists, and add the `data-testid` to the component in the same change.
- `userEvent` over `fireEvent`. Await every `userEvent` call.
- Use `findBy*`/`await screen.findByText` for async appearance; never `await new Promise(r => setTimeout(r, n))`.

## E2E (Playwright)

- One spec per user flow. Use `page.getByRole`/`getByLabel`; avoid CSS and XPath selectors.
- No `page.waitForTimeout`. Use `await expect(locator).toBeVisible()` and `page.waitForURL`.
- Authenticate once via a `storageState` fixture, not through the login form in every test.
- Tag slow or external-dependency tests with `test.slow()` or a `@external` tag so CI can shard them.

## Do not

- Do not skip (`it.skip`, `test.only`) in committed code. Remove `only` before finishing.
- Do not increase timeouts to make a flaky test pass; find the race.
- Do not snapshot large DOM trees or JSON blobs; snapshot a focused subset or assert on fields.
- Do not delete or weaken an existing assertion to make a change pass without saying so.

## Coverage

Run the coverage command when you add a module and make sure new files are not at 0%. Do not chase a percentage; cover branches that matter.
Cursor Rule: Testing Conventions · Waxmark