What does the go test -short flag actually do, and how does a slow test opt out under it?

## The flag is a boolean, not a filter `go test -short` is often described as "skip the slow tests", which gets the mechanism backwards. The `go` command translates `-short` into `-test.short` on the compiled test binary, and the `testing` package stores it. The only observable effect is that `testing.Short()` returns `true`. No test is selected, deselected, reordered or timed out because of it. If nobody in the package ever calls `testing.Short()`, then `go test -short ./...` and `go test ./...` do exactly the same work. ## The convention you have to write yourself The whole contract lives in the test: ```go func TestMigrateLargeSchema(t *testing.T) { if testing.Short() { t.Skip("skipping large-schema migration in short mode") } // ... applies several hundred migrations against a real database } ``` `t.Skip` records the message, marks the test skipped and stops it immediately — it is not a failure, the package still reports `ok`, and the process exit status stays 0. `t.Skipf` takes a format string; `t.SkipNow` skips without a message. The same guard works at the top of a subtest or inside a helper, since `Short()` is just a function call. ## Where the value comes from `testing.Short()` reads a flag that the test binary registers at start-up and parses before it runs any test function. That is why calling it from a package-level variable initializer is a mistake: those initializers run before the testing flags exist, and the call panics rather than returning a plausible-looking `false`. Keep the call inside the test function body, where the value is real. ## What the short run costs and what it buys Because the guarded test is ordinary code in an ordinary file, it is compiled, linked and type-checked on every build, short or not. The `go test` default vet pass sees it. A rename or a signature change in the package breaks it immediately, so the test cannot silently rot. That is the central difference from putting the same suite behind a build constraint, where the file is not part of the build at all in the default run and stops being checked by anything. The cost is that everything the test *imports* and *links* is still paid for in the short run. If the slow test needs a heavyweight dependency, the fast build still pulls it in; only the run time is saved. If the suite genuinely cannot compile or link in a normal developer environment, `testing.Short()` is the wrong tool and a build constraint is the right one. ## Reading the output Without `-v`, `go test` prints one line per package (`ok`, or a failure) and skipped tests are invisible — the package that skipped every one of its tests still says `ok`. With `-v` you get `--- SKIP: TestMigrateLargeSchema (0.00s)` followed by the file, line and skip message. That visibility is a real feature: someone reading a short run's verbose log can enumerate exactly what was not exercised, which is impossible for a suite that was excluded from the build. ## Practical use Two commands, one repository: - `go test -short ./...` — what a developer runs constantly and what a fast pre-merge job runs. Fast, and every file still compiles. - `go test ./...` — the full run, on a schedule or before a release. The convention is worth applying consistently: an unguarded slow test in a package where every peer is guarded is the reason a "short" run takes four minutes. Conversely, guarding a test that runs in 200 ms adds a branch and buys nothing. Reserve the guard for tests whose cost is measured in seconds and whose failure the fast run does not need to catch.