docs(agents): bazel test is authoritative; agents never run go test

Agents run tests only with `bazel test`, also while iterating on one
behavior: AGENTS.md shows the focused form
(`bazel test //cmd/bd:bd_test --config=ci --test_filter='^TestName$'`), the
target naming, that one --test_filter covers every target, that a cached
result for unchanged inputs is the same evidence, and that a new test file
needs `make bazel-sync` before Bazel runs it. `go test` (`./scripts/test.sh`,
`make test-go`) stays a convenience for humans working offline. TESTING.md's
focused red/green row and its plain-go-test section say the same.

Why: on the maintainer-city factory host, seats' own uncached `go test`
reruns of the same packages are the largest tool cost in adopt-pr, while
`bazel test` there executes on rbe-west and returns an unchanged target's
cached result in seconds.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Eddie the Engineer 2026-10-19 04:37:11 +00:00
commit c4d5409895
2 changed files with 22 additions and 9 deletions

View file

@ -126,9 +126,21 @@ make install # build and install bd to ~/.local/bin (canonical)
certificate `--config=remote-exec`, agent hosts whose `~/.bazelrc` names the
executor neither. Make yours the default with a `build --config=...` line in
the gitignored `.bazelrc.local`, or pass `BAZEL_FLAGS=...` to make.
- `go test` (`./scripts/test.sh`, `make test-go`) is an inner-loop
convenience only. CI does not enforce it, and it skips nogo, gofmt and the
guards; finish with `make test`.
- Agents run tests only with `bazel test`, also while iterating on one
behavior: `bazel test //cmd/bd:bd_test --config=ci
--test_filter='^TestName$'` (a package's tests are
`//<dir>:<last dir element>_test`, the root package's `//:beads_test`; one
`--test_filter` covers every target named). Results are cached by input,
so re-running an unchanged target is free and the cached result is the same
evidence. `--config=ci` sets `BEADS_TEST_SKIP=dolt`, so Dolt-backed tests
skip and still pass; run them with `--test_env=BEADS_TEST_SKIP=
--test_env=BEADS_TEST_DOLT_SERVER=local
--test_env=BEADS_TEST_REQUIRE_DOLT_CONTAINER=1` or their lane in
engdocs/TESTING.md. Bazel runs only the test files `BUILD.bazel` lists:
run `make bazel-sync` after adding one. Finish with `make test`.
- Agents do not run `go test` (`./scripts/test.sh`, `make test-go`): CI does
not enforce it, it skips nogo, gofmt and the guards, and agent hosts may
refuse it. It stays a convenience for humans working offline.
- **Do NOT** use `go build -o bd ./cmd/bd`, `go install ./cmd/bd`, or raw
`go run ./cmd/bd ...`: they bypass the canonical build path, leave stale
binaries, and raw `go run` misses the `gms_pure_go` tag. Use `make install`,

View file

@ -96,7 +96,7 @@ a unit test: use the real boundary when the defect could live there.
| Need | Run | When |
|---|---|---|
| Docs-only validation | `git diff --check` and `make check-docs` | For prose-only changes; add any generated-doc or surface-specific link check the changed paths require. Do not run the full suite merely because a Markdown file changed. |
| Focused red/green loop | `bazel test //path/to/package:package_test --config=ci --test_filter='^TestExactName$'`, or the plain-Go `./scripts/test.sh -run '^TestExactName$' ./path/to/package/...` | While writing or fixing one behavior. The `go test` loop is fine here; the Bazel targets below are the gate. |
| Focused red/green loop | `bazel test //path/to/package:package_test --config=ci --test_filter='^TestExactName$'` | While writing or fixing one behavior. Agents use only this form; an unchanged target returns its cached result. Humans working offline may use the plain-Go `./scripts/test.sh -run '^TestExactName$' ./path/to/package/...`, which is not the gate. |
| Affected-package confidence | `bazel test //path/to/package/... --config=ci` | After the focused test passes; include directly affected neighbors when their contract changed. |
| Final gate | `make test` | Once after focused work on Go code is green: the whole test lane, mostly cache hits. |
| Another lane's risk | that lane's command from the table above | When the change touches what that lane covers (integration-tagged files, the Dolt server path, embedded Dolt, pure-Go builds). |
@ -121,11 +121,12 @@ the suite CI gates on.
## Plain `go test` (Inner Loop)
`./scripts/test.sh` is the plain-Go runner behind `make test-go`. It sources
`.buildflags`, creates an isolated test environment, applies `.test-skip`, and
defaults to a **25m per-package** Go-test timeout. The timeout is a hang
backstop, not a target runtime. Override it only when diagnosing a legitimate
slow path:
This section is for humans working offline; agents run `bazel test` (see
"Choose the Smallest Useful Test" above). `./scripts/test.sh` is the plain-Go
runner behind `make test-go`. It sources `.buildflags`, creates an isolated
test environment, applies `.test-skip`, and defaults to a **25m per-package**
Go-test timeout. The timeout is a hang backstop, not a target runtime.
Override it only when diagnosing a legitimate slow path:
```bash
TEST_TIMEOUT=30m ./scripts/test.sh ./cmd/bd/...