go-test-reorg

---

name: go-test-reorg description: Reorganize Go test files — consolidate related tests into subtests, convert to table-driven style, shorten excessive test names, and reposition tests to match implementation ownership. Args:

Go Test Reorg

Reorganize Go test files in a package for clarity and maintainability. Consolidate related tests into subtests, prefer table-driven style, and eliminate excessively long test names. Keep test behavior unchanged.

Input

User provides a Go package directory path. If not provided, ask for it.

Step 1: Inventory

Read all *_test.go files in the target directory. For each test function, record:

• Function name — the TestXxx or FuzzXxx identifier.
• What it tests — the production function, method, or behavior under test.
• Style — standalone assertion, table-driven, subtest-based, or mixed.
• Size — approximate line count.
• File location — which _test.go file it lives in today.
• Related tests — other test functions that exercise the same or closely related production code.

Also note:

• Helpers — shared test helpers, fixtures, TestMain, custom assertions.
• Special suites — fuzz tests, generated tests, compatibility suites. These are left alone.
• Test file sizes — flag files already near the ~2000 line ceiling.

Step 2: Design new test layout

Consolidation rules

• Group tests that exercise the same production function/method/type under one TestXxx with subtests.
• Example: TestParseSimple, TestParseNested, TestParseEmpty, TestParseError → TestParse with subtests "Simple", "Nested", "Empty", "Error".
• If a group of tests share setup/teardown logic, that is a strong signal they belong together.
• Do NOT force unrelated tests together just to reduce top-level test count.

Naming rules

• Top-level test names should be short and map clearly to the thing being tested: TestParse, TestWrite, TestNewBuilder.
• Subtest names describe the scenario: "empty input", "duplicate keys", "nil receiver".
• Avoid redundancy between test name and subtest name. TestParse/"parse empty" is redundant — use TestParse/"empty input".
• If the original long name carries important context, preserve that context in the subtest name, not the top-level name.

Nesting rules

• Maximum 2 levels of subtests: TestFoo/Bar or TestFoo/Bar/Baz. Never deeper.
• Use the first subtest level for logical grouping (e.g., by method, by input category).
• Use the second level only when there is a natural sub-categorization (e.g., TestWriter/"Escape"/"special chars").
• If you are tempted to nest 3+ levels, flatten by making the grouping name more specific.

Table-driven style

• Prefer table-driven tests when a test function exercises the same code path with varying inputs/expectations.
• Table struct fields should have clear names: name, input, want, wantErr — not a, b, expected.
• Each table entry MUST have a name field used as t.Run(tc.name, ...).
• Do NOT force table-driven style when tests have fundamentally different setup, teardown, or assertion logic. A sequence of t.Run subtests with distinct bodies is fine in that case.
• When converting, preserve the original test's assertion logic exactly. Do not simplify or "improve" assertions.

File placement rules

• Tests should live in the _test.go file that matches the production file being tested: parse.go ↔ parse_test.go.
• If tests were in the wrong file (testing parse.go behavior but living in writer_test.go), move them.
• Merge small _test.go files that cover the same production file.
• Keep distinct special-purpose files separate: fuzz tests, generated test suites, compatibility tests.

Sizing rules

• Test files can be up to ~2000 lines. Do not split prematurely.
• If a single test file exceeds ~2000 lines after consolidation, split by production-code area, not arbitrarily.
• Prefer fewer, larger test files over many tiny ones.

Helper rules

• Shared test helpers stay in a dedicated helpers file (e.g., helpers_test.go or testutil_test.go).
• If a helper is used by only one test function, inline it or keep it adjacent to that test.
• TestMain stays in its own file or in the primary test file for the package.

Step 3: Present plan and get approval

Show the user the proposed changes organized by production area:

Production area	Current tests	Proposed structure	Notes

For each consolidation, show:

• Which test functions merge into what.
• The new top-level name and subtest names.
• Which file they move to (if any).

Ask: "Proceed with this reorganization? You can adjust before I start."

NEVER proceed without user approval.

Step 4: Execute

Apply changes according to the approved plan:

1. Convert standalone tests to table-driven or subtest form as planned.
2. Move tests to correct _test.go files.
3. Merge test files where planned.
4. Preserve all test assertions, setup, teardown, and skip logic exactly.
5. Do NOT manually write import blocks — goimports handles this in Step 5.
6. Remove emptied test files.
7. Preserve test helpers and TestMain in their designated locations.

Step 5: Verify

1. Run goimports -w on all new/modified _test.go files.
2. Run gofmt on changed files.
3. Run targeted package tests: go test -v -count=1 ./path/to/package/...
4. Confirm same number of test cases pass as before (compare -v output).
5. Run broader tests as appropriate for package impact.

If verification fails, diagnose and fix before proceeding. A failing test after reorganization means a conversion error — fix it immediately.

Step 6: Report

• Summarize changes by production area.
• List consolidations performed (old names → new structure).
• Report test pass/fail counts before and after.
• Call out any tests intentionally left unconsolidated and why.

Non-Goals

• Do NOT change what is being tested or assertion logic.
• Do NOT add new test cases.
• Do NOT remove or skip existing test cases.
• Do NOT refactor production code.
• Do NOT change test package (package foo_test vs package foo) unless required by a move.