Tests and documentation

Testing runs in two tiers. The unit tier is what each repository's check runs: hermetic, black-box, on every pull request. The integration and acceptance suites run a real process or a real engine, each behind its own task or CI job. A test proves a behavior only if it can fail; marathon's standards-reviewer names the ways a green test lies, tautological, structure-sensitive, or unable to fail, and rewrites or deletes such a test.

The unit tier: black-box and hermetic

Every test lives in an external test package (package <pkg>_test), co-located with the source it covers, and drives only the package's exported API; unexported code is covered through the exported entry points that use it. The one white-box file allowed is export_test.go, and it exists only to export a hook for what the API cannot reach: a clock or a probe it cannot reach deterministically, or a fixture node added before Run, such as go-web-sdk-template's AppendReactor. The tests that use the hook stay in the external package. Check enforces the rule: every repository's golangci-lint configuration enables the testpackage linter with its skip regexp narrowed to export_test\.go.

The tier is hermetic: go test -race ./... passes with no service running. A package proves its behavior with fakes, scripted drivers, and loopback listeners:

A shared test helper stays in its test package until more than one test package needs it; then it is hoisted into a <pkg>test package, following the standard library's httptest and fstest naming, under internal/ unless another module's tests consume it.

A composition root's test fixtures live in an internal <app>test package even when only one test package consumes them. The fixtures are built over the composition the root publishes, its graph and its nodes: a fixture replaces a node's constructor with a substitute or observes which nodes a build reaches, and wraps no production constructor. The composition root's tests then need no export_test.go beyond the clock, probe, or fixture-node hook above. go-cli-sdk-template's template/internal/apptest holds its internal/app fixtures this way, and so does go-web-service's internal/apptest, whose fixture replaces the meter provider node's constructor with one over a manual reader, so the unit tier proves the outcomes the sweep metrics hook records.

Integration and acceptance suites, and where each runs

Each suite that needs a real process or engine sits behind a build tag or an environment variable, so the unit tier never reaches it:

The integration tier drives a service only through production surfaces: configuration by environment variable, the API and the admin mount for state, the network for faults, and signals and the exit code for lifecycle. It observes through the same surfaces, plus the log for what only the log records and, in go-web-service, the object store read beneath the API and the telemetry exporter, which configuration aims at an OTLP receiver the test runs (the sweep metrics test sets APP_OBSERVABILITY_ENDPOINT and OTEL_METRIC_EXPORT_INTERVAL). It drives a CLI through configuration by environment variable and its arguments, and observes it through its standard output, its standard error, and its exit code. Nothing in the runtime exists for the tests' sake.

Integration toolkits and harness rules

A library whose infrastructure an integration suite exercises ships the toolkit beside it. go-core's process/processtest runs a program as its binary and drives it through its output, its signals, and its exit code; go-web-sdk's webtest is the client a suite drives a running service through. Both suites build their harness on them, and the harnesses follow these rules:

Toolkit mechanics, such as dropping the race runtime's exit sleep from a launched binary, stay with the toolkit's own code and documentation.

doc.go and godoc

Each API package has one doc.go holding only the package comment, and that comment is the authoritative description of the package's API. It inventories every exported identifier with a one-clause role and points to the symbols for the rest; each contract is stated once, on its symbol's own doc comment. Production symbols carry doc comments. A short method that exists only to satisfy a standard library interface, Error() string on a type whose comment already says what the error means or String() string on a Stringer, needs no comment of its own. Whether an inventory is complete is the reviewer's judgement; no check enforces it.

Keyboard shortcuts

Settings