Grow coverage with useful tests

Repeating a passing suite can find regressions without reaching any new code. Likewise, a changed line executed during a review is not a measure of the application’s total coverage. Track two results separately: which product problems the checks detect, and which previously untested behaviors the suite now exercises and asserts.

Use this workflow during ordinary feature development and test authoring, without waiting for a separate request to improve coverage. Stay inside the user’s execution budget, target authority and existing holds. It is not permission to run extra tests during a bounded review.

Read uncovered code through MCP

The connected local sidecar MCP exposes query_code_coverage. Use the cumulative gaps first: they exclude paths already reached by any accepted capture in the same source and measurement scope.

{"operation":"progress","collection":"<collection-id>","repository":"<repository-label>","commit":"<full-commit-hash>"}

Choose the series matching the application, source revision, producer, toolchain and exclusions. Then read remaining files and inspect a line window:

{"operation":"progress_gaps","collection":"<collection-id>","series":"<series-id>","query":"src/session","limit":10}

{"operation":"progress_lines","collection":"<collection-id>","series":"<series-id>","version":12,"path":"src/session.go","from":40,"to":120,"with_source":true}

Use the returned version, not the example’s 12. missedRanges are exact within the requested window. with_source optionally reads screened local Git source at the recorded clean commit/tree; unavailable source stays explicit. No raw profile is needed for the durable ranges. Follow nextCursor for more files; progress_changed means another ingest advanced the series, so start the gap read again. Filter by component rather than scanning unrelated code.

progress_history with the series ID returns cumulative reached lines and newLinesHit at each accepted capture. Repeated paths add zero; newly reached paths raise the curve. Separate source/toolchain/coverable-line universes are not joined into a fabricated percentage. Progress starts with post-feature ingests and survives raw-profile cleanup; earlier captures are not backfilled. A capture can be failed or unbound: observed execution does not prove a passing assertion, durable test quality or which individual flow caused the gain.

On older servers without progress, use documents to select a matching capture, then gaps and lines with with_source=true. Label that evidence per-capture. Missing instrumentation is unmeasured, not zero. The review-reader profile has metadata only. If the local tool or relevant profiles are unavailable, say what is missing; do not silently launch setup or extra runs.

Choose one new behavior

1. Read the existing suite’s purposes, assertions and retained coverage for the intended application revision. Keep Go statements, LLVM lines and other producers separate. Coverage measures instrumented code only.
2. Use reflow coverage gaps --document <baseline> --limit 10, then reflow coverage lines --document <baseline> --path <path> --with-source to inspect a candidate’s missed ranges. Follow paging when needed. A gap is an investigation lead, not a test specification or a reachability verdict.
3. Prefer an uncovered behavior with user impact: an error recovery, empty state, permission boundary, state transition or alternate execution mode. Rank candidates by risk, likely new paths, setup cost and execution cost. Do not choose a large file solely because it has the most missed lines.
4. Before running, name the behavior, entry action, expected result and oracle (why that result is correct). Add an observable checkpoint and assertion. Merely visiting a screen or executing a line is not a useful behavioral check.

For example, another successful sign-in may add nothing. Checking that an expired session offers recovery, then restores the intended destination, can exercise a distinct path and assert its user-visible contract. Whether it adds coverage is a measurement to make, not a claim to assume.

Measure the addition

Use the frozen-binary cumulative workflow. Retain a baseline cumulative document assembled from the existing suite’s raw windows. Run the candidate once within the agreed budget, in its own window against the same frozen instrumented binary, with the same exclusions. Assemble a second cumulative document from the baseline windows plus that window. This reuses saved profiles; it does not rerun the whole suite.

Compare the two documents with:

reflow coverage diff --document <baseline-plus-candidate> \
  --base <baseline> --json

Only a likeForLike pair assembled this way measures this candidate’s incremental test gain. Read newlyHit and newlyMissed, including remaining pages; equal totals alone do not establish equal coverage. A cumulative addition should not lose previously covered code: investigate newly missed ranges or an incomplete assembly before claiming gain. Never sum percentages, per-run hit counts or the maximum of separate journeys to manufacture a cumulative total.

Reflow does not automatically merge stored documents or attribute process coverage to individual flows. Keep the raw windows and their process counts, binary identity and apply keys as described in the cumulative guide. If those inputs are unavailable, report gain as unmeasured. Across-build differences and A/A-controlled mutation flips are useful review evidence, not this test-gain experiment.

Decide what to keep and what to try next

Record the candidate’s purpose, assertion result, newly hit ranges, baseline and combined document IDs, execution duration, and any setup or cleanup cost. Coverage growth and cost per newly tested behavior help choose the next test; there is no coverage-per-minute score inferred from unrelated captures.

• New paths and a meaningful passing assertion: keep the test, advance the cumulative baseline, then inspect the remaining risk-bearing gaps.
• No new paths, but a new contract or oracle: it may still be valuable. Keep it with the explicit reason; record zero coverage gain separately.
• An equivalent scenario with no new assertion or paths: stop repeating it as a growth exercise and choose a different behavior.
• Failure or uncertain completion: retain the original and investigate; do not weaken the assertion, repeatedly retry, or call it coverage progress.
• No gain measurement: say what is missing. Do not report zero, or imply the candidate expanded coverage because it passed.

For a recurring QA loop, keep stable regression journeys and their controls within each comparison. Reserve a bounded part of the agreed budget for test growth between rounds: inspect clean-base gaps, add one justified behavior, measure it, then establish fresh controls for the expanded suite. Do not swap journeys or binaries mid-round, select tests using a private mutation answer key, or retroactively compare old and expanded suites as identical workloads.

The product’s Code coverage view leads with Suite coverage growth and remaining gaps. Its durable line union stays flat for repeated execution and rises for newly reached code within the selected source/measurement scope. The separate capture-history chart shows individual process totals. New source or coverable-line universes start separate series; a lower percentage after adding code is not hidden. Use the frozen-binary workflow above when you need causal incremental gain rather than accumulated observed reach.