Testing

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. Run normal Go test suites with Rask through mise. Rask keeps package-level test runs fast while preserving the standard Go test behavior.

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. Use package structure, test names, and helper names to communicate test scope. Keep unit tests close to the package under test. Put expensive cross-service tests in an integration/ subdirectory when that makes the boundary clearer.

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 -- rask ./pkg/cache

Before pushing, run the full test suite:

mise run test

What is next

Use these guides for deeper patterns:

Internal workflow

Quality

Why we test

What to test

Testing observability

Go testing

Test organization

Writing test helpers

Resource cleanup

Running tests

What is next

​Why we test

​What to test

​Testing observability

​Go testing

​Test organization

​Writing test helpers

​Resource cleanup

​Running tests

​What is next

Why we test

What to test

Testing observability

Go testing

Test organization

Writing test helpers

Resource cleanup

Running tests

What is next