1
# Test Writer Loop
2
3
A red/green harness that improves test coverage the disciplined way: pick an untested
4
behavior, write a test that fails first (proving it tests something real), implement
5
just enough to pass, run the full suite, record the coverage delta, and repeat — with
6
explicit stop conditions instead of running until told to stop.
7
8
## When to use
9
10
- A module or file has known-low coverage and you want it improved safely, without
11
  the agent quietly weakening tests to hit a number.
12
- Before a refactor, to build a safety net around code that currently has thin tests.
13
- As a bounded, reportable task ("spend up to 10 iterations improving coverage on
14
  `src/billing/`") rather than an open-ended request.
15
16
Not a fit for writing the *first* test infrastructure in a project with none at all
17
(set up a test runner first) or for end-to-end/integration test design, which needs
18
more upfront scoping than a per-behavior loop.
19
20
## Install
21
22
```bash
23
npx openagents-cli add openagents/test-writer-loop
24
```
25
26
| Runtime | Installed to |
27
|---|---|
28
| `claude-code` | `.claude/skills/test-writer-loop/` |
29
| `codex` | `.codex/skills/test-writer-loop/` |
30
| `openai-agents` | `.openai-agents/test-writer-loop/` |
31
| `generic` | `.openagents/test-writer-loop/` |
32
33
## Inputs
34
35
| name | type | required | default | description |
36
|---|---|---|---|---|
37
| `target_path` | path | no | auto | File/directory to focus on; auto-selects the lowest-coverage non-trivial module if omitted |
38
| `max_iterations` | number | no | `10` | Max red/green cycles per session |
39
| `coverage_command` | string | no | auto | Coverage command; auto-detected from the package manifest if omitted |
40
41
## Example run
42
43
```
44
> Run the test writer loop on src/billing/invoice.ts, max 8 iterations.
45
```
46
47
The harness baselines current coverage, picks the first untested behavior (e.g. "throws
48
on negative quantity"), writes a failing test, implements the fix if needed, runs the
49
full suite, records the delta, and continues until a stop condition in
50
`stop-conditions.md` is hit or 8 iterations pass — then reports before/after coverage
51
and any deferred gaps.
52
53
## Files
54
55
- `HARNESS.md` — overview, setup, guardrails (entry point).
56
- `loop.md` — the per-iteration red/green procedure.
57
- `stop-conditions.md` — hard stops, soft stops, and what's explicitly not a stop
58
  condition (coverage % alone).
59
60
## Limitations
61
62
- Needs a working test runner already configured in the project; it does not set one
63
  up from scratch.
64
- Behaviors requiring live infrastructure (a real database, an external API with no
65
  test double) are recorded as deferred gaps, not faked.
66
- Targets coverage as a signal of untested *behavior*, not a percentage to chase — it
67
  will stop before reaching an arbitrary number if remaining gaps are trivial.
68