|
| 1 | +# Testing |
| 2 | + |
| 3 | +After any code change, run `go test ./...` from the project root and all tests must pass before considering the task complete. |
| 4 | + |
| 5 | +These conventions follow the patterns established in `internal/config/*_test.go`. Apply them to new tests; only deviate when there is a clear, code-specific reason. |
| 6 | + |
| 7 | +## Naming |
| 8 | + |
| 9 | +- Method tests: `Test<Type>_<Method>` — e.g. `TestAppOptions_UnmarshalTOML`, `TestAppOptions_Clone`, `TestAppOptions_Merge`. |
| 10 | +- Free-function tests: `Test<Function>` — e.g. `TestCheckDomainPattern`, `TestMustParseBytes`. |
| 11 | +- Subtest names use lowercase phrases describing the scenario: `"valid general options"`, `"nil receiver"`, `"merge values"`, `"invalid type"`. |
| 12 | + |
| 13 | +## Table-driven tests |
| 14 | + |
| 15 | +Default to table-driven. The slice is always named `tcs`, never `tests` / `cases`: |
| 16 | + |
| 17 | +```go |
| 18 | +tcs := []struct { |
| 19 | + name string |
| 20 | + input any |
| 21 | + wantErr bool |
| 22 | + assert func(t *testing.T, o AppOptions) |
| 23 | +}{ |
| 24 | + // ... |
| 25 | +} |
| 26 | + |
| 27 | +for _, tc := range tcs { |
| 28 | + t.Run(tc.name, func(t *testing.T) { |
| 29 | + var o AppOptions |
| 30 | + err := o.UnmarshalTOML(tc.input) |
| 31 | + if tc.wantErr { |
| 32 | + assert.Error(t, err) |
| 33 | + } else { |
| 34 | + assert.NoError(t, err) |
| 35 | + if tc.assert != nil { |
| 36 | + tc.assert(t, o) |
| 37 | + } |
| 38 | + } |
| 39 | + }) |
| 40 | +} |
| 41 | +``` |
| 42 | + |
| 43 | +Common struct fields (use the names that fit the test, not all of them): |
| 44 | +- `name string` — required |
| 45 | +- `input` — input value, typed appropriately |
| 46 | +- `expected` — expected value when comparison is a single equality |
| 47 | +- `wantErr bool` — expected error flag |
| 48 | +- `wantPanic bool` — for `Must*` functions |
| 49 | +- `assert func(t *testing.T, ...)` — closure for non-trivial output verification (multi-field structs, pointer identity, etc.) |
| 50 | +- For `Merge`: `base`, `override`, `assert` |
| 51 | +- For `Clone`: `input`, `assert(t, input, output)` so the closure can verify identity vs. value |
| 52 | + |
| 53 | +For simple validators where each case is just `(name, input, wantErr)`, use compact positional literals: |
| 54 | + |
| 55 | +```go |
| 56 | +tcs := []struct { |
| 57 | + name string |
| 58 | + input string |
| 59 | + wantErr bool |
| 60 | +}{ |
| 61 | + {"valid domain", "example.com", false}, |
| 62 | + {"invalid empty", "", true}, |
| 63 | +} |
| 64 | +``` |
| 65 | + |
| 66 | +## When inline `t.Run` is acceptable |
| 67 | + |
| 68 | +When a test needs a handful of distinctly-shaped scenarios that don't share a struct cleanly (e.g. parsing different TOML snippets), inline `t.Run` blocks are fine — see `TestSegmentPlan_UnmarshalTOML`. Don't force a table when each case is structurally different. |
| 69 | + |
| 70 | +## Assertions |
| 71 | + |
| 72 | +- Use `github.com/stretchr/testify/assert` for normal checks. |
| 73 | +- Use `github.com/stretchr/testify/require` only when subsequent code in the test cannot meaningfully run on failure (setup invariants, "function never called"). See `internal/config/cli_test.go` for examples. |
| 74 | +- Use `assert.NotSame` to verify `Clone` returns a distinct pointer. |
| 75 | +- Use `assert.Panics` / `assert.NotPanics` for `Must*` functions. |
| 76 | + |
| 77 | +## Constructing values |
| 78 | + |
| 79 | +- Build optional pointer fields with `lo.ToPtr(...)` from `github.com/samber/lo`. Do not write `func() *T { v := x; return &v }()` helpers. |
| 80 | +- Build `*net.TCPAddr` with explicit `&net.TCPAddr{IP: net.ParseIP(...), Port: ...}`. |
| 81 | + |
| 82 | +## Coverage |
| 83 | + |
| 84 | +Each function should have tests covering: happy path, edge cases, and failure cases. For `UnmarshalTOML` always include an `"invalid type"` case; for `Clone` always include a `"nil receiver"` case; for `Merge` always include `"nil receiver"` and `"nil override"` cases. |
| 85 | + |
| 86 | +## Section grouping |
| 87 | + |
| 88 | +When a single `_test.go` file covers multiple related types, separate them with ASCII box headers (matches `types_test.go`): |
| 89 | + |
| 90 | +```go |
| 91 | +// ┌─────────────────┐ |
| 92 | +// │ GENERAL OPTIONS │ |
| 93 | +// └─────────────────┘ |
| 94 | +``` |
| 95 | + |
| 96 | +## Parallelism |
| 97 | + |
| 98 | +Current config tests do not use `t.Parallel()`. Don't add it unless the rest of the suite is being migrated together — mixing parallel and serial tests in the same package can mask shared-state bugs. |
0 commit comments