ADR 0008: Keep Tests Runnable In CraftOS And In-Game

Status

Accepted

Date

2026-06-08

Context

The initial CraftOS-PC harness proved that repository code can be tested locally, but the first shell recipe also owned too much suite behavior: explicit test lists, per-case rendering, and success formatting. That made the host shell script more complex than necessary and tied test orchestration to CraftOS-PC launch details.

At the same time, tests in this repository are still ComputerCraft programs. They should be useful in CraftOS-PC and in-game, not only inside a host-side shell loop.

Decision

Keep /apis/libtest.lua focused on test cases and assertions. It must stay usable from normal ComputerCraft programs in CraftOS-PC or in-game.

Move suite orchestration into /programs/runtest.lua. The runner discovers tests under /tests, invokes each script with shell.run, renders grouped --pretty output, emits additional --verbose diagnostics, prints __TRAPOS_TEST_OK__ only after the full suite passes, and can shut down when the host harness asks with --shutdown.

Keep the Justfile minimal. It launches CraftOS-PC, mounts repository directories, enforces the process timeout, checks for the success marker, and prints runner output files. It should not know about individual test files or cases.

Consequences

Tests using libtest remain plain ComputerCraft programs.
/programs/runtest.lua can be run inside CraftOS-PC or in-game when /tests and dependencies are present.
Pretty colors and grouped suite output are runner concerns, not libtest concerns.
Verbose mode is reserved for debugging and agent work loops, while --pretty is the normal human-readable mode.
Host-specific concerns remain outside production Lua code.

Future Work

Add test selection filters when the suite grows.
Add runner-level timing if slow tests become hard to diagnose.
Add more libtest assertions only when real tests need them.

1.9 KiB Raw Blame History