Support integration test coverage system (coverageredesign) (#4397)

go1.25 removes the current runtime code coverage system adopted by
rules_go (nocoverageredesign)
https://go-review.googlesource.com/c/go/+/644997
which makes rules_go incompatible with the latest upcoming version of
go.

The change completely adopts the new integration test friendly
coverageredesign
system (https://go.dev/blog/integration-test-coverage) in rules_go.

Below I describe how the current rules_go coverage system currently
works, what
changes in the new coverage redesign, and what needs to change as a
result in
rules_go.

How nocoverageredesign currently works:

- rules_go invokes `go tool cover` to generate instrumented source files
that
are then passed to the Go compiler (in compilepkg.go). Instrumented
source
files update generated package variable counters.

- The rules_go generated test main (generate_test_main.go) calls
testing.RegisterCover to set a global variable that tracks references to
coverage generated package local variables that coverage instrumented
code
modify (ref:
https://github.com/golang/go/blob/go1.24.5/src/testing/cover.go#L72)
This replicates the behavior in go test's generated test main
(cmd/go/internal/load/test.go)

- rules_go specially adds a call to coverdata.RegisterFile call to all
coverage
instrumented files which connects each of the file coverage counter
variables
with a global object and enables rules_go to customize the file name
that
coverage variables are associated with.

- It's important to note that because rules_go accesses to this global
coverage struct,
it's able to manipulate the file path name associated with coverage
counter variables.
This is important because the lcov format that bazel uses expect exec
root relative files.

- When a test exits, This global object is flushed in a call to
`testing.coverReport()` to
generate a coverage report. This reports gets written a file configured
in
test.coverprofile flag.

- Via a special SetPanicOnExit0 hook, the coverage file set in
test.coverprofile
is coverted to a Bazel friendly Lcov format via logic in
bzltestutil/lcov.go

What changes in coverageredesign:

- A new flexible system for configuring coverage behavior. Instead of a
single
esting.RegisterCover function, there is a new testdeps package that
exposes hooks
to configure behavior.

- The global variable
(https://github.com/golang/go/blob/go1.24.5/src/testing/cover.go#L72)
that tracked all coverage data is completely removed. Instead, functions
in https://pkg.go.dev/internal/coverage/cfile that are called when
writing coverage reports on test exit are internally aware of and able
to access coverage counter variable data.

- Functionality to flush coverage counter variables write to an
intermediate
coverage directory in a binary format. Hooks configured in the testdeps
package
are responsible for translating this binary format into a human readable
coverage
output file.

- 'go tool cover' takes a new package based configuration "pkgcfg"
option that
enables this new coverage instrumentation logic in coverage source
files.

- Coverage counters can be flushed on demand via the APIs of
"runtime/coverage"
This allows coverage to work outside of test situations where coverage
used to rely on exit hooks generated into test mains to flush and write
coverage data.

What needs to change in rules_go as a result:

- Use the new testdeps configuration system in the rules_go generated
test main.
We can following the example of the go test generated test main.
ref:
https://github.com/golang/go/blob/go1.24.5/src/cmd/go/internal/load/test.go#L986

- Invoke 'go tool cover' with the new -pkgcfg flag. We can follow the
example of
how the go toolchain invokes coverage redesign instrumentation in

https://github.com/golang/go/blob/go1.24.5/src/cmd/go/internal/work/exec.go#L1932

- Not strictly necessary but removes technical debt, call
bzltestutil.ConvertCoverToLcov
inside of testdeps.CoverProcessTestDirFunc hook wrapper  instead of the
bzltestutil.LcovTestDeps SetPanicOnExit0 hook.

- Adjust the output of lcov profile to make file path keys in coverage
files
execution root relative.

Implementation Note:

Unfortunately, we still need
github.com/bazelbuild/rules_go/go/tools/coverdata
dependencies in coverage source files because the lcov coverage format
expects file paths associated with coverage data to be execution root
relative. coverageredesign writes Go coverage file data in the format of
`importpath/file_name` which is not execution root (e.g. `src/`)
relative.

During compilation is the only place we have the information to map
`importpath/file_name` to an execution root relative path so we have
to continue to use the trick of generating code that corrects the
file path coverage mapping at runtime.

This makes it hard for coverage to work outside of tests because depend
on a special
github.com/bazelbuild/rules_go/go/tools/coverdata dependency that can't
be
guaranteed because we don't control a generated test main in these
situations.

If Go coverage filepaths can be configured during invocations of the `go
tool cover`, we can break this dependency. I've filed an upstream go
ticket
to descrbe this issue golang/go#74749.

ref #3513

Author: r-hang

go/private/actions/compilepkg.bzl

@@ -120,10 +120,8 @@ def emit_compilepkg(
     )
 
     if cover and go.coverdata:
-        if go.mode.race:
-            cover_mode = "atomic"
-        else:
-            cover_mode = "set"
+        # Always use atomic mode as the "runtime/coverage" APIs require it.
+        cover_mode = "atomic"
         shared_args.add("-cover_mode", cover_mode)
         compile_args.add("-cover_format", go.mode.cover_format)
         compile_args.add_all(cover, before_each = "-cover")

go/private/rules/test.bzl

@@ -120,10 +120,9 @@ def _go_test_impl(ctx):
     arguments = go.builder_args(go, "gentestmain", use_path_mapping = True)
     arguments.add("-output", main_go)
     if go.coverage_enabled:
-        if go.mode.race:
-            arguments.add("-cover_mode", "atomic")
-        else:
-            arguments.add("-cover_mode", "set")
+        # Always use atomic mode as the "runtime/coverage" APIs require it
+        # and test behavior should follow non-test behavior.
+        arguments.add("-cover_mode", "atomic")
         arguments.add("-cover_format", go.mode.cover_format)
     arguments.add(
         # the l is the alias for the package under test, the l_test must be the

go/private/sdk.bzl

@@ -433,14 +433,6 @@ def _sdk_build_file(ctx, platform, version, experiments):
     ctx.file("ROOT")
     goos, _, goarch = platform.partition("_")
 
-    pv = parse_version(version)
-    if pv != None and pv[1] >= 20:
-        # Turn off coverageredesign GOEXPERIMENT on 1.20+
-        # until rules_go is updated to work with the
-        # coverage redesign.
-        if not "nocoverageredesign" in experiments and not "coverageredesign" in experiments:
-            experiments = experiments + ["nocoverageredesign"]
-
     ctx.template(
         "BUILD.bazel",
         ctx.path(ctx.attr._sdk_build_file),

go/tools/builders/compilepkg.go

@@ -17,6 +17,7 @@
 package main
 
 import (
+	"crypto/sha256"
 	"errors"
 	"flag"
 	"fmt"
@@ -243,7 +244,8 @@ func compileArchive(
 	goSrcsNogo := append([]string{}, goSrcs...)
 	cgoSrcsNogo := append([]string{}, cgoSrcs...)
 
-	// Instrument source files for coverage.
+	// Instrument source files in a package for coverage.
+	var coverageCfg string
 	if coverMode != "" {
 		relCoverPath := make(map[string]string)
 		for _, s := range coverSrcs {
@@ -254,6 +256,12 @@ func compileArchive(
 		if cgoEnabled {
 			combined = append(combined, cgoSrcs...)
 		}
+
+		var (
+			coverIn []string
+			coverOut []string
+			srcPathMapping = make(map[string]string)
+		)
 		for i, origSrc := range combined {
 			if _, ok := relCoverPath[origSrc]; !ok {
 				continue
@@ -269,7 +277,16 @@ func compileArchive(
 			case "lcov":
 				// Bazel merges lcov reports across languages and thus assumes
 				// that the source file paths are relative to the exec root.
+				//
+				// In the go's coverageredesign, rules_go no longer is able to
+				// set the filepath key generated to Go's coverage output files
+				// so we keep a mapping from importpath/filename format emitted
+				// by the go runtime in the coverageredesign to the exec root
+				// relative source path required by lcov. We will use this mapping
+				// to write the lcov file with the expected exec root relative source
+				// path.
 				srcName = relCoverPath[origSrc]
+				srcPathMapping[srcName] = path.Join(importPath, filepath.Base(srcName))
 			default:
 				return fmt.Errorf("invalid value for -cover_format: %q", coverFormat)
 			}
@@ -278,12 +295,10 @@ func compileArchive(
 			if ext := filepath.Ext(stem); ext != "" {
 				stem = stem[:len(stem)-len(ext)]
 			}
-			coverVar := fmt.Sprintf("Cover_%s_%d_%s", sanitizePathForIdentifier(importPath), i, sanitizePathForIdentifier(stem))
-			coverVar = strings.ReplaceAll(coverVar, "_", "Z")
 			coverSrc := filepath.Join(workDir, fmt.Sprintf("cover_%d.go", i))
-			if err := instrumentForCoverage(goenv, origSrc, srcName, coverVar, coverMode, coverSrc); err != nil {
-				return err
-			}
+
+			coverIn = append(coverIn, origSrc)
+			coverOut = append(coverOut, coverSrc)
 
 			if i < len(goSrcs) {
 				goSrcs[i] = coverSrc
@@ -292,6 +307,17 @@ func compileArchive(
 
 			cgoSrcs[i-len(goSrcs)] = coverSrc
 		}
+
+		// Modeled after go toolchain's coverage variables configuration.
+		// https://github.com/golang/go/blob/go1.24.5/src/cmd/go/internal/work/exec.go#L1932
+		sum := sha256.Sum256([]byte(importPath))
+		coverVar := fmt.Sprintf("goCover_%x_", sum[:6])
+		coverageCfg = workDir + "pkgcfg.txt"
+		coverOut, err := instrumentForCoverage(goenv, importPath, packageName, coverIn, coverVar, coverMode, coverOut, workDir, relCoverPath, srcPathMapping)
+		if err != nil {
+			return err
+		}
+		goSrcs = append(goSrcs, coverOut[0])
 	}
 
 	// If we have cgo, generate separate C and go files, and compile the
@@ -389,7 +415,7 @@ func compileArchive(
 	}
 
 	// Compile the filtered .go files.
-	if err := compileGo(goenv, goSrcs, packagePath, importcfgPath, embedcfgPath, asmHdrPath, symabisPath, gcFlags, pgoprofile, outLinkObj, outInterfacePath); err != nil {
+	if err := compileGo(goenv, goSrcs, packagePath, importcfgPath, embedcfgPath, asmHdrPath, symabisPath, gcFlags, pgoprofile, outLinkObj, outInterfacePath, coverageCfg); err != nil {
 		return err
 	}
 
@@ -465,6 +491,7 @@ func checkImportsAndBuildCfg(goenv *env, importPath string, srcs archiveSrcs, de
 			return "", errors.New("coverage requested but coverdata dependency not provided")
 		}
 		imports[coverdataPath] = coverdata
+		imports["runtime/coverage"] = nil
 	}
 
 	// Build an importcfg file for the compiler.
@@ -475,7 +502,7 @@ func checkImportsAndBuildCfg(goenv *env, importPath string, srcs archiveSrcs, de
 	return importcfgPath, nil
 }
 
-func compileGo(goenv *env, srcs []string, packagePath, importcfgPath, embedcfgPath, asmHdrPath, symabisPath string, gcFlags []string, pgoprofile, outLinkobjPath, outInterfacePath string) error {
+func compileGo(goenv *env, srcs []string, packagePath, importcfgPath, embedcfgPath, asmHdrPath, symabisPath string, gcFlags []string, pgoprofile, outLinkobjPath, outInterfacePath, coverageCfg string) error {
 	args := goenv.goTool("compile")
 	args = append(args, "-p", packagePath, "-importcfg", importcfgPath, "-pack")
 	if embedcfgPath != "" {
@@ -490,6 +517,9 @@ func compileGo(goenv *env, srcs []string, packagePath, importcfgPath, embedcfgPa
 	if pgoprofile != "" {
 		args = append(args, "-pgoprofile", pgoprofile)
 	}
+	if coverageCfg != "" {
+		args = append(args, "-coveragecfg", coverageCfg)
+	}
 	args = append(args, gcFlags...)
 	args = append(args, "-o", outInterfacePath)
 	args = append(args, "-linkobj", outLinkobjPath)

go/tools/builders/cover.go

@@ -16,31 +16,120 @@ package main
 
 import (
 	"bytes"
+	"encoding/json"
 	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
 	"go/parser"
 	"go/token"
-	"io/ioutil"
-	"os"
 	"strconv"
 )
 
+const writeFileMode = 0o666
+
 // instrumentForCoverage runs "go tool cover" on a source file to produce
 // a coverage-instrumented version of the file. It also registers the file
 // with the coverdata package.
-func instrumentForCoverage(goenv *env, srcPath, srcName, coverVar, mode, outPath string) error {
-	goargs := goenv.goTool("cover", "-var", coverVar, "-mode", mode, "-o", outPath, srcPath)
+func instrumentForCoverage(
+		goenv *env,
+		importPath string,
+		pkgName string,
+		infiles []string,
+		coverVar string,
+		coverMode string,
+		outfiles []string,
+		workDir string,
+		relCoverPath map[string]string,
+		srcPathMapping map[string]string,
+	) ([]string, error) {
+	// This implementation follows the go toolchain's setup of the pkgcfg file
+	// https://github.com/golang/go/blob/go1.24.5/src/cmd/go/internal/work/exec.go#L1954
+	pkgcfg := workDir + "pkgcfg.txt"
+	covoutputs := workDir + "coveroutfiles.txt"
+	odir := filepath.Dir(outfiles[0])
+	cv := filepath.Join(odir, "covervars.go")
+	outputFiles := append([]string{cv}, outfiles...)
+
+	pcfg := coverPkgConfig{
+		PkgPath:   importPath,
+		PkgName:   pkgName,
+		Granularity: "perblock",
+		OutConfig: pkgcfg,
+		Local:     false,
+	}
+	data, err := json.Marshal(pcfg)
+	if err != nil {
+		return nil, err
+	}
+	data = append(data, '\n')
+	if err := os.WriteFile(pkgcfg, data, writeFileMode); err != nil {
+		return nil, err
+	}
+	var sb strings.Builder
+	for i := range outputFiles {
+		fmt.Fprintf(&sb, "%s\n", outputFiles[i])
+	}
+	if err := os.WriteFile(covoutputs, []byte(sb.String()), writeFileMode); err != nil {
+		return nil, err
+	}
+
+	goargs := goenv.goTool("cover", "-pkgcfg", pkgcfg, "-var", coverVar, "-mode", coverMode, "-outfilelist", covoutputs)
+	goargs = append(goargs, infiles...)
 	if err := goenv.runCommand(goargs); err != nil {
-		return err
+		return nil, err
 	}
 
-	return registerCoverage(outPath, coverVar, srcName)
+	for i, outfile := range outfiles {
+		srcName := relCoverPath[infiles[i]]
+		importPathFile := srcPathMapping[srcName]
+		// Augment coverage source files to store a mapping of <importpath>/<filename> -> <execroot_relative_path>
+		// as this information is only known during compilation but is required when the rules_go generated
+		// test main exits and go coverage files are converted to lcov format.
+		if err := registerCoverage(outfile, importPathFile, srcName); err != nil {
+			return nil, err
+		}
+	}
+	return outputFiles, nil
+}
+
+// coverPkgConfig matches https://cs.opensource.google/go/go/+/refs/tags/go1.24.4:src/cmd/internal/cov/covcmd/cmddefs.go;l=18
+type coverPkgConfig struct {
+	// File into which cmd/cover should emit summary info
+	// when instrumentation is complete.
+	OutConfig string
+
+	// Import path for the package being instrumented.
+	PkgPath string
+
+	// Package name.
+	PkgName string
+
+	// Instrumentation granularity: one of "perfunc" or "perblock" (default)
+	Granularity string
+
+	// Module path for this package (empty if no go.mod in use)
+	ModulePath string
+
+	// Local mode indicates we're doing a coverage build or test of a
+	// package selected via local import path, e.g. "./..." or
+	// "./foo/bar" as opposed to a non-relative import path. See the
+	// corresponding field in cmd/go's PackageInternal struct for more
+	// info.
+	Local bool
+
+	// EmitMetaFile if non-empty is the path to which the cover tool should
+	// directly emit a coverage meta-data file for the package, if the
+	// package has any functions in it. The go command will pass in a value
+	// here if we've been asked to run "go test -cover" on a package that
+	// doesn't have any *_test.go files.
+	EmitMetaFile string
 }
 
 // registerCoverage modifies coverSrcFilename, the output file from go tool cover.
-// It adds a call to coverdata.RegisterCoverage, which ensures the coverage
-// data from each file is reported. The name by which the file is registered
-// need not match its original name (it may use the importpath).
-func registerCoverage(coverSrcFilename, varName, srcName string) error {
+// It adds a call to coverdata.RegisterSrcPathMapping, which ensures that rules_go
+// can produce lcov files with exec root relative file paths.
+func registerCoverage(coverSrcFilename, importPathFile, srcName string) error {
 	coverSrc, err := os.ReadFile(coverSrcFilename)
 	if err != nil {
 		return fmt.Errorf("instrumentForCoverage: reading instrumented source: %w", err)
@@ -97,13 +186,10 @@ func registerCoverage(coverSrcFilename, varName, srcName string) error {
 	var buf = bytes.NewBuffer(editor.Bytes())
 	fmt.Fprintf(buf, `
 func init() {
-	%s.RegisterFile(%q,
-		%[3]s.Count[:],
-		%[3]s.Pos[:],
-		%[3]s.NumStmt[:])
+	%s.RegisterSrcPathMapping(%q, %q)
 }
-`, coverdataName, srcName, varName)
-	if err := ioutil.WriteFile(coverSrcFilename, buf.Bytes(), 0666); err != nil {
+`, coverdataName, importPathFile, srcName)
+	if err := os.WriteFile(coverSrcFilename, buf.Bytes(), writeFileMode); err != nil {
 		return fmt.Errorf("registerCoverage: %v", err)
 	}
 	return nil

go/tools/builders/cover_test.go

@@ -21,10 +21,7 @@ var tests = []test{
 		out: `package main; import "github.com/bazelbuild/rules_go/go/tools/coverdata"
 
 func init() {
-	coverdata.RegisterFile("srcName",
-		varName.Count[:],
-		varName.Pos[:],
-		varName.NumStmt[:])
+	coverdata.RegisterSrcPathMapping("some.importh/path/file.go", "src/path/file.go")
 }
 `,
 	},
@@ -43,10 +40,7 @@ import (
 )
 
 func init() {
-	coverdata.RegisterFile("srcName",
-		varName.Count[:],
-		varName.Pos[:],
-		varName.NumStmt[:])
+	coverdata.RegisterSrcPathMapping("some.importh/path/file.go", "src/path/file.go")
 }
 `,
 	},
@@ -61,10 +55,7 @@ import "github.com/bazelbuild/rules_go/go/tools/coverdata"
 import "github.com/bazelbuild/rules_go/go/tools/coverdata"
 
 func init() {
-	coverdata.RegisterFile("srcName",
-		varName.Count[:],
-		varName.Pos[:],
-		varName.NumStmt[:])
+	coverdata.RegisterSrcPathMapping("some.importh/path/file.go", "src/path/file.go")
 }
 `,
 	},
@@ -79,10 +70,7 @@ import _ "github.com/bazelbuild/rules_go/go/tools/coverdata"
 import coverdata "github.com/bazelbuild/rules_go/go/tools/coverdata"
 
 func init() {
-	coverdata.RegisterFile("srcName",
-		varName.Count[:],
-		varName.Pos[:],
-		varName.NumStmt[:])
+	coverdata.RegisterSrcPathMapping("some.importh/path/file.go", "src/path/file.go")
 }
 `,
 	},
@@ -97,10 +85,7 @@ import cover0 "github.com/bazelbuild/rules_go/go/tools/coverdata"
 import cover0 "github.com/bazelbuild/rules_go/go/tools/coverdata"
 
 func init() {
-	cover0.RegisterFile("srcName",
-		varName.Count[:],
-		varName.Pos[:],
-		varName.NumStmt[:])
+	cover0.RegisterSrcPathMapping("some.importh/path/file.go", "src/path/file.go")
 }
 `,
 	},
@@ -113,7 +98,7 @@ func TestRegisterCoverage(t *testing.T) {
 			t.Errorf("writing input file: %v", err)
 			return
 		}
-		err := registerCoverage(filename, "varName", "srcName")
+		err := registerCoverage(filename, "some.importh/path/file.go", "src/path/file.go")
 		if err != nil {
 			t.Errorf("%q: %+v", test.name, err)
 			continue