# 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.