From 5edea4601f8bd0f1f550ffe0c69f834655d1daed Mon Sep 17 00:00:00 2001
From: Daan De Meyer <daan@amutable.com>
Date: Fri, 9 Oct 2026 15:24:01 +0200
Subject: [PATCH] go: Add go.test to run a project's Go tests

A Go project's tests have no rule in tine. A consumer runs go test in a
relaxed box, where go downloads the modules again and compiles the project a
second time. Add test_packages to go.package. The build action compiles the
tests of those packages with go test -c, using the go build cache that the
build of the binaries already filled. go.test runs the test binaries in the
package's box without network.

Signed-off-by: Daan De Meyer <daan@amutable.com>
---
 docs/design/architecture.md                   |   8 ++
 docs/user/go.md                               |  35 ++++++
 examples/image-go-project/BUCK                |  14 +++
 .../hello/cmd/hello-cli/main_test.go          |  17 +++
 examples/image-go-project/nodeps/main_test.go |  12 ++
 go/BUCK                                       |  13 +++
 go/build.py                                   | 107 ++++++++++++++---
 go/build_test.py                              | 108 ++++++++++++++++++
 go/defs.bzl                                   |   3 +-
 go/rules.bzl                                  |  64 ++++++++++-
 go/runner.py                                  |  63 ++++++++++
 go/runner_test.py                             |  84 ++++++++++++++
 12 files changed, 510 insertions(+), 18 deletions(-)
 create mode 100644 examples/image-go-project/hello/cmd/hello-cli/main_test.go
 create mode 100644 examples/image-go-project/nodeps/main_test.go
 create mode 100755 go/runner.py
 create mode 100644 go/runner_test.py

diff --git a/docs/design/architecture.md b/docs/design/architecture.md
index 692eda67..3e7976d8 100644
--- a/docs/design/architecture.md
+++ b/docs/design/architecture.md
@@ -1059,6 +1059,14 @@ sources are. For a mount buck keeps it too, so a dependency bump downloads only
 module versions accumulate but are inert, since go takes only what `go.sum` names out of the proxy view.
 Otherwise buck clears it before the fetch, and the cache content depends only on the fetch's inputs.
 
+A `go.package()` that sets `test_packages` also compiles the tests of those packages in `go_build`, with
+`go test -c`, one test binary per package. The test binaries use go's build cache of the same action, so the
+project's packages compile once for the binaries and the tests. A test that does not compile fails the
+build. The test compile runs without vet, because a vet finding would fail the build too. `go.test()` runs
+each test binary under `buck test` in the package's box, in the package's directory, with the sources
+read-only. A pattern in `test_packages` that matches a package outside `src` fails the build, because that
+package's directory does not exist when the tests run.
+
 ### Filesystem layer representation
 
 Buck directory artifacts cannot faithfully store overlay whiteout devices, opaque-directory xattrs, or a
diff --git a/docs/user/go.md b/docs/user/go.md
index 58b74056..3505288e 100644
--- a/docs/user/go.md
+++ b/docs/user/go.md
@@ -100,6 +100,41 @@ go.package(
 )
 ```
 
+## Running a project's tests
+
+Set `test_packages` on the `go.package()` to compile the project's tests in its build, and declare a
+`go.test()` that runs them:
+
+```Starlark
+go.package(
+    name = "hello",
+    box = ":go.box",
+    packages = {"hello-cli": "./cmd/hello-cli"},
+    test_packages = ["./..."],
+)
+
+go.test(
+    name = "hello-test",
+    package = ":hello",
+)
+```
+
+`buck test :hello-test` runs the tests in the package's box, without network.
+
+- `test_packages` lists Go package patterns relative to the module root, such as `["./..."]` or
+  `["./pkg/...", "./internal/store"]`. The build compiles one test binary for each matched package that has
+  `_test.go` files, with the same tags, cgo setting and `linker_flags` as the binaries. Building the
+  binaries also compiles the tests.
+- A test that does not compile fails the build of the `go.package()`, and with it the binaries. go's vet
+  checks do not run, so a vet finding fails neither the build nor the tests.
+- A pattern that matches a package outside `src`, such as a dependency's package, fails the build.
+- Each test binary runs in its package's directory, as with `go test`, so a test finds its `testdata/`.
+  The sources are read-only while the tests run, so a test that writes into its package directory fails.
+- `args` passes arguments to every test binary. A test binary takes the `-test.` form of the `go test`
+  flags, such as `["-test.short", "-test.skip=TestNetwork"]`. Each binary has a timeout of 10 minutes,
+  which `-test.timeout` overrides.
+- `labels` are passed to the test runner, so `buck test --exclude <label>` can leave the test out.
+
 ## What the builder box needs
 
 ```Starlark
