Coverage

Target: $ARGUMENTS. The floor is 90% lines per touched module, and every new pub / pub(crate) fn has a test (coverage floor). $S is your scratchpad directory.

1. Toolchain

Coverage runs on nightly (doc-tests only instrument there); build and test stay on the pinned stable toolchain. Two version couplings break it:

0% everywhere is never a real result. Cross-check with stable cargo llvm-cov --lib --all-features (undercounts doc-tests, but sane).

2. Baseline

A percentage means nothing without main's number for the same file.

• Quick: Coveralls has main's per-file numbers (https://coveralls.io/github/wboayue/rust-ibapi, measured as in §3's CI recipe).

• Like for like: run §3 on main in a detached worktree so your branch stays untouched. A fresh worktree is a cold build, several minutes.

  git worktree add --detach $S/cov-main origin/main
  # run §3 there, note the numbers
  git worktree remove $S/cov-main

(src/proto/decoders.rs once read 85% on a branch, which looked low until main read 41.7%.)

3. Per-file loop

just cover instruments everything and opens a browser. For one file:

# profiles pile up across --no-report runs; start each iteration clean
cargo +nightly llvm-cov clean --profraw-only

# instrument + test, no report (~1 min with a warm build cache)
cargo +nightly llvm-cov --all-features --doctests --no-report --quiet

# summary for the target file
F=src/contracts/types.rs
cargo +nightly llvm-cov report --json | jq -r --arg f "$F" '.data[0].files[]
  | select(.filename | endswith($f)) | .summary | to_entries[]
  | select(.key | IN("lines","functions","regions"))
  | "\(.key): \(.value.percent | floor)% (\(.value.covered)/\(.value.count))"'

# which lines are uncovered
cargo +nightly llvm-cov report --summary-only --show-missing-lines | grep "$F"

Feature-gated code. --all-features never compiles #[cfg(not(feature = "async"))] / not(feature = "sync") blocks, so they read as absent, not uncovered. CI (Coveralls) merges a sync-only and an async-only run instead; use that when the file has such blocks, or to match Coveralls:

cargo +nightly llvm-cov clean --workspace
cargo +nightly llvm-cov --no-report --doctests --no-default-features --features sync
cargo +nightly llvm-cov --no-report --doctests --no-default-features --features async
# then the same report commands

For the line-by-line view, cargo +nightly llvm-cov report --html --output-dir $S/cov and open $S/cov/html/coverage/<absolute path>.html; red lines carry uncovered-line.

Without the clean step, each run adds to the last: a deleted test still counts, and switching between the two recipes mixes configurations. After each batch of tests, re-run the clean and instrument steps of whichever recipe you used; the report commands (~15s) read what they left.

4. Read the numbers

• Track functions and regions, not lines. lines.count is instrumented sites: generics, derives and macro expansions move it without the file changing (one module went 241 → 343 → 245 sites across a refactor while its source stayed ~545 lines).
• Find gaps in the HTML, not the JSON. The JSON lists per-monomorphization sub-regions as uncovered where the HTML shows the line covered.
• Noise, not gaps (on stable or --lib runs): ..Default::default() and doc-comment fence lines. Nightly + --doctests removes them.
• Not coverage at all: a const fn called only from const initializers reads 0%; llvm-cov sees runtime paths only.

5. Close the gap

Test behavior through production code first (exercise production code): the impl Client method with a stubbed bus, the decoder with a fixture builder, the error branch with the frame that triggers it. Then, for what's left:

Every added test asserts something a reader would care about. A test that only executes a line to move a number gets cut in review.

6. Report

In the PR body, per touched file: main's number → yours, for lines and functions, and the command that produced them. target/llvm-cov-target/ grows large; delete it when done if disk is tight.