Skip to main content

​
Why we test

Tests exist to give confidence. Confidence to ship changes quickly, confidence that refactoring will not break production, confidence that the system behaves as expected. A test suite with 90 percent coverage that misses critical edge cases is less valuable than one with 60 percent coverage that catches real bugs. We prioritize quality over quantity. A single well-designed test that validates complex business logic is worth more than a dozen tests that exercise trivial code paths. When writing tests, ask what could go wrong in production that this test would catch. Treat test code as production code. Tests are part of the system contract, not a safety net added after implementation. They must be readable, typed, deterministic, reviewed with the same care as application code, and maintained when behavior changes. Every test must make its guarantee clear to the reader. The guarantee is the production behavior that would break if the test failed. A future reader must be able to understand what risk the test covers without reverse engineering setup, mocks, or fixtures. Document non-obvious guarantees with docstrings or comments. Use them when a test protects a security property, regression, invariant, concurrency condition, failure mode, or business rule that the test name cannot fully explain. 
// TestTokenParserRejectsAlgorithmConfusion guarantees that tokens signed with
// one algorithm cannot be accepted under another algorithm. This protects the
// verifier from accepting attacker-controlled headers as trusted policy.
func TestTokenParserRejectsAlgorithmConfusion(t *testing.T) {
    // ...
}
Do not document obvious mechanics. A comment that says “creates a workspace” above createWorkspace(t) adds noise. A comment that explains why cross-workspace access must return 404 instead of 403 documents a guarantee.

​
What to test

Invest testing effort where bugs would hurt most. High value targets: Business logic with complex conditionals, error handling paths, concurrent code with race potential, security sensitive operations, data transformations that could silently corrupt. Lower value targets: Simple getters and setters, straightforward pass-through functions, code that delegates to well-tested libraries. Skip entirely: Tests that verify the programming language works. Ask what bug this test would catch that the compiler, a code review, or a more meaningful test would not.

​
Testing observability

Do not verify every log line or metric increment. Test metrics that drive alerts or SLOs. Test that error conditions produce the logs operators need for debugging. 
func TestRateLimiter_EmitsRejectionMetric(t *testing.T) {
    collector := &testMetricCollector{}
    limiter := NewRateLimiter(Config{Limit: 1}, collector)

    limiter.Allow()
    limiter.Allow()

    require.Equal(t, 1, collector.Count("rate_limit_rejected_total"))
}

​
Go testing

All Go tests use github.com/stretchr/testify/require for assertions. We build and test with Bazel rather than go test directly. Bazel provides hermetic builds, intelligent caching, and precise dependency tracking.

​
Test organization

Tests live alongside the code they test. A file cache.go has its tests in cache_test.go in the same directory. For integration tests that require substantial setup or external dependencies, create an integration/ subdirectory when it improves clarity. Organize tests around guarantees, not implementation details. File names, test names, table cases, and helper names must help a reader answer which behavior is protected and why it matters. Bazel requires each test target to declare a size that determines its timeout and resource allocation. Unit tests must be small. Integration tests that spin up containers must be large. 
go_test(
    name = "cache_test",
    size = "small",
    srcs = ["cache_test.go"],
    deps = [":cache", "@com_github_stretchr_testify//require"],
)

​
Writing test helpers

Every helper function must call t.Helper() as its first line. 
func createTestWorkspace(t *testing.T) *Workspace {
    t.Helper()
    ws, err := db.CreateWorkspace(ctx, "test-workspace")
    require.NoError(t, err)
    return ws
}

​
Resource cleanup

Tests that acquire resources must clean them up. Use t.Cleanup() instead of defer. 
func TestWithDatabase(t *testing.T) {
    db := setupTestDatabase(t)
    t.Cleanup(func() {
        db.Close()
    })
}

​
Running tests

During development, run tests for the package you are working on: 
mise exec -- bazel test //pkg/cache:cache_test --test_output=errors
Before pushing, run the full test suite: 
mise run test

​
What is next

Use these guides for deeper patterns: