proposal: cmd/go,cmd/testmain: extract `_testmain.go` generator into a standalone tool

[podtserkovskiy]

Problem

go test command synthesises a _testmain.go file that wires the user's Test*/Benchmark*/etc functions into testing.MainStart.

The generator lives inline in cmd/go/internal/load/test.go. There is no standalone cmd/testmain binary.

• Buck2 maintains fork buck2/prelude/go/tools/testmaingen.go
• Bazel rules_go maintains fork rules_go/go/tools/builders/generate_test_main.go

I maintain the Buck2 fork. Keeping it in sync with upstream testing internals across Go releases is recurring work, and the fork has accumulated subtle behavioral differences from go test. A shared standalone generator would let both Buck2 and rules_go drop their forks and stay aligned with cmd/go.

Proposed Change

Add a cmd/testmain binary, pre-built like other Go tools, that cmd/go execs via base.Tool("testmain"), replacing the in-process call to cmd/go/internal/load.formatTestmain.

Buck2 and rules_go can adopt it via cmd/testmain call.

CLI Sketch

The tool reads test sources and writes the generated _testmain.go:

go tool testmain [flags] [@responsefile]
  -o FILE              output file (use "-" for stdout)
  -importpath PATH     package import path
  -modulepath PATH     module path (optional)
  -testfile FILE       internal test source (repeatable)
  -xtestfile FILE      external test source (repeatable, package foo_test)
  -covermode MODE      "" | "set" | "count" | "atomic"
  -coverpkg PATH       resolved cover-package import path (repeatable)
  -coverpath PATTERN   user-typed -coverpkg pattern (repeatable, banner)
  @responsefile        GCC-style, via cmd/internal/objabi.Flagparse

Integration

• cmd/go: Switch formatTestmain to a subprocess call.

• Buck2 (out of scope): Drop prelude/go/tools/testmaingen.go and exec cmd/testmain. Buck handles its working-directory requirement (resources colocated with the binary) on the Buck side.

• rules_go (out of scope): Drop go/tools/builders/generate_test_main.go and exec cmd/testmain. rules_go has additional features the standard generator does not provide (Bazel test protocol — TESTBRIDGE_*, sharding, XML_OUTPUT_FILE, TEST_TIMEOUT — and lcov coverage output). They live in the generated main() today, landing them elsewhere will likely need new extension points in cmd/testmain or in testing/internal/testdeps, scoped by the rules_go maintainers.

Migration is opt-in. Existing forks keep working.

cmd/testmain is stricter about test-function signatures than Buck and rules_go are today; the upstream rules will be enforced once they migrate.

Had a great chat about this with @aclements and @matloob at GopherCon, felt like we were on the same page.

[gabyhelp]

Related Issues

• proposal: cmd/go: breakout testmain generation functionality into its own tool #30421 (closed)
• proposal: go/test: add a package to facilitate test tooling #47101 (closed)
• testing: go test -n is missing the creation of _testmain.go #66592
• cmd/go: generated test main files do not have generated comment #31971 (closed)

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}

[gopherbot]

Change https://go.dev/cl/775560 mentions this issue: cmd/go,cmd/testmain: extract _testmain.go generation into a tool

[podtserkovskiy]

Since this doesn't touch the public API or impact users directly, do you think we could bypass the full proposal paperwork? I'd love to just align with the cmd/go maintainers on the implementation so we can get this moving.

I’ve uploaded CL 775560 to show what I have in mind. What do you think?

[seankhliao]

a new command is public api

[podtserkovskiy]

Fair point! I was mainly thinking that since this targets a niche group of build-system maintainers rather than general Go developers, we might be able to keep the process a bit leaner.
But if you think a formal proposal is still the best path, I'm happy to follow this path.

[matloob]

I totally think we should make the testmain generation logic available but we would need a proposal to add a new command.

But I'm not sure we should add a new command (at least one that's pre-built). We've been going in the direction of reducing the number of tools shipped in the go distribution to reduce the distribution size. I think we might want to make a go package available that exposes the functionality- the go command can invoke the logic directly, and others can build a simple wrapper around it. Maybe (haven't thought too deeply about this, just throwing out an idea) we can add it to tools and then vendor it in for the go command?

[podtserkovskiy]

Maybe (haven't thought too deeply about this, just throwing out an idea) we can add it to tools and then vendor it in for the go command?

That would work for me as well. I'm happy to work on the implementation once the proposal is reviewed and accepted. Is there anything I can do to help move this forward or provide more details at this stage?