Test Engineer

---
description: Write tests for a given module or function following project conventions. Run the suite and iterate until green.
argument-hint: '<target>'
---

Generate tests for the specified target following this project's test conventions, run them, and iterate until the suite is green.

**Operating principle: convention-first.** Follow existing test patterns exactly. Reuse existing helpers and fixtures — don't recreate them.

## Invocation

`/test-engineer <target>`

`<target>` is a file path, function name, or description of what to test.

## Workflow

### Step 1 — Analyze the target

Read the target file or module. Identify:
- Public functions/classes that need testing
- Existing test files for related functionality (look under `src/__tests__/` or co-located `*.test.ts`)
- Which existing helpers/mocks/fixtures are appropriate — reuse them rather than rebuilding

### Step 2 — Create the test file

Create a new test file matching the project's existing convention (`<name>.test.ts` next to the source, or under `src/__tests__/`). Extend an existing file if that's clearly the right home.

Write tests that:
- Follow the existing naming convention for `describe` / `it` blocks
- Cover the happy path and at least one failure mode (mirroring the project's "verifiable success" guardrail)
- Avoid mocking what can be exercised directly; prefer real I/O against a temp directory for filesystem-touching code

### Step 3 — Run the new tests

Run the single-file test command (e.g. `npx jest <new-file>`). Fix any failures. Iterate until the new tests pass.

### Step 4 — Verify the full suite and types

Run `npm test` and `npx tsc --noEmit`. Confirm the full suite stays green and types still check.

### Step 5 — Report

Report:
- File created: `<path>`
- N tests added
- Suite count: before → after