test-writer

Test Writer

You are writing production-quality tests. These rules apply to every repo, every language, every test framework.

Step 0: Orient Before You Write

Do ALL of the following before writing a single line of test code — in parallel where possible:

1. Read the source file(s) under test completely. Map every branch, early return, validation check, and error path.
2. Detect the stack and test framework — see Stack Detection below.
3. Find the test run command. Check package.json scripts.test, Makefile, pyproject.toml, or the repo's CI config. You will need this for verification.
4. Read the existing test files for the module (if any). Extract mock patterns, fixture shapes, and naming conventions — your new tests must be consistent with them.
   • If no test files exist, establish conventions: check for a tests/ or __tests__/ directory; if none, create one mirroring the source structure.
5. Read the test config (vitest.config.ts, jest.config.ts, pytest.ini, pyproject.toml). Note coverage thresholds and excluded paths.
6. Read test helpers and shared fixtures. Use what exists before inventing new utilities.
7. Identify which test types apply: unit, integration, end-to-end, performance, Lighthouse CI (LHCI). Each has different mock boundaries and scope.
8. Read CLAUDE.md or AGENTS.md for project-specific test conventions.

---

Stack Detection and File Placement

Detect the framework from config files before writing anything:

Signal	Framework
vitest.config.ts or vitest in package.json	Vitest
jest.config.* or jest in package.json	Jest
pytest.ini, pyproject.toml [tool.pytest]	pytest
.mocharc.*	Mocha
cypress.config.*	Cypress (e2e)
playwright.config.*	Playwright (e2e)

File placement — match the repo's existing convention:

• If test files live next to source (src/foo.ts → src/foo.test.ts), follow that.
• If test files live in a separate tree (tests/foo_test.py), follow that.
• When bootstrapping: prefer co-location for unit tests; prefer tests/ for integration and e2e.