Tagging Slow Suites

## The shape A slow suite that needs a real database is put behind an opt-in constraint like this: ```go //go:build integration package migrate_test import "testing" func TestApplyMigrationsAgainstRealDB(t *testing.T) { // only compiled when the integration tag is supplied } ``` The first line is the constraint. The blank line after it is not decoration: a `//go:build` comment counts as a build constraint only when it appears before the package clause and is followed by a blank line. Without the blank line it becomes a doc comment on the package, the constraint disappears, and the file is compiled into every build — the exact opposite of what you wanted, and a mistake that is easy to miss because everything still passes, just slowly. ## What the go command does with it Build constraints are evaluated while the go command is deciding which files make up the package, long before anything is compiled. If the constraint is not satisfied, the file is not parsed, not type-checked, not compiled and not linked. This has three consequences worth stating out loud: 1. Excluding a suite this way is free at run time — there is no test to skip, because there is no test. 2. Nothing reports it. An excluded test cannot print a SKIP line, so an ordinary run gives you no hint that the suite exists. 3. Errors inside the file are invisible in the default build. A rename in the package under test can leave the tagged file uncompilable for weeks while the pipeline stays green. ## Opting in `go test -tags=integration ./...` puts the tag into the build context and the file comes back. The flag takes a comma-separated list — `-tags=integration,slow` — and the same flag exists on `go build`, `go vet` and `go list`, which matters when you want to inspect or lint the tagged configuration rather than run it. An unrecognised tag is not an error. `-tags=integraton` (misspelled) satisfies nothing, the file stays excluded, and the command exits 0. The failure mode of build tags is always silence. ## Granularity: per file, never per function A build constraint applies to a whole file. There is no way to constrain a single test function, so gating a suite means physically splitting the package's tests: the fast ones stay in `migrate_test.go`, the slow ones move to `migrate_integration_test.go` with the constraint on top. When splitting is awkward — for instance, a handful of table entries inside one test are the slow part — a `testing.Short()` guard is the better mechanism, because it works per test and leaves the file in the build. ## Choosing a tag name Tag names are arbitrary identifiers; `integration` is only a convention, not something the toolchain knows. Because they are arbitrary, they are also unchecked, which argues for keeping the set small, writing it down, and having exactly one command per tag in the pipeline so nobody has to guess. Prefer a name that describes what the suite *needs* rather than how long it takes: what changes over time is the run time, not the dependency on external infrastructure. ## The operational half Adding the tag is one line; keeping the suite alive is the actual work. Since the default build does not compile the file, the tagged configuration needs a scheduled run — and the result of that run has to be treated as a real signal, with an owner, rather than a job whose red state is background noise. A cheap intermediate step is running `go vet -tags=integration ./...` or `go build -tags=integration ./...` on every push: it type-checks the excluded files in seconds without paying for the suite itself, and catches the rot that silence would otherwise hide.