diff --git a/examples/image-go-project/BUCK b/examples/image-go-project/BUCK
index 65eb14ea..07fc3a39 100644
--- a/examples/image-go-project/BUCK
+++ b/examples/image-go-project/BUCK
@@ -30,6 +30,13 @@ go.package(
     name = "hello",
     box = ":go.box",
     packages = {"hello-cli": "./cmd/hello-cli"},
+    test_packages = ["./..."],
+)
+
+go.test(
+    name = "hello-test",
+    labels = ["image"],
+    package = ":hello",
 )
 
 # A project with no dependencies at all, which therefore commits no go.sum and fetches nothing.
@@ -37,6 +44,13 @@ go.package(
 go.package(
     name = "nodeps",
     box = ":go.box",
+    test_packages = ["./..."],
+)
+
+go.test(
+    name = "nodeps-test",
+    labels = ["image"],
+    package = ":nodeps",
 )
 
 # The local checkout must override this fetch, so its revision is deliberately a placeholder.
diff --git a/examples/image-go-project/hello/cmd/hello-cli/main_test.go b/examples/image-go-project/hello/cmd/hello-cli/main_test.go
new file mode 100644
index 00000000..27387b3b
--- /dev/null
+++ b/examples/image-go-project/hello/cmd/hello-cli/main_test.go
@@ -0,0 +1,17 @@
+// SPDX-FileCopyrightText: Amutable GmbH <https://amutable.com/>
+// SPDX-License-Identifier: MPL-2.0
+
+package main
+
+import (
+	"strings"
+	"testing"
+
+	"rsc.io/quote"
+)
+
+func TestQuote(t *testing.T) {
+	if got := quote.Go(); !strings.Contains(got, "communicating") {
+		t.Fatalf("unexpected quote: %q", got)
+	}
+}
diff --git a/examples/image-go-project/nodeps/main_test.go b/examples/image-go-project/nodeps/main_test.go
new file mode 100644
index 00000000..2086c655
--- /dev/null
+++ b/examples/image-go-project/nodeps/main_test.go
@@ -0,0 +1,12 @@
+// SPDX-FileCopyrightText: Amutable GmbH <https://amutable.com/>
+// SPDX-License-Identifier: MPL-2.0
+
+package main
+
+import "testing"
+
+func TestMessage(t *testing.T) {
+	if message != "no dependencies here\n" {
+		t.Fatalf("unexpected message: %q", message)
+	}
+}
diff --git a/go/BUCK b/go/BUCK
index 61c0c965..5b78a158 100644
--- a/go/BUCK
+++ b/go/BUCK
@@ -34,6 +34,17 @@ tine_python_binary(
     ],
 )
 
+# Runs inside the box offline. It runs each test binary that the build compiled in the binary's package directory.
+tine_python_binary(
+    name = "runner",
+    main = "runner.py",
+    visibility = ["PUBLIC"],
+    deps = [
+        "//:specs",
+        "//rootfs:rootfs",
+    ],
+)
+
 box_python_test(
     name = "test",
     box = "//tools:dev.box",
@@ -42,6 +53,8 @@ box_python_test(
         "build_test.py",
         "fetch.py",
         "fetch_test.py",
+        "runner.py",
+        "runner_test.py",
         "workspace.py",
         "workspace_test.py",
     ],
diff --git a/go/build.py b/go/build.py
index 3a9159bf..3e1ae083 100755
--- a/go/build.py
+++ b/go/build.py
@@ -15,7 +15,7 @@
 import tempfile
 from contextlib import ExitStack
 from pathlib import Path
-from typing import TypedDict, cast
+from typing import Any, TypedDict, cast
 
 import specs
 import util
@@ -45,36 +45,89 @@ class Spec(TypedDict):
     src: str
     # The build tags gating which of the project's files compile.
     tags: list[str]
-
-
-def _package(selector: str, workspace: Path, env: dict[str, str]) -> str:
-    """Resolve a selector to exactly one main package before building an executable."""
-    if not selector or selector.startswith("-") or selector.endswith(".go"):
-        util.fail(f"go-build: invalid package selection {selector!r}")
+    # The Go package patterns whose tests to compile, or None to compile no tests.
+    test_packages: list[str] | None
+    # The output directory for the test binaries and their manifest, or None to compile no tests.
+    tests: str | None
+
+
+class Test(TypedDict):
+    # The test binary's file name in the tests directory.
+    binary: str
+    # The package's import path.
+    package: str
+    # The package's directory relative to src. go test runs a test binary in this directory.
+    dir: str
+
+
+def _list(patterns: list[str], fields: str, workspace: Path, env: dict[str, str]) -> list[dict[str, Any]]:
+    """Return the packages that `patterns` match, as go list reports them."""
+    for pattern in patterns:
+        if not pattern or pattern.startswith("-") or pattern.endswith(".go"):
+            util.fail(f"go-build: invalid package selection {pattern!r}")
     listed = subprocess.run(
-        ["go", "list", "-json=ImportPath,Name", selector],
+        ["go", "list", f"-json={fields}", *patterns],
         check=True,
         cwd=workspace,
         env=env,
         stdout=subprocess.PIPE,
         text=True,
     )
-    # go prints one object per package, back to back. A pattern such as the `./...` an undeclared
-    # `packages` stands for also matches the libraries beside the program, which are not candidates.
+    # go prints one object per package, back to back.
     decoder = json.JSONDecoder()
-    mains: list[str] = []
+    packages: list[dict[str, Any]] = []
     rest = listed.stdout.lstrip()
     while rest:
-        package, end = cast(tuple[dict[str, str], int], decoder.raw_decode(rest))
-        if package["Name"] == "main":
-            mains.append(package["ImportPath"])
+        package, end = cast(tuple[dict[str, Any], int], decoder.raw_decode(rest))
+        packages.append(package)
         rest = rest[end:].lstrip()
+    return packages
+
+
+def _package(selector: str, workspace: Path, env: dict[str, str]) -> str:
+    """Resolve a selector to exactly one main package before building an executable."""
+    # A pattern such as the `./...` an undeclared `packages` stands for also matches the libraries
+    # beside the program, which are not candidates.
+    mains = [
+        package["ImportPath"]
+        for package in _list([selector], "ImportPath,Name", workspace, env)
+        if package["Name"] == "main"
+    ]
     if len(mains) != 1:
         util.fail(
             f"go-build: package selection {selector!r} must resolve to exactly one main package, "
             f"found {mains}"
         )
-    return mains[0]
+    return cast(str, mains[0])
+
+
+def _test_packages(
+    patterns: list[str], workspace: Path, src: Path, env: dict[str, str]
+) -> list[tuple[str, str]]:
+    """Return the import path and the directory relative to `src` of each matched package that has tests."""
+    found: list[tuple[str, str]] = []
+    fields = "ImportPath,Dir,TestGoFiles,XTestGoFiles"
+    for package in _list(patterns, fields, workspace, env):
+        if not package.get("TestGoFiles") and not package.get("XTestGoFiles"):
+            continue
+        # A pattern can name a package of a dependency, which go extracts into the module cache in
+        # the scratch space. go.test runs each test binary in its package directory, and that
+        # directory does not exist when the tests run.
+        directory = Path(package["Dir"]).resolve()
+        if not directory.is_relative_to(src.resolve()):
+            util.fail(f"go-build: test package {package['ImportPath']} is not in src")
+        found.append((package["ImportPath"], str(directory.relative_to(src.resolve()))))
+    return found
+
+
+def _test_command(binary: Path, package: str, linker_flags: list[str]) -> list[str]:
+    """Compile the tests of one package into a test binary."""
+    # go test runs a subset of go vet before it compiles the tests, also with -c. A vet finding would
+    # fail the build of the project's binaries along with the tests.
+    cmd = ["go", "test", "-c", "-vet=off", "-o", str(binary)]
+    if linker_flags:
+        cmd.append("-ldflags=" + " ".join(linker_flags))
+    return cmd + [package]
 
 
 def _build_command(binary: Path, package: str, linker_flags: list[str]) -> list[str]:
@@ -140,10 +193,14 @@ def build_go(spec: Spec) -> None:
         # enough to need a C compiler in the box and to link the binary dynamically.
         env["CGO_ENABLED"] = "1" if spec["cgo"] else "0"
 
+    tests = scratch / "tests"
+
     with ExitStack() as stack:
         outputs = {Path(spec["bin"]): out}
         if spec["gocache"] is not None:
             outputs[Path(spec["gocache"])] = gocache
+        if spec["tests"] is not None:
+            outputs[Path(spec["tests"])] = tests
         stack.enter_context(rootfs.readonly_project(Path.cwd(), outputs))
         util.remove_previous_binaries(out)
 
@@ -157,6 +214,26 @@ def build_go(spec: Spec) -> None:
                 env=env,
             )
 
+        if spec["tests"] is None or spec["test_packages"] is None:
+            return
+        util.remove_previous_binaries(tests)
+        # The tests compile in this action because it already has go's build cache filled with the
+        # project's packages. A separate action would compile the packages again.
+        manifest: list[Test] = []
+        for index, (package, directory) in enumerate(
+            _test_packages(spec["test_packages"], workspace, Path(spec["src"]), env)
+        ):
+            # Two packages can have the same name, so the binaries are numbered.
+            binary = f"{index}.test"
+            subprocess.run(
+                _test_command(tests / binary, package, spec["linker_flags"]),
+                check=True,
+                cwd=workspace,
+                env=env,
+            )
+            manifest.append(Test(binary=binary, package=package, dir=directory))
+        (tests / "manifest.json").write_text(json.dumps(manifest, indent=2) + "\n", encoding="utf-8")
+
 
 def main(argv: list[str] | None = None) -> None:
     build_go(specs.parse(Spec, "go-build", argv))
diff --git a/go/build_test.py b/go/build_test.py
index ec96df35..b446a055 100644
--- a/go/build_test.py
+++ b/go/build_test.py
@@ -9,6 +9,7 @@
 """
 
 import errno
+import json
 import subprocess
 import tempfile
 import unittest
@@ -48,6 +49,8 @@ def test_sources_are_read_only_and_kept_outputs_survive_failure(self) -> None:
                     root="",
                     src="checkout",
                     tags=[],
+                    test_packages=None,
+                    tests=None,
                 )
                 stale = self.project / spec["bin"] / "undeclared"
                 stale.parent.mkdir()
@@ -104,6 +107,111 @@ def run(
                 (self.project / "outside").write_text("writable again", encoding="utf-8")
 
 
+class TestCompileTests(unittest.TestCase):
+    @override
+    def setUp(self) -> None:
+        root = Path(self.enterContext(tempfile.TemporaryDirectory(prefix="go-build-test.", dir="/var/tmp")))
+        self.project = root / "project"
+        (self.project / "checkout").mkdir(parents=True)
+        (root / "scratch").mkdir()
+        self.enterContext(chdir(self.project))
+        self.enterContext(patch.object(tempfile, "tempdir", str(root / "scratch")))
+
+    def test_writes_a_binary_and_a_manifest_entry_per_package(self) -> None:
+        spec = build.Spec(
+            bin="bin",
+            cgo=None,
+            cgo_cflags=[],
+            gocache=None,
+            linker_flags=["-s"],
+            module_cache_dir=None,
+            packages={},
+            root="",
+            src="checkout",
+            tags=[],
+            test_packages=["./..."],
+            tests="tests",
+        )
+        stale = self.project / "tests" / "7.test"
+        stale.parent.mkdir()
+        stale.touch()
+        commands: list[list[str]] = []
+
+        def run(command: list[str], *, check: bool, cwd: Path, env: dict[str, str]) -> None:
+            commands.append(command)
+            Path(command[command.index("-o") + 1]).write_text("compiled", encoding="utf-8")
+
+        packages = [("example.com/a", "a"), ("example.com/b/a", "b/a")]
+        with (
+            patch.object(build, "_test_packages", return_value=packages) as listed,
+            patch.object(build.subprocess, "run", side_effect=run),
+        ):
+            build.build_go(spec)
+
+        self.assertEqual(listed.call_args.args[0], ["./..."])
+        self.assertEqual(
+            [command[-1] for command in commands],
+            ["example.com/a", "example.com/b/a"],
+        )
+        tests = self.project / "tests"
+        self.assertFalse(stale.exists())
+        self.assertEqual((tests / "0.test").read_text(encoding="utf-8"), "compiled")
+        self.assertEqual(
+            json.loads((tests / "manifest.json").read_text(encoding="utf-8")),
+            [
+                {"binary": "0.test", "package": "example.com/a", "dir": "a"},
+                {"binary": "1.test", "package": "example.com/b/a", "dir": "b/a"},
+            ],
+        )
+
+    def test_compile_command(self) -> None:
+        self.assertEqual(
+            build._test_command(Path("/var/tmp/tests/0.test"), "example.com/a", ["-s", "-w"]),
+            [
+                "go",
+                "test",
+                "-c",
+                "-vet=off",
+                "-o",
+                "/var/tmp/tests/0.test",
+                "-ldflags=-s -w",
+                "example.com/a",
+            ],
+        )
+
+    def test_lists_packages_with_tests_relative_to_src(self) -> None:
+        src = self.project / "checkout"
+        listing = "".join(
+            json.dumps(package)
+            for package in [
+                {"ImportPath": "example.com/a", "Dir": str(src / "server/a"), "TestGoFiles": ["a_test.go"]},
+                {"ImportPath": "example.com/b", "Dir": str(src / "server/b")},
+                {"ImportPath": "example.com/c", "Dir": str(src / "api"), "XTestGoFiles": ["c_test.go"]},
+            ]
+        )
+        with patch("build.subprocess.run") as run:
+            run.return_value.stdout = listing
+            self.assertEqual(
+                build._test_packages(["./..."], src / "server", src, {}),
+                [("example.com/a", "server/a"), ("example.com/c", "api")],
+            )
+
+    def test_rejects_test_packages_outside_src(self) -> None:
+        listing = json.dumps(
+            {
+                "ImportPath": "rsc.io/quote",
+                "Dir": "/var/tmp/modules/rsc.io/quote",
+                "TestGoFiles": ["quote_test.go"],
+            }
+        )
+        with (
+            patch("build.subprocess.run") as run,
+            self.assertRaisesRegex(SystemExit, "rsc.io/quote is not in src"),
+        ):
+            run.return_value.stdout = listing
+            build._test_packages(["rsc.io/quote"], Path("checkout"), Path("checkout"), {})
+
+
 class TestBuildCommand(unittest.TestCase):
     def test_output_name_and_linker_flags(self) -> None:
         self.assertEqual(
diff --git a/go/defs.bzl b/go/defs.bzl
index b27feece..ad4d1d48 100644
--- a/go/defs.bzl
+++ b/go/defs.bzl
@@ -7,8 +7,9 @@ Load the `go` namespace from here; the modules behind it are implementation stru
 rearranged.
 """
 
