guillaumearm/cc-libs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
e5d8e16c5a
cc-libs/DEVELOPMENT.md
Guillaume ARM e5d8e16c5a test(craftos): add layered test timeouts
2026-06-08 05:37:49 +02:00

2.7 KiB
Raw Blame History

Development

Requirements:

  • just
  • jq
  • luacheck
  • CraftOS-PC ≥ v2.8.3 — local harness for the CC:Tweaked sandbox; see docs/craftos_pc_glossary.md for CLI flags, mounting, periphemu, save data, and troubleshooting references.

After cloning the repository, run:

just install

This creates .env from .env.sample when needed and installs the local Git hooks, including a pre-commit hook that runs just ci.

just ci is the local verification entry point. Today it verifies that craftos --version reports v2.8.3 or newer, runs just check for luacheck, and runs just test for CraftOS-PC headless tests. Use just craftos to launch CraftOS-PC with repo-local save data under .craftos and read-only mounts for /trapos, /apis, /programs, /servers, and /startup. just repl opens the same environment with --cli for human interactive use only; LLM agents must not run it. Use the CraftOS-PC glossary when adjusting --headless, --exec, --script, --rom, or --mount-* usage.

Tests live under tests/ and run inside CraftOS-PC through just test, which launches /programs/runtest.lua. API-level tests should use require('/apis/libtest')({ ... }), register cases with testlib.test(name, fn), and call testlib.run() at the end. libtest tests remain normal ComputerCraft programs; the runner handles suite discovery, grouped output, and the __TRAPOS_TEST_OK__ shell success contract. Pass --pretty to just test for grouped colored [OK]/[KO] statuses, or --verbose for additional runner/debug detail.

Test timeouts run in two independent layers (see docs/adrs/adr-0009-layered-test-timeouts.md):

  • libtest per-case timeout (primary). Each libtest case is cancelled after 3 seconds by default, failing with a distinct libtest timeout message. Override with --timeout <seconds>, or disable with --no-timeout (both forwarded by runtest to each case). This catches a single hung case quickly without taking down the whole run.
  • Shell watchdog (backstop). The whole CraftOS-PC process is killed if it does not finish within TRAP_CCLIBS_TEST_TIMEOUT_SECONDS (.env.sample ships 7; the recipe falls back to 7). Keep it above the 3s libtest default so libtest fires first; the watchdog only catches what Lua cannot interrupt. Override in .env for slower local probes.

just test-timeout-5s and just test-timeout-10s are self-asserting harness checks for these layers (fixtures under tests/harness/, not part of just test): the first proves libtest cancels a 5s case at 3s, the second proves the shell watchdog kills a 10s case run with --no-timeout.