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:
parent
36f81bab1c
commit
c4d5409895
2 changed files with 22 additions and 9 deletions
18
AGENTS.md
18
AGENTS.md
|
|
@ -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`,
|
||||
|
|
|
|||
|
|
@ -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/...
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue