Document exceptions, parseServerOutput, and compile behavior in README #136

New Issue

2026-08-30T15:02:04+02:00

SirStone commented

2026-08-30 15:02:04 +02:00

Parent: #135

Question

Update common_libs/test_framework/README.md to close the documentation gaps LLM simulations surfaced:

Exceptions: Document that runBattle() can raise OSError (compilation failure), IOError (runner non-zero exit), TimeoutError (any timeout). Show a try/except example.
parseServerOutput: Document this exported proc from battle_result.nim. Show how to use it for fast offline parser tests without needing Java/server. Include a fixture example.
Compile behavior: Note that compileBots runs on every runBattle() call (no caching). If running multiple tests, each call recompiles. Mention this so users aren't surprised.
Compile timeout: Note the 30s per-bot hardcoded compile timeout (independent of runBattle's timeout param).
Zero-value BotResult trap: Add a note/example showing that searching r.results by name returns a zeroed struct if not found — recommend guarding with check found.name == "MyBot".
Env-var skip pattern: Show a pattern for gracefully skipping tests when TR_SERVER_JAR / TR_BATTLE_RUNNER are not set.

Parent: #135 ## Question Update `common_libs/test_framework/README.md` to close the documentation gaps LLM simulations surfaced: 1. **Exceptions**: Document that `runBattle()` can raise `OSError` (compilation failure), `IOError` (runner non-zero exit), `TimeoutError` (any timeout). Show a try/except example. 2. **`parseServerOutput`**: Document this exported proc from `battle_result.nim`. Show how to use it for fast offline parser tests without needing Java/server. Include a fixture example. 3. **Compile behavior**: Note that `compileBots` runs on every `runBattle()` call (no caching). If running multiple tests, each call recompiles. Mention this so users aren't surprised. 4. **Compile timeout**: Note the 30s per-bot hardcoded compile timeout (independent of `runBattle`'s `timeout` param). 5. **Zero-value BotResult trap**: Add a note/example showing that searching `r.results` by name returns a zeroed struct if not found — recommend guarding with `check found.name == "MyBot"`. 6. **Env-var skip pattern**: Show a pattern for gracefully skipping tests when `TR_SERVER_JAR` / `TR_BATTLE_RUNNER` are not set.

SirStone added the wayfinder:task label 2026-08-30 15:02:04 +02:00

SirStone referenced this issue

2026-08-30 15:02:26 +02:00

Add integration test to a second garage (QBot) #138

~~SirStone referenced this issue 2026-08-30 15:03:05 +02:00~~

Make test framework LLM-ready (docs + examples) #135

SirStone commented

2026-08-30 15:06:41 +02:00

Done — added exceptions table, parseServerOutput section, compile behavior note, zero-value trap warning, env-var skip pattern, shared adversaries note to README.

SirStone closed this issue

2026-08-30 15:06:52 +02:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: SirStone/SirRoboGarage#136