-load("//go:rules.bzl", "go_package")
+load("//go:rules.bzl", "go_package", "go_test")
 
 go = struct(
     package = go_package,
+    test = go_test,
 )
diff --git a/go/rules.bzl b/go/rules.bzl
index f0526348..009a4954 100644
--- a/go/rules.bzl
+++ b/go/rules.bzl
@@ -1,7 +1,7 @@
 # SPDX-FileCopyrightText: Amutable GmbH <https://amutable.com/>
 # SPDX-License-Identifier: MPL-2.0
 
-"""Build a Go project from its own source tree: one online, verified module fetch, then an offline build."""
+"""Build and test a Go project from its own source tree: one online, verified module fetch, then an offline build."""
 
 load("//:specs.bzl", "spec_args")
 load("//box:runtime.bzl", "BoxInfo", "box_run")
@@ -9,6 +9,17 @@ load("//project:defs.bzl", "project")
 
 _PRIVATE = "__tine"
 
+GoPackageInfo = provider(
+    doc = "The test binaries of a go_package, for a go_test to run.",
+    fields = {
+        "box": provider_field(BoxInfo),
+        "src": provider_field(Artifact),
+        # The test binaries and the manifest that build.py writes beside them. It is None when the
+        # go_package sets no `test_packages`.
+        "tests": provider_field(Artifact | None),
+    },
+)
+
 def _go_build_impl(
     actions: AnalysisActions,
     bin: OutputArtifact,
@@ -22,6 +33,8 @@ def _go_build_impl(
     packages: dict[str, str],
     src: Artifact,
     tags: list[str],
+    test_packages: list[str] | None,
+    tests: OutputArtifact | None,
     workspace: ArtifactValue,
 ) -> list[Provider]:
     """Declare what the project's go.mod asks for, once it has been found and can be read."""
@@ -71,6 +84,8 @@ def _go_build_impl(
                     "root": module["root"],
                     "src": src,
                     "tags": tags,
+                    "test_packages": test_packages,
+                    "tests": tests,
                 },
             ),
         ),
