feat: add shared integration test framework for garages (#126)
Implements: - BattleResult type and JSON-lines parser (#127) - TR server lifecycle manager (#128) - Bot compiler using nim c (#129) - runBattle() orchestrator (#130) - Example test in OscillatorBot_garage (#131) - Framework usage guide (#132) - TestBattleRunner.java for external server (#133) - BattleRunner process lifecycle (#134) Fix: runner_process.nim was redefining TimeoutError locally; now uses std/net.TimeoutError consistently with server_manager.nim.
This commit is contained in:
@@ -0,0 +1,205 @@
|
||||
# test_framework
|
||||
|
||||
Integration test framework for Tank Royale bots. Spins up a TR server JAR on a random port, compiles your Nim bots, runs a battle via a Java `TestBattleRunner` subprocess, and returns structured results you can assert on. Local development tool only — no CI support.
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- **Java JRE** (11+) — `java` must be on `PATH`
|
||||
- **Tank Royale server JAR** — `robocode-tankroyale-server-*-all.jar`
|
||||
- **Tank Royale runner JAR** — `robocode-tankroyale-runner.jar`
|
||||
|
||||
### Environment variables
|
||||
|
||||
| Variable | Purpose | Default |
|
||||
|---|---|---|
|
||||
| `TR_SERVER_JAR` | Path to the TR server JAR | hardcoded dev path in `server_manager.nim` |
|
||||
| `TR_BATTLE_RUNNER` | Path to the TR runner JAR | hardcoded dev path in `runner_process.nim` |
|
||||
| `TR_BATTLE_RUNNER_DIR` | Directory containing compiled `TestBattleRunner.class` | `tools/battle_runner/` |
|
||||
|
||||
Set at minimum `TR_SERVER_JAR` and `TR_BATTLE_RUNNER` to point at your local JAR builds.
|
||||
|
||||
### One-time Java compilation
|
||||
|
||||
```sh
|
||||
cd tools/battle_runner
|
||||
TANK_ROYALE_JAR=/path/to/robocode-tankroyale-runner.jar ./run_test_battle.sh --help
|
||||
```
|
||||
|
||||
`run_test_battle.sh` auto-compiles `TestBattleRunner.java` when `.class` is missing or stale. After this, `TR_BATTLE_RUNNER_DIR` defaults to `tools/battle_runner/` and the class file is found automatically.
|
||||
|
||||
---
|
||||
|
||||
## Setup for your garage
|
||||
|
||||
**`tests/config.nims`** — add the common_libs path so the import resolves:
|
||||
|
||||
```nim
|
||||
--path:"../../common_libs"
|
||||
```
|
||||
|
||||
Adjust the relative depth to match your garage's position in the repo.
|
||||
|
||||
**`YourBot.nimble`** — add a test task:
|
||||
|
||||
```nim
|
||||
task test, "Compile and run integration tests":
|
||||
exec "nim c -r --path:../common_libs tests/test_basic_battle.nim"
|
||||
```
|
||||
|
||||
Run with:
|
||||
|
||||
```sh
|
||||
nimble test
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Writing tests
|
||||
|
||||
```nim
|
||||
import std/[os, unittest]
|
||||
import test_framework/test_framework
|
||||
|
||||
const
|
||||
myBotDir = currentSourcePath().parentDir.parentDir # garage root
|
||||
sittingDuck = currentSourcePath().parentDir / "bots" / "SittingDuck"
|
||||
|
||||
suite "MyBot basic battle":
|
||||
test "beats SittingDuck in 3 rounds":
|
||||
let r = runBattle(@[myBotDir, sittingDuck], rounds = 3)
|
||||
|
||||
check r.rounds.len == 3
|
||||
check r.results.len == 2
|
||||
|
||||
let me = block:
|
||||
var found: BotResult
|
||||
for b in r.results:
|
||||
if b.name == "MyBot": found = b
|
||||
found
|
||||
|
||||
check me.totalScore > 0
|
||||
check "MyBot" in r.winners
|
||||
```
|
||||
|
||||
`runBattle` blocks until the battle finishes (or `timeout` ms elapses). The server process is started once per test binary run and killed on exit.
|
||||
|
||||
---
|
||||
|
||||
## API reference
|
||||
|
||||
### `runBattle`
|
||||
|
||||
```nim
|
||||
proc runBattle*(botDirs: seq[string], rounds: int = 10,
|
||||
timeout: int = 120000): BattleResult
|
||||
```
|
||||
|
||||
| Parameter | Description |
|
||||
|---|---|
|
||||
| `botDirs` | Absolute or relative paths to bot directories (one per participating bot) |
|
||||
| `rounds` | Number of rounds to play (default: 10) |
|
||||
| `timeout` | Milliseconds to wait for the battle runner to finish (default: 120000) |
|
||||
|
||||
Each bot directory must have `src/<BotName>.nim` and the compiler writes the binary to `out/<BotName>`.
|
||||
|
||||
### `BattleResult`
|
||||
|
||||
```nim
|
||||
BattleResult = object
|
||||
bots*: seq[string] # bot names in participation order
|
||||
rounds*: seq[RoundResult] # one entry per round
|
||||
results*: seq[BotResult] # final standings, sorted by rank
|
||||
winners*: seq[string] # names of bots with rank == 1
|
||||
```
|
||||
|
||||
### `BotResult`
|
||||
|
||||
```nim
|
||||
BotResult = object
|
||||
name*: string
|
||||
totalScore*: int
|
||||
rank*: int
|
||||
firstPlaces*: int
|
||||
survivalCount*: int
|
||||
```
|
||||
|
||||
### `RoundResult`
|
||||
|
||||
```nim
|
||||
RoundResult = object
|
||||
round*: int
|
||||
results*: seq[BotRoundResult]
|
||||
```
|
||||
|
||||
### `BotRoundResult`
|
||||
|
||||
```nim
|
||||
BotRoundResult = object
|
||||
name*: string
|
||||
score*: int
|
||||
rank*: int
|
||||
survived*: bool
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Writing adversary bots
|
||||
|
||||
Minimal bot — does nothing, useful as a baseline target:
|
||||
|
||||
**`tests/bots/SittingDuck/src/SittingDuck.nim`**
|
||||
```nim
|
||||
import std/os
|
||||
import tankroyale_botapi
|
||||
|
||||
const botJsonPath = currentSourcePath().parentDir / "SittingDuck.json"
|
||||
|
||||
type SittingDuck = ref object of Bot
|
||||
|
||||
method run*(bot: SittingDuck) =
|
||||
while isRunning():
|
||||
go()
|
||||
|
||||
when isMainModule:
|
||||
var bot = SittingDuck()
|
||||
start(bot, botJsonPath)
|
||||
```
|
||||
|
||||
**`tests/bots/SittingDuck/src/SittingDuck.json`** — required metadata:
|
||||
```json
|
||||
{
|
||||
"name": "SittingDuck",
|
||||
"version": "0.1.0",
|
||||
"authors": ["Test"],
|
||||
"description": "Does nothing — test adversary",
|
||||
"gameTypes": ["classic", "1v1"],
|
||||
"platform": "Nim",
|
||||
"programmingLang": "Nim"
|
||||
}
|
||||
```
|
||||
|
||||
Place adversary bots under `tests/bots/<BotName>/src/`. The framework infers the binary name from the directory name, so the directory name must match the `.nim` filename.
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**`TR server JAR not found`**
|
||||
Set `TR_SERVER_JAR` to the full path of your `robocode-tankroyale-server-*-all.jar`.
|
||||
|
||||
**`TR server did not start within 15s`**
|
||||
The server took too long — check that the JAR is valid and the port was free. Also check for leftover `java` processes from a previous crashed run.
|
||||
|
||||
**`BattleRunner timed out after Nms`**
|
||||
The `timeout` parameter (default 120 000 ms) was exceeded. Increase it: `runBattle(..., timeout = 300_000)`. Also check that bots are connecting to the server (look for compilation errors in test output).
|
||||
|
||||
**`BattleRunner exited with code N`**
|
||||
`TestBattleRunner.class` is missing or `TR_BATTLE_RUNNER` points at the wrong JAR. Re-run `run_test_battle.sh` once to recompile.
|
||||
|
||||
**Zombie `java` processes after a crash**
|
||||
The server process is registered with `addExitProc` and killed on normal exit. A hard kill (SIGKILL) of the test binary will leave the server process behind. Kill manually: `pkill -f robocode-tankroyale-server`.
|
||||
|
||||
**`No .nim source found in .../src/`**
|
||||
The bot directory's `src/` folder is empty or the `.nim` file is missing. The compiler expects `src/<DirName>.nim` (stripping a `_garage` suffix if present).
|
||||
@@ -0,0 +1,82 @@
|
||||
import std/[json, strutils, sequtils]
|
||||
|
||||
type
|
||||
BotRoundResult* = object
|
||||
name*: string
|
||||
score*: int
|
||||
rank*: int
|
||||
survived*: bool
|
||||
|
||||
RoundResult* = object
|
||||
round*: int
|
||||
results*: seq[BotRoundResult]
|
||||
|
||||
BotResult* = object
|
||||
name*: string
|
||||
totalScore*: int
|
||||
rank*: int
|
||||
firstPlaces*: int
|
||||
survivalCount*: int
|
||||
|
||||
BattleResult* = object
|
||||
bots*: seq[string]
|
||||
rounds*: seq[RoundResult]
|
||||
results*: seq[BotResult]
|
||||
winners*: seq[string] # bots with rank == 1
|
||||
|
||||
proc parseServerOutput*(stdout: string): BattleResult =
|
||||
for line in stdout.splitLines():
|
||||
let s = line.strip()
|
||||
if s.len == 0 or s[0] != '{': continue
|
||||
let node = parseJson(s)
|
||||
case node["event"].getStr()
|
||||
of "game_started":
|
||||
result.bots = node["bots"].getElems().mapIt(it.getStr())
|
||||
of "round_ended":
|
||||
var rr = RoundResult(round: node["round"].getInt())
|
||||
for r in node["results"].getElems():
|
||||
rr.results.add BotRoundResult(
|
||||
name: r["name"].getStr(),
|
||||
score: r["score"].getInt(),
|
||||
rank: r["rank"].getInt(),
|
||||
survived: r["survived"].getBool()
|
||||
)
|
||||
result.rounds.add rr
|
||||
of "battle_ended":
|
||||
for r in node["results"].getElems():
|
||||
result.results.add BotResult(
|
||||
name: r["name"].getStr(),
|
||||
totalScore: r["totalScore"].getInt(),
|
||||
rank: r["rank"].getInt(),
|
||||
firstPlaces: r["firstPlaces"].getInt(),
|
||||
survivalCount: r["survivalCount"].getInt()
|
||||
)
|
||||
result.winners = result.results.filterIt(it.rank == 1).mapIt(it.name)
|
||||
else: discard
|
||||
|
||||
when isMainModule:
|
||||
const sample = """
|
||||
{"event":"game_started","bots":["Alpha","Beta"]}
|
||||
{"event":"round_ended","round":1,"results":[{"name":"Alpha","score":150,"rank":1,"survived":true},{"name":"Beta","score":80,"rank":2,"survived":false}]}
|
||||
{"event":"round_ended","round":2,"results":[{"name":"Beta","score":200,"rank":1,"survived":true},{"name":"Alpha","score":60,"rank":2,"survived":false}]}
|
||||
{"event":"battle_ended","results":[{"name":"Alpha","totalScore":500,"rank":1,"firstPlaces":3,"survivalCount":5},{"name":"Beta","totalScore":300,"rank":2,"firstPlaces":1,"survivalCount":2}]}
|
||||
|
||||
not json, should be ignored
|
||||
"""
|
||||
let br = parseServerOutput(sample)
|
||||
assert br.bots == @["Alpha", "Beta"]
|
||||
assert br.rounds.len == 2
|
||||
assert br.rounds[0].round == 1
|
||||
assert br.rounds[0].results[0].name == "Alpha"
|
||||
assert br.rounds[0].results[0].score == 150
|
||||
assert br.rounds[0].results[0].rank == 1
|
||||
assert br.rounds[0].results[0].survived == true
|
||||
assert br.rounds[1].results[0].name == "Beta"
|
||||
assert br.rounds[1].results[1].survived == false
|
||||
assert br.results.len == 2
|
||||
assert br.results[0].name == "Alpha"
|
||||
assert br.results[0].totalScore == 500
|
||||
assert br.results[0].firstPlaces == 3
|
||||
assert br.results[0].survivalCount == 5
|
||||
assert br.winners == @["Alpha"]
|
||||
echo "all assertions passed"
|
||||
@@ -0,0 +1,48 @@
|
||||
## Compiles Nim bots before battle tests.
|
||||
## config.nims in each bot dir already sets --path and --outdir, so we just
|
||||
## run `nim c src/BotName.nim` from the bot dir and let config.nims do the rest.
|
||||
|
||||
import std/[os, osproc, streams, strformat, strutils, sequtils]
|
||||
|
||||
proc compileBots*(botDirs: seq[string]): seq[string] =
|
||||
## Compiles each bot dir, returns absolute paths to compiled binaries.
|
||||
## Raises on first compilation failure, message includes compiler output.
|
||||
for dir in botDirs:
|
||||
let absDir = absolutePath(dir)
|
||||
# Infer main source: src/<stem>.nim where stem = last path component
|
||||
# minus optional _garage suffix (e.g. OscillatorBot_garage → OscillatorBot)
|
||||
var stem = lastPathPart(absDir)
|
||||
if stem.endsWith("_garage"): stem = stem[0 ..< stem.len - "_garage".len]
|
||||
|
||||
let srcFile = absDir / "src" / stem & ".nim"
|
||||
if not fileExists(srcFile):
|
||||
# Fall back: pick the first .nim in src/
|
||||
let candidates = toSeq(walkFiles(absDir / "src" / "*.nim"))
|
||||
if candidates.len == 0:
|
||||
raise newException(IOError, fmt"No .nim source found in {absDir}/src/")
|
||||
stem = splitFile(candidates[0]).name
|
||||
|
||||
# ponytail: startProcess+streams for timeout; execCmdEx has no timeout param
|
||||
let p = startProcess("nim", workingDir = absDir,
|
||||
args = ["c", fmt"src/{stem}.nim"],
|
||||
options = {poUsePath, poStdErrToStdOut})
|
||||
let exitCode = waitForExit(p, timeout = 30_000)
|
||||
let output = p.outputStream.readAll()
|
||||
p.close()
|
||||
if exitCode != 0:
|
||||
raise newException(OSError,
|
||||
fmt"Compilation failed for {absDir}:{'\n'}{output}")
|
||||
|
||||
result.add absDir / "out" / stem
|
||||
|
||||
when isMainModule:
|
||||
let botDir = currentSourcePath().parentDir().parentDir().parentDir() /
|
||||
"OscillatorBot_garage"
|
||||
echo "Compiling OscillatorBot from: ", botDir
|
||||
try:
|
||||
let bins = compileBots(@[botDir])
|
||||
echo "OK — binary: ", bins[0]
|
||||
doAssert fileExists(bins[0]), "binary not found after compile"
|
||||
except CatchableError as e:
|
||||
echo "FAIL: ", e.msg
|
||||
quit(1)
|
||||
@@ -0,0 +1,61 @@
|
||||
## BattleRunner Java subprocess — capture stdout JSON-lines output.
|
||||
|
||||
import std/[osproc, os, strutils, streams, times, net]
|
||||
|
||||
const
|
||||
DefaultRunnerJar = "/home/davide/Projects/tank-royale/runner/examples/lib/robocode-tankroyale-runner.jar"
|
||||
ScriptDir = currentSourcePath().parentDir() / ".." / ".." / "tools" / "battle_runner"
|
||||
|
||||
proc runBattleRunner*(serverUrl: string, botDirs: seq[string], rounds: int,
|
||||
timeout: int = 30000): string =
|
||||
## Starts TestBattleRunner as a subprocess. Returns captured stdout on success.
|
||||
## Raises IOError on non-zero exit or TimeoutError on timeout.
|
||||
let jar = getEnv("TR_BATTLE_RUNNER", DefaultRunnerJar)
|
||||
let classDir = getEnv("TR_BATTLE_RUNNER_DIR", ScriptDir)
|
||||
|
||||
let args = @[
|
||||
"-cp", classDir & ":" & jar,
|
||||
"TestBattleRunner",
|
||||
"--server-url", serverUrl,
|
||||
"--rounds", $rounds,
|
||||
"--bot-dirs", botDirs.join(",")
|
||||
]
|
||||
|
||||
let p = startProcess("java", args = args,
|
||||
options = {poUsePath, poStdErrToStdOut})
|
||||
defer:
|
||||
p.close()
|
||||
|
||||
let deadline = epochTime() + timeout.float / 1000.0
|
||||
var stdout = ""
|
||||
var line: string
|
||||
while epochTime() < deadline:
|
||||
if p.peekExitCode() != -1:
|
||||
# Process finished; drain remaining output
|
||||
while p.outputStream.readLine(line):
|
||||
stdout.add(line & "\n")
|
||||
break
|
||||
if p.outputStream.readLine(line):
|
||||
stdout.add(line & "\n")
|
||||
|
||||
if epochTime() >= deadline and p.peekExitCode() == -1:
|
||||
p.terminate()
|
||||
raise newException(TimeoutError,
|
||||
"BattleRunner timed out after " & $timeout & "ms")
|
||||
|
||||
let code = p.waitForExit()
|
||||
if code != 0:
|
||||
raise newException(IOError,
|
||||
"BattleRunner exited with code " & $code & "\nOutput:\n" & stdout)
|
||||
|
||||
result = stdout
|
||||
|
||||
when isMainModule:
|
||||
echo "runner_process.nim — usage:"
|
||||
echo " runBattleRunner(serverUrl, botDirs, rounds, timeout)"
|
||||
echo ""
|
||||
echo "Env vars:"
|
||||
echo " TR_BATTLE_RUNNER JAR path (default: " & DefaultRunnerJar & ")"
|
||||
echo " TR_BATTLE_RUNNER_DIR class dir (default: tools/battle_runner/)"
|
||||
echo ""
|
||||
echo "Cannot self-test without a running TR server. Start one first."
|
||||
@@ -0,0 +1,67 @@
|
||||
## TR server lifecycle manager — lazy singleton for integration tests.
|
||||
## Start with ensureServer(), query with getServerUrl().
|
||||
|
||||
import std/[osproc, net, os, strutils, times, streams, exitprocs]
|
||||
|
||||
const
|
||||
DefaultJar = "/home/davide/Projects/tank-royale/server/build/libs/robocode-tankroyale-server-0.35.5-all.jar"
|
||||
ReadySignal = "Starting server on port"
|
||||
StartupTimeout = 15.0 # seconds
|
||||
|
||||
var
|
||||
serverProc: Process = nil
|
||||
serverPort: int = 0
|
||||
|
||||
proc findFreePort(): int =
|
||||
let s = newSocket()
|
||||
s.bindAddr(Port(0))
|
||||
let (_, port) = s.getLocalAddr()
|
||||
result = port.int
|
||||
s.close()
|
||||
|
||||
proc ensureServer*() =
|
||||
if serverProc != nil: return
|
||||
|
||||
let jar = getEnv("TR_SERVER_JAR", DefaultJar)
|
||||
if not fileExists(jar):
|
||||
raise newException(IOError, "TR server JAR not found: " & jar &
|
||||
"\nSet TR_SERVER_JAR env var to override.")
|
||||
|
||||
serverPort = findFreePort()
|
||||
serverProc = startProcess("java",
|
||||
args = @["-jar", jar, "--port", $serverPort, "--enable-initial-position"],
|
||||
options = {poUsePath, poStdErrToStdOut})
|
||||
|
||||
exitprocs.addExitProc(proc() =
|
||||
if serverProc != nil:
|
||||
serverProc.terminate()
|
||||
serverProc.close()
|
||||
)
|
||||
|
||||
# Wait for ready signal
|
||||
let deadline = epochTime() + StartupTimeout
|
||||
var ready = false
|
||||
while epochTime() < deadline:
|
||||
var line: string
|
||||
discard serverProc.outputStream.readLine(line)
|
||||
if ReadySignal in line:
|
||||
ready = true
|
||||
break
|
||||
if not ready:
|
||||
serverProc.terminate()
|
||||
serverProc.close()
|
||||
serverProc = nil
|
||||
raise newException(TimeoutError, "TR server did not start within " & $StartupTimeout & "s")
|
||||
|
||||
proc getServerUrl*(): string =
|
||||
if serverPort == 0:
|
||||
raise newException(CatchableError, "Server not started — call ensureServer() first")
|
||||
"ws://localhost:" & $serverPort
|
||||
|
||||
when isMainModule:
|
||||
echo "Starting TR server..."
|
||||
ensureServer()
|
||||
echo "Server ready at: ", getServerUrl()
|
||||
echo "Sleeping 2s then exiting (addExitProc will kill server)..."
|
||||
os.sleep(2000)
|
||||
echo "Done."
|
||||
@@ -0,0 +1,32 @@
|
||||
## Public API for the TR integration test framework.
|
||||
## Import this module only; it re-exports all types you need.
|
||||
|
||||
import ./server_manager
|
||||
import ./bot_compiler
|
||||
import ./battle_result
|
||||
import ./runner_process
|
||||
|
||||
export battle_result.BattleResult
|
||||
export battle_result.BotResult
|
||||
export battle_result.RoundResult
|
||||
export battle_result.BotRoundResult
|
||||
|
||||
proc runBattle*(botDirs: seq[string], rounds: int = 10,
|
||||
timeout: int = 120000): BattleResult =
|
||||
ensureServer()
|
||||
discard compileBots(botDirs)
|
||||
let stdout = runBattleRunner(getServerUrl(), botDirs, rounds, timeout)
|
||||
result = parseServerOutput(stdout)
|
||||
|
||||
when isMainModule:
|
||||
echo "test_framework.nim — public API, not a standalone binary."
|
||||
echo "Requires a TR server JAR. Usage from your test file:"
|
||||
echo ""
|
||||
echo " import common_libs/test_framework/test_framework"
|
||||
echo " let r = runBattle(@[\"path/to/BotA\", \"path/to/BotB\"])"
|
||||
echo " echo r.winners"
|
||||
echo ""
|
||||
echo "Env vars forwarded to sub-modules:"
|
||||
echo " TR_SERVER_JAR TR server JAR path"
|
||||
echo " TR_BATTLE_RUNNER BattleRunner JAR path"
|
||||
echo " TR_BATTLE_RUNNER_DIR BattleRunner class dir"
|
||||
Reference in New Issue
Block a user