test: make GR-8 overhead gate robust (best-of-N; skip under -race)

Author: muhammetsafak

bench_test.go

@@ -57,30 +57,56 @@ func BenchmarkBarePayloadJSON(b *testing.B) {
 // already pays), measured against a conservative broker round-trip. It is pure CPU
 // — no broker — so it is stable and environment-independent in CI.
 func TestCodecOverheadWithinBudget(t *testing.T) {
+	// GR-8 is a pure-CPU timing gate. The race detector instruments every memory
+	// access and inflates the codec disproportionately (it touches more memory than
+	// bare JSON), so the measurement is meaningless under -race. CI runs this suite
+	// with -race; the non-race coverage job enforces this gate instead.
+	if raceEnabled {
+		t.Skip("GR-8 overhead is a pure-CPU timing gate; skipped under -race (enforced in the non-race coverage job)")
+	}
+
 	const iter = 200_000
+	const rounds = 5
 
-	avg := func(fn func()) time.Duration {
-		for i := 0; i < 20_000; i++ { // warm up
-			fn()
-		}
+	// measure returns the average per-op duration for fn over `iter` calls.
+	measure := func(fn func()) time.Duration {
 		start := time.Now()
 		for i := 0; i < iter; i++ {
 			fn()
 		}
 		return time.Since(start) / iter
 	}
 
-	envelope := avg(envelopeRoundTrip)
-	bare := avg(barePayloadJSON)
+	// best returns the fastest (minimum) average across several rounds. CPU
+	// contention, GC and scheduler preemption on shared CI runners only ever ADD
+	// time, so the minimum is the closest estimate of the true pure-CPU cost. Taking
+	// the best round makes this gate robust against a noisy runner instead of flaking
+	// on it — it cannot mask a real regression (a genuinely slow codec is slow in
+	// every round, including the fastest).
+	best := func(fn func()) time.Duration {
+		for i := 0; i < 20_000; i++ { // warm up
+			fn()
+		}
+		min := measure(fn)
+		for r := 1; r < rounds; r++ {
+			if d := measure(fn); d < min {
+				min = d
+			}
+		}
+		return min
+	}
+
+	envelope := best(envelopeRoundTrip)
+	bare := best(barePayloadJSON)
 
 	marginal := envelope - bare
 	if marginal < 0 {
 		marginal = 0
 	}
 	overhead := float64(marginal) / float64(referenceBrokerRoundTrip) * 100
 
-	t.Logf("envelope codec: %v/op  bare JSON: %v/op  marginal: %v  overhead vs %v broker: %.2f%%",
-		envelope, bare, marginal, referenceBrokerRoundTrip, overhead)
+	t.Logf("envelope codec: %v/op  bare JSON: %v/op  marginal: %v  overhead vs %v broker: %.2f%% (best of %d rounds)",
+		envelope, bare, marginal, referenceBrokerRoundTrip, overhead, rounds)
 
 	if overhead > 2.0 {
 		t.Fatalf("codec overhead %.2f%% exceeds the 2%% GR-8 budget (marginal %v over a %v round-trip)",

race_enabled_test.go

@@ -0,0 +1,7 @@
+//go:build race
+
+package babelqueue_test
+
+// raceEnabled reports whether the test binary was built with the race detector
+// (`go test -race`). See race_norace_test.go for why the GR-8 gate consults it.
+const raceEnabled = true

race_norace_test.go

@@ -0,0 +1,9 @@
+//go:build !race
+
+package babelqueue_test
+
+// raceEnabled reports whether the test binary was built with the race detector
+// (`go test -race`). The GR-8 overhead gate is a pure-CPU timing measurement, so it
+// is skipped under -race (which instruments every memory access and distorts timing)
+// and enforced in the non-race coverage job instead.
+const raceEnabled = false