@@ -94,6 +109,8 @@ _go_build = dynamic_actions(
         "packages": dynattrs.value(dict[str, str]),
         "src": dynattrs.value(Artifact),
         "tags": dynattrs.value(list[str]),
+        "test_packages": dynattrs.value(list[str] | None),
+        "tests": dynattrs.option(dynattrs.output()),
         "workspace": dynattrs.artifact_value(),
     },
 )
@@ -110,6 +127,7 @@ def _go_package_impl(ctx: AnalysisContext) -> list[Provider]:
     # clears them before rerunning it unless told not to. A declared output is also uploaded to the
     # cache, only do that for incremental builds; otherwise build in scratch space.
     gocache = project.kept_dir(ctx.actions, _PRIVATE + "/gocache") if ctx.attrs.incremental else None
+    tests = project.kept_dir(ctx.actions, _PRIVATE + "/tests") if ctx.attrs.test_packages != None else None
 
     # The go_workspace action checks that module_root contains a go.mod. go_workspace runs only after
     # src is built, and building src can mean a git fetch. Checking the form of the path at analysis
@@ -150,10 +168,12 @@ def _go_package_impl(ctx: AnalysisContext) -> list[Provider]:
             packages = packages,
             src = src,
             tags = ctx.attrs.tags,
+            test_packages = ctx.attrs.test_packages,
+            tests = tests.as_output() if tests != None else None,
             workspace = workspace,
         ),
     )
