How to Fill Test Gaps With an Agent

Test-gap filling is the recurring work of finding important behavior that lacks coverage, turning that behavior into scenarios, and adding tests in the project's own style. It is different from chasing a coverage percentage. The goal is to protect critical paths, edge cases, and failure modes that would hurt if they regressed.

That makes the job a good fit for an agent when the workflow is narrow and reviewable. The agent can survey the repository, rank gaps by blast radius, write scenarios, backfill one vertical slice at a time, and draft a PR. A human still approves the tests and any production bug the tests reveal.

Why test gaps quietly cost you

Untested code rarely announces itself as "risky". It looks like a branch nobody touches, an error path that only fails in production, an authorization rule covered by shape tests, or a recently changed flow that was manually checked once. Coverage reports can help, but they do not tell you which missing test matters most.

The cost is review debt. Every future change in that area requires a human to remember the behavior, inspect the implementation, and hope the manual path still works. The longer a critical path stays uncovered, the more expensive each change becomes.

What the manual process looks like

A careful test-gap pass follows this sequence:

1. Read the source and neighboring tests to learn the domain vocabulary and existing conventions.
2. Identify unprotected behavior, not only uncovered lines.
3. Rank gaps by blast radius: auth, payments, data writes, error paths, edge cases, recent changes, and complex logic first.
4. Write a scenario for each selected behavior with objective, starting conditions, role, steps, and expected outcomes.
5. Backfill tests one behavior at a time through public interfaces.
6. Match the existing framework, layout, naming, fixtures, and assertion style.
7. Run the relevant checks, self-review against the test quality bar, and draft a PR.

The discipline is in selecting the right gaps. A small PR that protects a critical error path is better than a large PR that tests trivial getters.

What an agent can automate

The test gap filler playbook gives the agent a recurring coverage workflow:

• Find behavior gaps. The agent reads the repository and existing tests, then produces a durable list of untested behaviors without depending on file paths or line numbers.
• Prioritize by risk. It puts critical paths, error handling, recently changed code, and complex state ahead of low-value coverage.
• Write scenarios first. Before any assertion, it writes the objective, starting conditions, role, steps, expected outcomes, and matching edge cases.
• Backfill in vertical slices. It adds one behavior test at a time, confirms it passes, then moves to the next behavior instead of bulk-writing imagined tests.
• Match house style. It copies the existing test framework, naming, fixtures, helpers, and assertion style rather than introducing a new convention.
• Draft the PR. It names the protected behaviors, the gaps closed, and any findings the tests surfaced.

If a backfilled test reveals production code is wrong, the agent should surface the finding. It should not weaken the assertion to make the PR easier.

The guardrails that make it safe

The first guardrail is behavior-level scope. The agent describes gaps by what the system should do, not by private functions or implementation details. That keeps tests useful after refactors.

The second guardrail is the scenario step. A scenario written before the assertion prevents the agent from reading the implementation and then testing that the implementation does what it already does.

The final guardrail is human approval. The workflow drafts a PR and waits. A human reviews the tests, self-review notes, and any production finding before merging.

Set it up in Task Machine

The Test gap filler playbook installs the coding agent, the Fill test gaps workflow, the coverage-rising goal, and the recurring schedule. Setup takes a few minutes. You need a Task Machine workspace and permission to install playbooks (workspace owners have it). A connected repository is best. Until it is connected, the agent needs code and test context attached to the run.

1. Find the playbook

Open Playbooks and search for "test gap filler", or browse the Engineering category. The card shows the coding agent, workflow, goal, schedule, and testing skills the install creates.

2. Preview what it installs

Preview & install opens the full contents before anything is created: the Coding Agent, the Fill test gaps workflow, the Coverage rising goal, the testing skills, and the schedule.

3. Define the test-gap context

Start setup asks for the repository, uncovered behavior, risk areas, and test command. Use the risk areas field for the parts of the product where a missed regression would hurt most.

4. Generate and review

Generate customized playbook turns the context into the agent instructions, workflow prompts, coverage goal, and schedule. Review for the QA pass, scenario-writing step, vertical-slice backfill, self-review bar, draft PR, and approval gate.

5. Install

Install customized playbook creates the records in your workspace. Two follow-ups arrive in your inbox: start the Fill test gaps workflow and set the test-gap filling cadence. The first run confirms repo scope, risk areas, test style, check commands, and PR handoff before scheduled coverage work begins.

What good looks like

Healthy gap filling has three signs:

• Gaps are behavior names. The PR says which behavior is now protected, not only which file gained tests.
• The highest-risk paths move first. Auth, payments, data writes, edge cases, and recent changes outrank easy coverage wins.
• The tests fit the codebase. New tests look like neighboring tests and use public interfaces.

Common questions

Is this the same as raising coverage percentage? No. Coverage can guide exploration, but the playbook prioritizes behavior risk. A lower-count test that protects a critical branch is more valuable than many tests over trivial code.

What if a new test exposes a production bug? The agent should flag it as a finding in the PR and stop weakening the test. The human decides whether to fix it in the same PR or split the work.

Does the agent create new test conventions? No. The workflow tells the agent to match the existing framework, layout, naming, fixtures, helpers, and assertion style.

Does it merge the PR? No. The agent drafts the PR and waits for human approval.