User cargo config silently disables the docker-tests cfg, making a documented command a false green

[FAZuH]

Found while verifying PR #52. This is not a doc nit: one of the commands AGENTS.md documents reports zero tests run as a green pass.

The mechanism

.cargo/config.toml in this repo contains only:

[build]
rustflags = ["--cfg", "feature=\"docker-tests\""]

But ~/.cargo/config.toml sets a target-specific rustflags table:

[target.x86_64-unknown-linux-gnu]
rustflags = ["-C", "link-arg=-Wl,-rpath,/home/admin/.local/share/koharu-toolchain/lib"]

Cargo does not merge [build].rustflags with [target.<triple>].rustflags; the target table takes precedence. So on this host the --cfg feature="docker-tests" never reaches the compiler, and everything behind #[cfg(feature = "docker-tests")] is compiled out.

The symptom

AGENTS.md documents this as the way to run the suite:

cargo test -p lab-ops --test auto_discover   # auto-discover Docker integration tests

It reports:

running 0 tests
test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

A green result for a suite that did not run. I hit this myself earlier in the session and misread it as a passing run; it took a second look to catch.

AGENTS.md asserts that .cargo/config.toml "always enables docker-tests" and that --all-features is therefore "redundant but harmless". On this host the opposite is true: --all-features is required, and omitting it silently skips the whole suite.

What to build

A state where the documented commands either work or fail loudly. Options, in order of preference:

• (a) Add --all-features to the documented commands and correct the AGENTS.md claim. Smallest honest fix, and it makes the intent explicit at the call site rather than depending on a config file that is being overridden from outside the repo.
• (b) Make the user-level config stop clobbering the project one. The [env] entries in ~/.cargo/config.toml are load-bearing for this host (libclang, fontconfig pkg-config), but the [target.*] rustflags entry exists only to bake an rpath. Merging the rpath into [build].rustflags in the user config, or using RUSTFLAGS plus a second flag, would let the project config apply again. This is machine config, not repo config, so it does not travel with the repo and is easier to regress.
• (c) Add a guard so the suite cannot report green while running nothing, e.g. an assertion on the test count.

Note (b) alone does not help CI or anyone else whose config differs, so (a) is the part that travels.

Acceptance criteria

• Every command in AGENTS.md that targets the Docker suites actually runs them on a clean host
• Running a Docker target without the feature does not report ok. 0 passed as if it passed
• AGENTS.md no longer claims .cargo/config.toml always enables docker-tests, and no longer calls --all-features redundant
• The same false claim is not repeated in docs/dev/testing.md

Blocked by

None (can start immediately).

Related: PR #52 touches this harness. Its --test-threads=1 claim in AGENTS.md is also false and is reported separately.

[FAZuH]

The related finding: PR #52's harness work assumed --test-threads=1 and turned out not to have it. A per-test container sweep was reverted for exactly that reason, since it would have deleted containers belonging to tests running concurrently. See the flakiness issue for the full picture.

[FAZuH]

Fixed in c981148, pushed to main.

The mechanism in this issue was wrong, and so was the one I first wrote into AGENTS.md. Both claimed that a user-level [target.<triple>] rustflags table replaces [build] rustflags wholesale. Cargo merges them. Asking for the real rustc invocation shows both flags in the same command:

--cfg feature="docker-tests"                                  <- [build]
link-arg=-Wl,-rpath,/nix/store/...-openssl-3.6.4/lib          <- [target]

The real override is the RUSTFLAGS environment variable, which supersedes both tables. With it set the cfg is dropped and the suite compiles to nothing:

RUSTFLAGS="-C debuginfo=0" cargo test -p lab-ops --test auto_discover
running 0 tests
test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

--all-features is still the right fix, for a better reason than the issue gave: it enables the feature through the feature system rather than through rustflags, so it survives any rustflags override.

RUSTFLAGS="-C debuginfo=0" cargo test -p lab-ops --all-features --test auto_discover
47 tests listed

Changed

• AGENTS.md and docs/dev/testing.md: the two Docker-target commands now carry --all-features
• Both files: the "redundant but harmless" claim replaced with the mechanism above, and the 0-test symptom documented so the next person recognises it

Scope check, as asked

dev.sh test already passes --all-features (cargo test --workspace --all-targets --all-features --no-fail-fast), as does CI (_pr-checks.yml:55, and _cache-warm.yml:29 for check). Neither needed changing — the false green was confined to hand-written commands in the two docs.

Verification

• RUSTFLAGS set, no --all-features: 0 tests, reported ok
• RUSTFLAGS set, with --all-features: 47 tests listed
• Documented natmap_docker command: 34 passed
• Documented auto_discover command: 47 passed
• ./dev.sh test, exit 0: 442 passed, 0 failed across 10 targets

Caveat on reproducing this

The 0-test symptom did not reproduce on demand from a clean state during this ticket; I had to set RUSTFLAGS explicitly to trigger it. My earlier sighting was on this same node, but I could not reproduce it without an explicit override, so I do not have the original trigger. If you remember what was set that day, it would close the loop.

[FAZuH]

Landed as 036674f on main (direct push, docs-only: AGENTS.md, docs/dev/testing.md).

The mechanism as filed here is correct and is now documented with the precedence chain rather than a description of the symptom:

RUSTFLAGS env  >  [target.<triple>]  >  [build]

Cargo uses exactly one rustflags source, the highest-precedence one. The repo's [build] rustflags is the lowest, so the cfg is dropped by either of two independent triggers — a user-level ~/.cargo/config.toml defining a [target.<triple>] table, or any RUSTFLAGS that does not itself carry the cfg. The second was not in the original report; on the node ~/.bashrc exports a RUSTFLAGS that re-declares the cfg as a local workaround, so that box is masked against one trigger and not the other.

The fix is --all-features on any command targeting the Docker suites. It is required rather than merely preferred because it enables the feature through the feature system, not through rustflags, so it survives every rustflags override. dev.sh test, _pr-checks.yml and _cache-warm.yml already passed it; the false green was confined to hand-written commands in the two docs, which now carry it.

Suite after the change: 442 passed, 0 failed.

One trap worth recording, because it cost a verification round here: a cached test binary built while the cfg was in effect still lists all 47 tests when the same command is re-run after the cfg is gone. Reproducing this needs the rebuild forced, or the stale artifact reports a green suite for code that no longer compiles the tests at all.

Closes #53.