testlayers

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
• func RequireNightly(tb testing.TB)
• func RequireSoak(tb testing.TB)

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 the `soak` build tag. This stub is selected when the tag is absent; the variant in testlayers_soak.go sets it to true.

Functions

func RequireNightly

func RequireNightly(tb testing.TB)

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

func RequireSoak(tb testing.TB)

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.