testbudget

package
v0.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 5, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Overview

Package testbudget sizes the deadlines tests use to bound a hang.

A test that waits for a subprocess, an extension, or a shell command should return as soon as the awaited event happens; its deadline only decides how long a genuine hang takes to fail. Fixed 5-10 s deadlines turned into failures when many test binaries shared a machine (load average 80 on 14 cores), so waits use Wait instead. Only test code imports this package.

The go test -timeout deadline caps every bound, so a test that starts when the package run is about to expire reports a timeout of its own, naming a wait, a few seconds before the test binary's timeout panic. That test is not at fault: the run is out of time. A package whose tests need longer than -timeout in one process (coding/cli needs about 25 minutes on 4 CPUs) runs as several go test processes in CI (automation/ci/test-grouped.sh).

Index

Constants

View Source
const Default = 120 * time.Second

Default matches the extension-conformance connect budget, chosen for -p 12 runs on shared CI runners where builds and Node startup stall for tens of seconds.

View Source
const Env = "PIG_TEST_WAIT_TIMEOUT_SEC"

Env overrides Default with a positive whole number of seconds.

Variables

This section is empty.

Functions

func Capped

func Capped(budget, until time.Duration) string

Capped is the note Wait logs when the go test -timeout deadline, until away, cuts a wait to budget. In that window nothing is known about the code under test: a test that fails after the note may be a hang or may be healthy work that the package's own slowness left no time for, and only the package's total time tells them apart.

func Context

func Context(t *testing.T) context.Context

Context returns t.Context() bounded by Wait(t).

func DeadlineContext

func DeadlineContext(t *testing.T) context.Context

DeadlineContext returns t.Context() bounded to end [grace] before t's go test deadline; without a deadline it is t.Context(). It bounds work whose length no event of the test decides, such as the go build of a shared test binary: the time that takes is what the host needs, so no fixed bound fits, and only the package timeout says it hangs. Work that fails at this bound should say so (see Expired).

func Expired

func Expired(ctx context.Context) string

Expired describes ctx from DeadlineContext when its deadline ended it, or returns "".

func Resolve

func Resolve(override string, untilDeadline time.Duration, hasDeadline bool) (time.Duration, error)

Resolve computes a budget from an Env value and the time left before the test deadline.

func Wait

func Wait(t *testing.T) time.Duration

Wait returns the hang bound for t: Default or the Env override, capped to end before t's deadline. When the deadline cuts the bound short, Wait logs Capped on t, once: a wait the package's deadline ended fails the test, or kills the child process whose context carries the bound ("signal: killed"), just as a hang does, and that line is what tells the two apart.

Types

type Once

type Once[T any] struct {
	// contains filtered or unexported fields
}

Once runs one build per test process and keeps its result for every later test: the shape of a shared fixture binary. The build runs under DeadlineContext of the first test that asks, so it ends at the go test deadline and not at a fixed bound, and a build that the deadline cut reports that (Expired). A failed build is kept, not retried.

func (*Once[T]) Do

func (o *Once[T]) Do(t *testing.T, build func(ctx context.Context) (T, error)) (T, error)

Do returns the build's result, running build on the first call.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL