docs-ssot go-test.instructions.md

Go Test Rules

These rules apply to all *_test.go files in mcp-server/. Read them before writing any test.

Package declaration

Choose based on whether the test needs unexported symbols:

• Same package (package orchestrator): when the test needs access to unexported types, functions, or variables. Used in orchestrator/ and other pure-logic packages.
• External package (package state_test): when tests should only touch the exported API. Used in state/ and tools/ to keep tests honest about the public surface.

Do not mix both styles in the same directory.

Parallelism

Every test function and every t.Run subtest must call t.Parallel() as its first statement. This is enforced by the tparallel linter.

func TestFoo(t *testing.T) {
    t.Parallel()

    t.Run("case", func(t *testing.T) {
        t.Parallel() // required inside every t.Run subtest
        ...
    })
}

Exception: tests that mutate OS-level global state (environment variables, working directory) must NOT call t.Parallel(). Add a comment explaining why.

In Go 1.22+, the loop variable in for _, tc := range tests is scoped per iteration — tc := tc capture workarounds are not needed and must not be added.

Table-driven tests

Use table-driven tests with t.Run when two or more cases share the same function signature and assertion pattern. Do not write individual TestFoo_CaseA, TestFoo_CaseB functions for structurally identical cases — merge them into one table.

tests := []struct {
    name  string
    input string
    want  string
}{
    {name: "foo", input: "a", want: "b"},
    {name: "bar", input: "c", want: "d"},
}
for _, tc := range tests {
    t.Run(tc.name, func(t *testing.T) {
        t.Parallel()
        got := fn(tc.input)
        if got != tc.want {
            t.Errorf("fn(%q) = %q, want %q", tc.input, got, tc.want)
        }
    })
}

For 2D matrix tests (e.g. sourceType × effort), use tc.sourceType+"/"+tc.effort as the subtest name — the / creates a hierarchy that makes -run filtering precise.