go-test-timing-boundary-flake

Answer

Root cause: TestExecuteTimeout asserted Duration >= 20ms against a 20ms context deadline — a razor-edge on measured wall time. context.WithTimeout arms its internal timer against now() at call time; if the test goroutine is descheduled (scheduler preemption under t.Parallel() load) between arming the deadline and capturing start := time.Now(), the timer fires "early" relative to the later-captured start. Measured wall time then lands at 19.7–19.99ms for a 20ms deadline. The assertion passes in isolation and flakes under load (UHLP tick 145, FLAKE-001, fixed in d95594b).

Fix: assert a tolerance band that proves the 1s sleep was truncated near the timeout — a lower bound that absorbs preemption slack, and an upper bound that proves the full 1s sleep did not run. The upper bound is the real behavioral guarantee; the lower bound no longer sits on the razor's edge.

// execute.go — implementation under test
func Execute(ctx context.Context) error {
    timer := time.NewTimer(time.Second) // simulated 1s workload
    defer timer.Stop()
    select {
    case <-ctx.Done():
        return ctx.Err() // truncated near the deadline
    case <-timer.C:
        return nil
    }
}

// execute_test.go — fixed test (commit d95594b)
func TestExecuteTimeout(t *testing.T) {
    t.Parallel()

    ctx, cancel := context.WithTimeout(context.Background(), 20*time.Millisecond)
    defer cancel()

    start := time.Now()
    err := Execute(ctx)
    d := time.Since(start)

    if !errors.Is(err, context.DeadlineExceeded) {
        t.Fatalf("Execute() error = %v, want context.DeadlineExceeded", err)
    }

    // FLAKE-001 (d95594b): old assertion `d >= 20*time.Millisecond` failed
    // under parallel load when preemption measured 19.7ms wall time.
    //
    // Tolerance band:
    //   lower bound — allows scheduler/timer slack below nominal
    //   upper bound — proves the 1s sleep was truncated (never 500ms+)
    const (
        minTruncated = 15 * time.Millisecond
        maxTruncated = 500 * time.Millisecond
    )
    if d < minTruncated || d > maxTruncated {
        t.Fatalf("Execute() took %v, want %v <= d <= %v (proves 1s sleep truncated)",
            d, minTruncated, maxTruncated)
    }
}

Bound rationale: the upper bound (500ms) is the meaningful assertion — it fails only if the sleep ran to completion or truncation was pathologically late, catching the bug the test exists for. The lower bound (15ms, 75% of nominal) is wide enough that a 1s–20ms scheduling jitter or timer early-fire can never trip it, while still failing if truncation returns far too early (e.g., a broken pre-canceled fast path).