iru-go-coverage
Run a Go module's (or Go workspace's) container-free tests with statement coverage — `go test -covermode=atomic -coverpkg=./... -coverprofile=build/coverage/cover.out` — and read the profile with a sm
SKILL.md.claude/skills/iru-go-coverage/SKILL.md
GitHubGo Coverage
Run the module's fast (container-free) tests with Go's statement coverage and report the exact, measured coverage for the files the user cares about, read from the coverprofile. This skill only measures and reports coverage — it does not add tests, modify source/test code, or change any configuration unless asked to as a follow-up.
Step 1 — Determine scope and test selection
- Targets (optional, comma-separated): Go files (
internal/greet/greet.go), package directories (internal/cli— the files directly in it), directory trees (internal/cli/...— the directory and everything below), or import paths (github.com/acme/tool/internal/cli→ its directory viago list -f '{{.Dir}}' <path>, made relative). No targets → every file in the profile. bar: <N>— the threshold to judge each target against; default 80 (this catalog's group gate).coverpkg: <pattern>— what is instrumented; default./...(Step 2 explains why). In ago.workworkspace whose root isn't a module, the default is one./<dir>/...per workspace module, comma-joined (go list -m -f '{{.Dir}}', verified:./...alone fails there), and the test patterns are those same./<dir>/...entries.tags:,run:— as iniru-go-testStep 0. Arun:filter undercounts code other tests also exercise — say which tests ran; prefer the whole fast suite when in doubt.profile: <path>— an extra coverprofile to merge (e.g. Step 4's binary coverage).lock: held— only meaningful withtags: integration(Step 3).
Detect the toolchain, module/workspace layout, vendoring, and race-detector availability exactly as iru-go-test
Steps 1–2 do; a wiring failure there (no Go, inconsistent vendoring, go.mod requires go >= …) stops this skill too.
Step 2 — Run the coverage build
rm -f build/coverage/cover.out && mkdir -p build/coverage build/test-results
go test -count=1 -covermode=atomic -coverpkg=<coverpkg> -coverprofile=build/coverage/cover.out \
[-tags <tags>] [-run '<regex>'] -json <test patterns, default ./...> > build/test-results/go-test.json
-coverpkg=./...instruments every package of the module in every test binary, so a package with no tests of its own (cmd/<bin>,internal/version) and code reached only through another package's tests (the CLI tests ininternal/clidrivinginternal/greet) are counted. Without it, each package is measured only by its own tests andcmd/<bin>/main.gonever appears. The profile then repeats every block once per test binary — the parser merges them (a block counts as covered if any binary hit it).- In-process testscript e2e tests count:
testscript.Mainre-executes the test binary for eachexec <bin>line, and go-internal merges those subprocesses' coverage into the profile (verified:cli.Main, reached only from.txtarscripts, measured 83.3% → 100% as scripts were added). -covermode=atomicis the mode-racerequires and is safe with parallel tests; this run doesn't add-race(iru-go-testcovers that), which keeps it faster.- Test failures: the profile is still written when tests fail (verified) — report the coverage but say it comes
from a failing run, and list the failures by parsing
build/test-results/go-test.jsonwithiru-go-test's Step 6 parser. A build failure leaves that package's blocks out of the profile (or no profile at all) — report it and never read a stale file (hence therm -ffirst). - Integration coverage only when
tagscontainsintegration: run it throughiru-go-testStep 5 (Docker check +.integration-test.lock,lock: heldhonored) with-coverprofile=build/coverage/cover-integration.out, and report it separately, labeled "includes container-backed tests — not the gate value".
Step 3 — Optional: coverage of the real binary (Go ≥ 1.20)
When the project's end-to-end tests run a built binary as a subprocess (a shell/bats/Python harness, or Go tests
that exec.Command a binary built in TestMain instead of testscript's in-process re-exec), that code is invisible to
-coverprofile. Instrument the binary instead:
rm -rf build/coverage/covdata && mkdir -p build/coverage/covdata
go build -cover -covermode=atomic -coverpkg=./... -o build/coverage/<bin>-cover ./cmd/<bin>
GOCOVERDIR=build/coverage/covdata <run the e2e harness against build/coverage/<bin>-cover>
go tool covdata percent -i=build/coverage/covdata # per-package summary
go tool covdata textfmt -i=build/coverage/covdata -o build/coverage/e2e.out
textfmt writes the same legacy profile format as -coverprofile (verified), so pass profile: build/coverage/e2e.out and the parser merges it with the unit profile. Only do this when the user asks or the
project already wires it (a GOCOVERDIR in its Makefile/CI) — the harness is the project's, not this skill's.
Step 4 — Read the exact coverage from the profile
Profile lines are <import path>/<file>.go:<startLine>.<startCol>,<endLine>.<endCol> <statements> <count>. Statement
% = covered statements / statements. go tool cover -func only gives per-function figures (and a total), so per
file figures come from this parser (verified: its total matched go tool cover -func's total: (statements) 76.9%, and per-file sums matched the per-function rows). Pass the profile(s) comma-joined, then the targets, then
the bar:
python3 - build/coverage/cover.out[,build/coverage/e2e.out] 'internal/greet/greet.go,internal/cli' 80 <<'PY'
import os
import re
import subprocess
import sys
profile = sys.argv[1]
want = [w.strip().rstrip("/") for w in (sys.argv[2] if len(sys.argv) > 2 else "").split(",") if w.strip()]
bar = float(sys.argv[3]) if len(sys.argv) > 3 else 80.0
# Map import-path file names (github.com/o/r/internal/x/y.go) back to repo-relative paths via go list.
mods = subprocess.run(["go", "list", "-m", "-f", "{{.Path}} {{.Dir}}"], capture_output=True, text=True).stdout.split("\n")
roots = [l.split(" ", 1) for l in mods if " " in l] # one line per module (several in a go.work)
cwd = os.path.realpath(os.getcwd())
def rel(name):
for path, d in sorted(roots, key=lambda r: -len(r[0])):
if name == path or name.startswith(path + "/"):
return os.path.relpath(os.path.join(os.path.realpath(d), name[len(path) + 1:]), cwd)
return name
blocks = {} # (file, block) -> [stmts, hit]
lines = [ln for prof in profile.split(",") if prof for ln in open(prof)] # several profiles merge
for line in lines:
if line.startswith("mode:"):
continue
m = re.match(r"^(.+\.go):(\d+\.\d+,\d+\.\d+) (\d+) (\d+)$", line.strip())
if not m:
continue
key = (m[1], m[2]) # -coverpkg repeats every block once per test binary: merge
b = blocks.setdefault(key, [int(m[3]), False])
b[1] = b[1] or int(m[4]) > 0
GEN = re.compile(r"^// Code generated .* DO NOT EDIT\.$", re.M)
files = {}
for (f, blk), (n, hit) in blocks.items():
s = files.setdefault(f, {"stmts": 0, "hit": 0, "miss": set()})
s["stmts"] += n
if hit:
s["hit"] += n
elif n:
start, end = blk.split(",")
s["miss"].update(range(int(start.split(".")[0]), int(end.split(".")[0]) + 1))
def ranges(nums):
out = []
for n in sorted(nums):
if out and n == out[-1][1] + 1:
out[-1][1] = n
else:
out.append([n, n])
return ", ".join(str(a) if a == b else f"{a}-{b}" for a, b in out)
def pct(h, n):
return f"{100 * h / n:.2f}%" if n else "n/a"
def match(path, w):
if w.endswith("/..."):
return path.startswith(w[:-4] + "/")
return path == w or os.path.dirname(path) == w
th = tn = 0
rows, generated = [], []
for f in sorted(files):
path, s = rel(f), files[f]
try:
head = open(path, encoding="utf-8", errors="replace").read(4096)
except OSError:
head = ""
if GEN.search(head): # generated code never counts toward the bar
generated.append(path)
continue
th, tn = th + s["hit"], tn + s["stmts"]
if want and not any(match(path, w) for w in want):
continue
rows.append((path, s))
print(f"TOTAL statements {th}/{tn} ({pct(th, tn)}) branches: not available in Go")
for path, s in rows:
p = 100 * s["hit"] / s["stmts"] if s["stmts"] else 100.0
flag = "" if p >= bar else f" BELOW {bar:g}% uncovered: {ranges(s['miss'])}"
print(f"{path} statements {s['hit']}/{s['stmts']} ({pct(s['hit'], s['stmts'])}){flag}")
if generated:
print(f"excluded (generated): {', '.join(generated)}")
for w in want:
if not any(match(r[0], w) for r in rows):
print(f"NOT IN PROFILE {w} — no statements, outside -coverpkg, generated, or its package failed to build")
PY
Interpreting it:
- Generated files (the standard
// Code generated … DO NOT EDIT.line, e.g.stringer/mockgen/protobuf output) are excluded from both the total and the per-file list and named on one line (verified). NOT IN PROFILE— a file with no executable statements (onlyvar/const/type declarations, such asinternal/version/version.goor adoc.go), a package outside-coverpkg, a generated file, or a package that failed to build. Say which (checkgo-test.jsonfor build failures); never report it as 0%. A file present with0/Ngenuinely is 0%.- Thin entry points:
cmd/<bin>/main.goholding onlyos.Exit(cli.Main(ctx, os.Args[1:], …))is one or two statements reached only when the real binary runs — testscript's in-processexeccalls the registered function, notmain(), so it stays uncovered undergo test(verified:0/1) unless Step 3's binary coverage is merged (verified:1/1). Report it as "thin entry point, exercised by the binary — excluded from the bar" when it contains no logic (no branches, only theMaincall); if it holds real logic, it counts like any file and the finding is "move the logic intointernal/cli". - Branches: Go's coverage is statement-based (blocks between branch points); there is no branch metric — say
"branch coverage: not available in Go" rather than inventing one. An uncovered
ifarm shows up as uncovered lines.
Leave build/coverage/cover.out in place when build/ is gitignored (CI and sonar.go.coverage.reportPaths read
it); otherwise delete it after parsing (rm -f build/coverage/*).
Step 5 — Report results
State the toolchain, how coverage was collected (-coverpkg=<pattern>, -covermode=atomic, whether a binary
profile was merged), the test selection (and that integration-tagged tests were not compiled), and whether the
tests passed. Then, computed from the actual profile — never estimated:
- Total: statement % and whether it meets the bar; "branch coverage: not available in Go".
- Per target (or per file, for an unscoped run with few files): statement %, and for every target under the bar
the uncovered line ranges (
internal/greet/greet.go: 71.43% (5/7) — uncovered: 18-19, 27) so the user, or a follow-up coding step, knows where to add tests. Name excluded generated files and thin entry points, and everyNOT IN PROFILEtarget with its reason.
Never paste the profile or go tool cover output. If the run never started (wiring problem) or a target's package
failed to build, report that instead of a percentage, with the exact command and the fix. Do not add tests, modify
source/test code, or re-run to raise the number — that's a follow-up the user (or a coding skill) drives explicitly.
Verification notes
Verified with Go 1.27.2 (darwin/arm64), cobra 1.10.2 and go-internal 1.16.0 (testscript) in
$TMPDIR/iru-verify/cli/go-gates/demo (a throwaway Cobra CLI module outside this repository):
go test -count=1 -covermode=atomic -coverpkg=./... -coverprofile=… ./...exited1(one deliberately failing test) but still wrote the profile; it listed each block once per test binary. The parser reportedTOTAL statements 20/26 (76.92%)—go tool cover -funcsaidtotal: (statements) 76.9%— withinternal/cli/cli.go 15/18 (83.33%)(=Main 83.3%),internal/greet/greet.go 5/7 (71.43%) BELOW 80% uncovered: 18-19, 27, andcmd/democtl/main.go 0/1.cli.Mainwas reached only from in-process testscript scripts.- A
// Code generated by stringer; DO NOT EDIT.file was excluded and named;internal/version/version.go(onlyvardeclarations) and an unknown target came backNOT IN PROFILE; target filters by file and by directory worked. go build -cover -covermode=atomic -coverpkg=./...+GOCOVERDIR=… ./democtl-cover greet Zed(and a failinggreet "", exit 3) wrotecovmeta/covcountersfiles;go tool covdata percentprinted per-package figures andgo tool covdata textfmta legacy profile; merged with the unit profile,cmd/democtl/main.gobecame1/1and the total24/30 (80.00%).- A two-module
go.workworkspace:-coverpkg=./a/...,./b/...with./a/... ./b/...produced a merged profile that the parser mapped back toa/a.go/b/b.goviago list -m. - Still unverified: Windows paths, profiles from
-tags integrationruns with real containers merged into the gate number (deliberately not done), and very large modules (the parser holds every block in memory).
Sources
- go.dev:
go help testflag(-cover,-covermode,-coverpkg,-coverprofile), go.dev/blog/cover (statement coverage, block profile format), go.dev/doc/build-cover (Go 1.20go build -cover,GOCOVERDIR,go tool covdata percent|textfmt|merge), go.dev/ref/mod (workspaces),go generatedocs (theCode generated … DO NOT EDIT.convention) - pkg.go.dev: github.com/rogpeppe/go-internal/testscript (
Mainre-exec of the test binary) - irurueta docs: ai/cli-for-agents/testing-clis.adoc (thin entry point, logic in a testable core, in-process testscript end-to-end tests)