diff --git a/AGENTS.md b/AGENTS.md index 1a450309e..66505a754 100644 --- a/AGENTS.md +++ b/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 + `//:_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`, diff --git a/engdocs/TESTING.md b/engdocs/TESTING.md index d92a75a2e..2620ccd6c 100644 --- a/engdocs/TESTING.md +++ b/engdocs/TESTING.md @@ -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/...