-    return project.binaries_providers(outputs)
+    return project.binaries_providers(outputs) + [GoPackageInfo(box = ctx.attrs.box[BoxInfo], src = src, tests = tests)]
 
 _go_package = rule(
     impl = _go_package_impl,
@@ -167,6 +187,7 @@ _go_package = rule(
         "packages": attrs.dict(attrs.string(), attrs.string(), default = {}, doc = "output name to main package; unset builds the module's only one"),
         "src": attrs.source(allow_directory = True, doc = "the project's source directory, go.mod and go.sum included"),
         "tags": attrs.list(attrs.string(), default = [], doc = "build tags selecting the project's optional files"),
+        "test_packages": attrs.option(attrs.list(attrs.string()), default = None, doc = "Go package patterns whose tests the build compiles for a go_test"),
         "_build": attrs.exec_dep(providers = [RunInfo], default = "tine//go:build"),
         "_fetch": attrs.exec_dep(providers = [RunInfo], default = "tine//go:fetch"),
         "_workspace": attrs.exec_dep(providers = [RunInfo], default = "tine//go:workspace"),
@@ -191,3 +212,42 @@ def go_package(
         src = src if src != None else name,
         **kwargs,
     )
+
+def _go_test_impl(ctx: AnalysisContext) -> list[Provider]:
+    package = ctx.attrs.package[GoPackageInfo]
+    if package.tests == None:
+        fail("go_test {}: {} sets no `test_packages`, so its build compiles no tests".format(ctx.label.name, ctx.attrs.package.label))
+    command = cmd_args(
+        box_run(box = package.box, exe = ctx.attrs._runner),
+        spec_args(
+            ctx.actions,
+            "go-test.spec.json",
+            {
+                "args": ctx.attrs.args,
+                "src": package.src,
+                "tests": package.tests,
+            },
+        ),
+    )
+    return [
+        DefaultInfo(),
+        RunInfo(args = command),
+        ExternalRunnerTestInfo(
+            type = "custom",
+            command = [command],
+            labels = ctx.attrs.labels,
+            # The sandbox chroots, unshares and mounts, so it cannot run on a remote executor.
+            default_executor = CommandExecutorConfig(local_enabled = True, remote_enabled = False),
+        ),
+    ]
+
+go_test = rule(
+    doc = """Run the tests that a go_package's build compiled, by `buck test` inside the package's box.""",
+    impl = _go_test_impl,
+    attrs = {
+        "args": attrs.list(attrs.string(), default = [], doc = "arguments for each test binary, such as -test.short"),
+        "labels": attrs.list(attrs.string(), default = [], doc = "passed to the test runner, for `buck test` filtering"),
+        "package": attrs.dep(providers = [GoPackageInfo], doc = "the go_package whose tests to run"),
+        "_runner": attrs.exec_dep(providers = [RunInfo], default = "tine//go:runner"),
+    },
+)
diff --git a/go/runner.py b/go/runner.py
new file mode 100755
index 00000000..304bdc8b
--- /dev/null
+++ b/go/runner.py
@@ -0,0 +1,63 @@
+#!/usr/bin/python3
+
+# SPDX-FileCopyrightText: Amutable GmbH <https://amutable.com/>
+# SPDX-License-Identifier: MPL-2.0
+
+"""Run the test binaries that a go_package's build compiled, inside a box."""
+
+import json
+import subprocess
+import time
+from contextlib import ExitStack
+from pathlib import Path
+from typing import TypedDict, cast
+
+import specs
+
+import rootfs
+
+# go test passes these flags to every test binary it runs. A flag in `args` comes later on the command
+# line, and the test binary takes the last value of a flag.
+_DEFAULT_ARGS = ["-test.paniconexit0", "-test.timeout=10m0s"]
+
+
+class Spec(TypedDict):
+    # Arguments for each test binary, such as -test.short.
+    args: list[str]
+    # The project's source directory artifact.
+    src: str
+    # The go_package's test binaries and their manifest.
+    tests: str
+
+
+def run_tests(spec: Spec) -> int:
+    """Run each test binary in its package directory, and return 1 if any of them fails."""
+    # A test binary runs in its package directory, so the path of `tests` has to be absolute.
+    tests = Path(spec["tests"]).absolute()
+    # build.py writes the manifest: one entry per test binary, with the binary's file name, the package's
+    # import path and the package's directory relative to src.
+    manifest = cast(list[dict[str, str]], json.loads((tests / "manifest.json").read_text(encoding="utf-8")))
+    failed = False
+    with ExitStack() as stack:
+        # The sources are a build output, or the checkout itself in dev mode. A test that writes to
+        # its package directory would change either one.
+        stack.enter_context(rootfs.readonly_project(Path.cwd(), {}))
+        for test in manifest:
+            start = time.monotonic()
+            status = subprocess.run(
+                [tests / test["binary"], *_DEFAULT_ARGS, *spec["args"]],
+                check=False,
+                cwd=Path(spec["src"]) / test["dir"],
+            ).returncode
+            elapsed = time.monotonic() - start
+            print(f"{'ok  ' if status == 0 else 'FAIL'}\t{test['package']}\t{elapsed:.3f}s", flush=True)
+            failed = failed or status != 0
+    return 1 if failed else 0
+
+
+def main(argv: list[str] | None = None) -> None:
+    raise SystemExit(run_tests(specs.parse(Spec, "go-test", argv)))
+
+
+if __name__ == "__main__":
+    main()
diff --git a/go/runner_test.py b/go/runner_test.py
new file mode 100644
index 00000000..8d1db167
--- /dev/null
+++ b/go/runner_test.py
@@ -0,0 +1,84 @@
+# SPDX-FileCopyrightText: Amutable GmbH <https://amutable.com/>
+# SPDX-License-Identifier: MPL-2.0
+
+"""Tests for the runner of Go test binaries.
+
+buck test tine//go:test
+"""
+
+import errno
+import io
+import json
+import subprocess
+import tempfile
+import unittest
+from contextlib import chdir, redirect_stdout
+from pathlib import Path
+from typing import override
+from unittest.mock import patch
+
+import runner
+
+
+class TestRunTests(unittest.TestCase):
+    @override
+    def setUp(self) -> None:
+        self.project = Path(
+            self.enterContext(tempfile.TemporaryDirectory(prefix="go-runner-test.", dir="/var/tmp"))
+        )
+        for package in ("server", "server/api"):
+            (self.project / "checkout" / package).mkdir(parents=True, exist_ok=True)
+            (self.project / "checkout" / package / "main_test.go").write_text("original", encoding="utf-8")
+        (self.project / "tests").mkdir()
+        (self.project / "tests" / "manifest.json").write_text(
+            json.dumps(
+                [
+                    {"binary": "0.test", "package": "example.com/server", "dir": "server"},
+                    {"binary": "1.test", "package": "example.com/server/api", "dir": "server/api"},
+                ]
+            ),
+            encoding="utf-8",
+        )
+        self.enterContext(chdir(self.project))
+
+    def _run(self, statuses: list[int]) -> tuple[int, list[tuple[list[str], Path]]]:
+        calls: list[tuple[list[str], Path]] = []
+
+        def run(command: list[str | Path], *, check: bool, cwd: Path) -> subprocess.CompletedProcess[str]:
+            self.assertFalse(check)
+            # The tests must find the project read-only, including the sources.
+            with self.assertRaises(OSError) as caught:
+                (cwd / "main_test.go").write_text("changed", encoding="utf-8")
+            self.assertEqual(caught.exception.errno, errno.EROFS)
+            calls.append(([str(part) for part in command], cwd))
+            return subprocess.CompletedProcess(command, statuses[len(calls) - 1])
+
+        spec = runner.Spec(args=["-test.short", "-test.timeout=1h"], src="checkout", tests="tests")
+        with patch.object(runner.subprocess, "run", side_effect=run), redirect_stdout(io.StringIO()):
+            status = runner.run_tests(spec)
+        return status, calls
+
+    def test_runs_each_binary_in_its_package_directory(self) -> None:
+        status, calls = self._run([0, 0])
+        self.assertEqual(status, 0)
+        tests = self.project.resolve() / "tests"
+        self.assertEqual(
+            [(command, cwd.resolve()) for command, cwd in calls],
+            [
+                (
+                    [str(tests / binary), *runner._DEFAULT_ARGS, "-test.short", "-test.timeout=1h"],
+                    self.project.resolve() / "checkout" / directory,
+                )
+                for binary, directory in (("0.test", "server"), ("1.test", "server/api"))
+            ],
+        )
+        self.assertEqual((self.project / "checkout/server/main_test.go").read_text(), "original")
+
+    def test_runs_every_binary_and_fails_when_one_fails(self) -> None:
+        status, calls = self._run([1, 0])
+        self.assertEqual(status, 1)
+        self.assertEqual(len(calls), 2)
+
+
+if __name__ == "__main__":
+    unittest.main()