A common mistake is assuming that supplying a tag runs only tagged tests. A build tag is a special comment at the beginning of a Go file, followed by an empty line, that controls whether the file enters a build or test invocation. Untagged files remain included when a matching tag is supplied. section 11.1.1
Use build tags when you need to:
- Select implementation files conditionally, such as including a file only when cgo is enabled. section 11.1.1
- Classify integration tests with //go:build integration. Running go test without tags omits the file; running with --tags=integration includes it alongside untagged tests. section 11.1.1
- Run only one category by adding //go:build !integration to unit-test files, so those files are excluded when integration is enabled. section 11.1.1
- Exclude tests from race-enabled builds with //go:build !race when they behave incompatibly with race detection. section 11.2
Tagged versus untagged tests
With an integration-tagged TestInsert and an untagged TestContract, go test -v . runs only TestContract. Running go test --tags=integration -v . runs both. If silent omission is risky, an environment-variable guard can keep the test visible and call t.Skip("skipping integration test") when INTEGRATION is not true. section 11.1.1 section 11.1.2
