/test-coverage

name: test-coverage
description: "Generate unit tests for untested branches and edge cases. Use when coverage is low, CI flags gaps, or a release needs hardening. Not for integration/E2E suites, framework migrations, or fixing production bugs."
license: MIT
effort: low
metadata:
  version: 1.5.0
  author: "Luong NGUYEN <luongnv89@gmail.com>"

Test Coverage Expander

Expand unit test coverage by targeting untested branches and edge cases.

When to Use

• User asks to "increase test coverage", "add more tests", "expand unit tests", or "cover edge cases"
• A CI pipeline reports low coverage and the user wants it improved
• A code review flags untested error paths or boundary conditions
• The user wants to identify and fill gaps in an existing test suite before a release

Stack (detect before Step 1 of Workflow)

Detect the project's language from its manifest file and use the matching commands throughout the Workflow below:

| Manifest | Stack | Coverage command | Test framework | |---|---|---|---| | `package.json` | JavaScript/TypeScript | `npx jest --coverage` or `npx vitest --coverage` | Jest, Vitest, Mocha | | `pyproject.toml` | Python | `pytest --cov=. --cov-report=term-missing` | pytest, unittest | | `go.mod` | Go | `go test -coverprofile=coverage.out ./...` | testing, testify | | `Cargo.toml` | Rust | `cargo tarpaulin` or `cargo llvm-cov` | built-in test framework |

If none of these manifests is found, see [Edge Cases](#edge-cases) — "No test framework detected".

Repo Sync Before Edits (mandatory)

Before creating/updating/deleting files in an existing repository, sync the current branch with remote. First save `git status --porcelain` as the pre-sync list; Step 4 never stages those paths.

branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin
git pull --rebase origin "$branch"

If the working tree is not clean, stash first, sync, then restore:

git stash push -u -m "pre-sync"
branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin && git pull --rebase origin "$branch"
git stash pop

If `origin` is missing, pull is unavailable, or rebase/stash conflicts occur, stop and ask the user before continuing.

Workflow

0. Create Feature Branch

Before making any changes: 1. Run `git rev-parse --abbrev-ref HEAD`. If it prints a branch other than `main` or `master` that was created for this task, skip to Step 1. 2. Run `git branch -a` and note the prefix most existing branches use (e.g., `feat/`, `feature/`, `test/`). 3. Create and switch to a new branch with that prefix. If no prefix is in use, name it `feat/test-coverage`.

1. Analyze Coverage

Run the coverage command for the detected [Stack](#stack-detect-before-step-1-of-workflow) above. Record the total coverage percentage and the pass/fail counts as the baseline. If any test fails, stop here (see [Edge Cases](#edge-cases)).

From the report, identify:

• Untested branches and code paths
• Low-coverage files/functions (prioritize files below 60%)
• Missing error handling tests

2. Identify Test Gaps

Review the low-coverage code for:

• Logical branches (if/else, switch), state transitions, and side effects
• Error paths and invalid input, where real bugs often live
• Boundary values: empty, null, zero, min, max, and off-by-one
• Normal paths that no existing test covers

3. Write Tests

1. Read `references/unit-test-quality.md`. 2. Write tests for the Step 2 gaps with the test framework for the detected [Stack](#stack-detect-before-step-1-of-workflow), following that file's rules: deterministic, isolated, fast, one behavior per test, and assertions on behavior rather than implementation. 3. Check each new test against the file's four self-check questions. Rewrite any test that fails one.

4. Verify Improvement

1. Run the full test suite. If a previously passing test now fails, report PARTIAL and name it. If a new test fails, run it on its own twice more. If it passes in either solo run, it is flaky: handle it as in item 2. Only if it fails all three times, read the failure and decide which side is wrong:

• **The test is wrong** (bad setup, or an expectation the code never promised): fix the test, then rerun.
• **The code is wrong** (the test checks behavior that the code's docstring, types, or name promise): this is a suspected bug. Remove the test, and any import or fixture only it used, then rerun item 1. Do not change production code, and do not loosen the assertion to match the code. Report the bug under `Decision:` with the test's code and failure output. The run can still be `COMPLETE`; name the bug in the `Result:` line. That test becomes the regression test for the fix.
• **You cannot tell which side is wrong**: treat it as a suspected bug.

2. Run only the new tests on their own, twice (for example `pytest tests/test_parser.py`, `go test ./internal/store -count=1 -run '^TestKey'`, `cargo test key_`). If a new test fails in either run, it depends on test order, shared state, or timing. Fix it once from the flakiness table in `references/unit-test-quality.md` and repeat items 1 and 2. If it still fails, remove it and list it under `Uncertainty:`. 3. Run the same coverage command as Step 1. 4. Compare the new total with the Step 1 baseline. If it is not strictly higher, report PARTIAL and list the Step 2 gaps that are still untested. 5. If the full suite passed in item 1 and the new test files passed in item 2, commit the new tests on the feature branch with a message that records the before/after coverage percentages and the files newly covered. Stage each test file this run wrote by explicit path (`git add tests/test_parser.py`); never `git add -A`, `git add .` or `git commit -a`, which would sweep in user work Repo Sync restored. Never stage a path on the pre-sync list. Stage a changed manifest or lockfile (*Coverage tool not installed*) only with its reason in the commit message. Check `git diff --cached --name-only` before committing. Under