slowgate

Overview ¶

Command slowgate enforces a wall-clock budget on individual Go tests by reading `go test -json` events from stdin. Tests whose Elapsed exceeds --threshold are reported on stderr and the process exits 1, unless the (Package, TestName) pair appears in the allowlist file referenced by --allowlist.

Usage:

go test -json ./... | tee /tmp/test.json |
  slowgate --threshold=2s --allowlist=tools/slowgate/allowlist.txt

The companion `tee` is the recommended pipeline form — it preserves the raw event stream for log archival; slowgate itself emits no stdout, only stderr reasons plus exit code.

Allowlist file format (line-based, grep-friendly, no external parser):

# comments after `#` are ignored; blank lines are ignored
github.com/example/pkg<TAB>TestName       # tab-separated (preferred)
github.com/example/pkg TestName            # any whitespace also accepted

Each data line must produce exactly two fields. The (Package, TestName) pair is matched verbatim against the `Package` and `Test` fields of the `go test -json` event. Subtests (Test names containing `/`) are skipped because the parent root-test event already aggregates the subtest's wall-clock into its own Elapsed; counting subtests independently would double-count the same time spent.

Companion gates (independent, no shared invariant):

• TEST-SLEEP-DISCIPLINE-01 (tools/archtest) — every time.Sleep in test code carries a //archtest:allow:test-sleep <reason> annotation. Targets sleep paper-trail; not coupled to slowgate.
• SLOWGATE-ALLOWLIST-01 (tools/archtest) — every entry in the slowgate allowlist (a) maps to a real top-level `func TestXxx`, AND (b) is preceded by a `# <reason>` comment line in allowlist.txt. Decoupled from sleep annotations: most >2s tests in this codebase are slow due to packages.Load / subprocess go-toolchain / fixture walks, not sleep.

ref: docs/plans/202605011500-029-master-roadmap.md G9 ref: cmd/test2json — TestEvent schema (Action/Package/Test/Elapsed) ref: github.com/gotestyourself/gotestsum cmd/tool/slowest/slowest.go ref: github.com/ghbvf/gocell/tools/e2egate/parser.go (stdin pipe pattern)