probo/contrib/claude/go-testing.md

Go Testing

Test library: github.com/stretchr/testify (require for fatal, assert for non-fatal).

Package naming

Black-box test packages (package foo_test). White-box (package foo) only when testing unexported functions.

Test naming

Test names follow TestFunctionName_Scenario. Use t.Run for subtests with lowercase descriptive names. Table-driven tests for parameterized cases.

Parallel tests

Always call t.Parallel() at both the top-level test and each subtest.

require vs assert

• require — stops the test immediately on failure. Use for preconditions that would make subsequent assertions meaningless: require.NoError, require.Error, require.ErrorAs, require.Len, require.NotNil, require.True (as a guard).
• assert — logs failure but continues the test. Use for the actual values being verified: assert.Equal, assert.Contains, assert.True, assert.False, assert.Nil.

Rule of thumb: if a failure would cause a nil-pointer panic or make every following assertion nonsensical, use require; otherwise use assert.

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

	t.Run(
		"handoff with custom tool name and description",
		func(t *testing.T) {
			t.Parallel()

			// ... setup ...

			result, err := triage.Run(
				context.Background(),
				[]llm.Message{
					userMessage("How much is my invoice?"),
				},
			)

			require.NoError(t, err)
			assert.Equal(t, "Your invoice is $42.", result.FinalMessage().Text())
			assert.Equal(t, "billing", result.LastAgent.Name())
		},
	)
}

Helpers and mocks

Define mock types and helper functions (e.g. stopResponse, userMessage) at the top of the test file, not inline in each test.