Documentation
¶
Overview ¶
Package testcase contains shared assertions for the native Go test harness.
Package testcase is a helper that gives each go test case a deadline and records its steps in the test's log.
The report is the native output of go test. The results of the cases started with Start (`--- PASS`, `--- FAIL`, `--- SKIP`) and the steps (lines of t.Log) are printed as they are by go test -json or -v. Group marks a group without a deadline of its own and writes no line either. Each grouped case has its own deadline.
Run and RunLong of the non-test runner run a case without a test and write its steps to stdout as they are. The result is decided by the error returned. Long runner jobs (build, install, tool run) run without a deadline with RunLong.
The deadline is wall-clock time, because it is the timer that ends a stuck case, not a limit that measures the case's own computation time (AGENTS.md testing rule).
Index ¶
- Constants
- func As[T any](t testing.TB, v any) T
- func AsErr[T any](v any) (T, error)
- func Bounded(wait time.Duration, work func() error) (ok bool, err error)
- func CatchExit(code *int)
- func Close(t testing.TB, c io.Closer)
- func Group(t testing.TB)
- func MySQLConfig(uri string) (*mysql.Config, error)
- func ParityImplementations(root string) []string
- func Run(name string, deadline time.Duration, work func(c *Case) error) error
- func RunLong(name string, work func(c *Case) error) error
- func SequenceNameRows[T interface{ ... }](t testing.TB, rows interface{ ... }) [][2]any
- func StallGuard(parent context.Context, limit time.Duration) (ctx context.Context, progress func(), stop func())
- func StepBudget(steps int) time.Duration
- func Warn(format string, args ...any)
- type Case
- type EventRecorder
- type Exit
- type StepWriter
Constants ¶
const ( // Compute is the deadline of a case that only computes in memory and reads repository files. Basis: // the largest of such cases (parse and emit of the dbspec stress document, the fuzz seed corpus) finishes // within seconds, so a case that exceeds one minute is stuck. Compute = time.Minute // Database is the deadline of a case that connects to the database of TEST_ENV and runs a fixed number of statements. // Basis: such a case runs up to a few hundred statements, including creating and dropping databases, // and two minutes is ample, including the time spent waiting for locks on a shared server. Database = 2 * time.Minute // Process is the deadline of a case that runs subprocesses such as `go build`, `go run`, php, node, and Rust binaries. // Basis: `go run` and `go build` take minutes to recompile the packages and // dependencies when the build cache is empty. Process = 5 * time.Minute )
The deadline tiers. A case uses the tier that fits its work; work that takes longer than its tier uses its own deadline, with the basis stated in a comment.
const Grace = 5 * time.Second
Grace is the time to wait for the process to end after the deadline has passed. A case that follows Context can fail with its own error at the deadline and finish its cleanup; only a stuck case that does not follow Context ends after Grace.
Variables ¶
This section is empty.
Functions ¶
func Bounded ¶ added in v0.0.19
Bounded runs work in its own goroutine and waits for its result for at most wait. A panic of work is its error. ok is false when work has not returned by then, and its result is dropped.
func CatchExit ¶ added in v0.0.19
func CatchExit(code *int)
CatchExit is deferred by a command's run function, with a pointer to its named result code: it turns an Exit panic into the code, and re-panics any other value.
func Close ¶ added in v0.0.19
Close closes c and fails t with the error of its Close. A test defers it, or calls it in t.Cleanup, for the resources it opens, so that a failed Close is a failure of the test and not a lost error.
func Group ¶
Group marks a test that groups cases, each started with Start. The group itself has no deadline and writes no line.
func MySQLConfig ¶ added in v0.0.19
MySQLConfig returns the go-sql-driver configuration of the MySQL client DSN uri: the user, the password, and the database of its path, over TCP to its host, or over the unix socket named by its socket query parameter.
func ParityImplementations ¶ added in v0.0.19
ParityImplementations returns the names of the implementations that the config/parity.json of the repository at root declares. A missing or invalid file panics, since the tests that read it cannot run without it.
func Run ¶
Run runs one case for a non-test runner (the check command). work must follow c.Context(). If work has not returned after the deadline plus Grace, it returns an error. The error of work is the result.
func RunLong ¶
RunLong runs one long job (build, install, tool run) for a non-test runner without a deadline. So that a slow but normal job does not fail because of the clock, no timer is set. Success and failure are decided by the result work observed (the command's exit code and errors). c.Context() never ends.
func SequenceNameRows ¶ added in v0.0.19
func SequenceNameRows[T interface {
GetSeq() (int64, error)
GetName() (string, error)
}](t testing.TB, rows interface{ Slice() []T }) [][2]any
SequenceNameRows reads typed sequence and name values from a client model collection. Native SQL rows retain their independent scanners and expected-value checks.
func StallGuard ¶
func StallGuard(parent context.Context, limit time.Duration) (ctx context.Context, progress func(), stop func())
StallGuard returns a context that is canceled, with a cause that names the limit, when progress is not called within limit. progress restarts the limit; stop releases the guard.
func StepBudget ¶
StepBudget is the deadline of a case that does the given number of steps one after another.
func Warn ¶
Warn writes the line `WARNING <message>` saying that a performance measurement exceeded the document's reference value. It measures and reports performance but does not fail the test (AGENTS.md): a warning is not a failure. The message carries the measured value, the reference value, and the machine. The check runner collects this line into the run record and summary, and also writes it as a GitHub Actions `::warning::` annotation.
Types ¶
type Case ¶
type Case struct {
// contains filtered or unexported fields
}
Case is one running case. log takes one step line: in a test it is the test's log, and in a runner it is stdout.
func Of ¶
Of is the case started on t, or otherwise the case started on the nearest enclosing test wrapping t. It is used by a helper that does not take a case value to log its steps to that case's log. If no case was started, it fails t.
func Start ¶
Start starts t as a case under a deadline. Context ends at the deadline. Adding Grace to the deadline If it has not ended after that time, it writes the diagnostic and the stacks of all goroutines to stderr and ends the test binary, because a stuck case does not return by itself. The result is reported to t by go test.
func (*Case) Step ¶
Step writes one step to the case's log. In a test it is t.Log, so go test -v and -json show it; in a runner it is one line on stdout. A case that can run longer than a minute calls Step at each step.
func (*Case) StepWriter ¶
func (c *Case) StepWriter() *StepWriter
StepWriter returns a writer that records lines as steps of c.
type EventRecorder ¶ added in v0.0.19
type EventRecorder[T any] struct { // contains filtered or unexported fields }
EventRecorder collects typed events from a callback-based source.
func NewEventRecorder ¶ added in v0.0.19
func NewEventRecorder[T any]() *EventRecorder[T]
NewEventRecorder creates an empty recorder for a test's event subscription.
func (*EventRecorder[T]) Events ¶ added in v0.0.19
func (r *EventRecorder[T]) Events() []T
Events returns the events recorded so far.
func (*EventRecorder[T]) Record ¶ added in v0.0.19
func (r *EventRecorder[T]) Record(event T) error
Record appends one event and is suitable as an event subscription callback.
func (*EventRecorder[T]) Reset ¶ added in v0.0.19
func (r *EventRecorder[T]) Reset()
Reset clears the recorded events without changing the subscribed callback.
type Exit ¶ added in v0.0.19
type Exit int
Exit is the panic by which a command's run ends with an exit code: its value is the code. A run that is deferred CatchExit turns it into the code it returns.
type StepWriter ¶
type StepWriter struct {
// contains filtered or unexported fields
}
StepWriter is a writer that, for each non-blank line written, records one Step line. It records the progress output of a subprocess such as a build as the case's steps. When the process ends, Flush writes the final line.
func (*StepWriter) Flush ¶
func (w *StepWriter) Flush()
Flush records the output left without a line ending as a step line.
Source Files