Documentation
¶
Overview ¶
Package testlayers gates tests by execution layer.
GoGraph organises its test corpus into three layers:
- short — runs on every PR; default `go test ./...` with no tags. Each package must finish in well under one minute.
- soak — minutes-long mixed workloads. Enabled by the `soak` build tag, or at runtime by setting `SOAK_FULL=1` (legacy env var preserved for backward compatibility). The pre-existing `stress` and `soakfull` build tags are considered part of the soak family.
- nightly — hours-long, runner-expensive scenarios. Enabled by the `nightly` build tag, or at runtime by setting `GOGRAPH_NIGHTLY=1`.
Tests that cannot be split into a separate file with a build-tag header (for example, a single-file scenario that mixes short assertions with optional soak-only steps) should call RequireSoak or RequireNightly at the top of the test body to skip cleanly when the corresponding layer is inactive. New tests should prefer compile-time gating (build tags) over runtime skipping wherever practical: a build-tag-gated file simply does not compile out of layer, which is both faster and safer than a runtime skip.
Sample invocations:
go test ./... # short layer only go test -tags=soak ./... # short + soak go test -tags=nightly ./... # short + soak + nightly SOAK_FULL=1 go test ./... # short + soak (env opt-in) GOGRAPH_NIGHTLY=1 go test ./... # short + soak + nightly (env opt-in)
The full layer specification lives in docs/test-layers.md.
Index ¶
Constants ¶
const IsNightly = false
IsNightly reports, at compile time, whether the binary was built with the `nightly` build tag. This stub is selected when the tag is absent; the variant in testlayers_nightly.go sets it to true.
const IsSoak = false
IsSoak reports, at compile time, whether the binary was built with a build tag in the soak family. This stub is selected when none of `soak`, `nightly`, `soakfull`, or `stress` is active; the variant in testlayers_soak.go sets it to true for any of those tags (#1810).
Variables ¶
This section is empty.
Functions ¶
func Instrumented ¶ added in v0.11.0
func Instrumented() bool
Instrumented reports whether coverage instrumentation is active, for a caller that wants to adjust rather than skip.
func RequireNightly ¶
RequireNightly skips the calling test unless the nightly layer is active. A test is considered to be running under the nightly layer when the binary was built with `-tags=nightly`, or when the environment variable GOGRAPH_NIGHTLY=1 is set.
Prefer placing nightly-only tests in their own file with a `//go:build nightly` header. Use RequireNightly only when splitting the test out is impractical.
func RequireSoak ¶
RequireSoak skips the calling test unless the soak layer is active. A test is considered to be running under the soak layer when the binary was built with `-tags=soak` (or any superset such as `nightly`), or when the environment variable SOAK_FULL=1 is set, or when GOGRAPH_NIGHTLY=1 is set (nightly implies soak).
Prefer placing soak-only tests in their own file with a `//go:build soak` header. Use RequireSoak only when splitting the test out is impractical.
func RequireUninstrumented ¶ added in v0.11.0
RequireUninstrumented skips tb when the binary was built with coverage instrumentation, which removes the environment precondition a concurrency-EFFECT control depends on. See the file comment for the measurements.
detail must name the quantity the caller was about to assert on, so the skip reads as a stated precondition rather than as an absence. Callers that have not measured anything yet should say what they were going to measure.
It is for CONTROLS ONLY — a test whose subject is whether the environment can still demonstrate an effect. A test whose subject is the module must keep asserting, or coverage runs stop gating the module.
Types ¶
This section is empty.
Source Files