LiteInst Testing
Preconditions
Tests require Linux x86-64, dynamically linked guest programs, seccomp/SIGSYS,
and permission to load the generated preload DSO. Run process-wide runtime tests
serially with --test-threads=1.
Coverage Matrix
Use tests/strace.rs for:
- first-trap patch installation and hook counts;
- built-in strace and compatibility event stability;
- event-fd isolation, spoof rejection, backpressure, and recovery;
- compatibility fork behavior and explicit unsafe clone/exec failures.
Use tests/rpc_tool.rs for:
- shared coordinator RPC and hook reentry bypass;
- preinstalled, pending, blocked, or spoofed SIGSYS states;
- syscall subscription, thread/process callbacks, and injected exit;
- typed tool guest access and coordinator interaction.
Use ../reverie-examples/tests/liteinst.rs for:
- the public
LiteinstBackend launcher and bootstrap contract;
- concrete no-op, counter, chaos, strace, and trace tools;
- output, environment, descriptor, allocator, and tool-option behavior.
Commands
Start narrow, then broaden:
cargo test -p reverie-liteinst --test strace -- --test-threads=1
cargo test -p reverie-liteinst --test rpc_tool -- --test-threads=1
cargo test -p reverie-liteinst --all-features -- --test-threads=1
cargo test -p reverie-examples --test liteinst -- --test-threads=1
cargo fmt --all -- --check
cargo clippy -p reverie-liteinst --all-targets --all-features
Use a bounded external timeout while diagnosing a possible hang, but do not add
large internal sleeps or weaken assertions to mask it. Capture the exact test,
guest command, child/process state, and whether execution reached trap, hook,
tool dispatch, or RPC.
Regression Design
- Test the owning contract at the lowest layer that exposes it.
- Assert externally visible behavior, not incidental log formatting or syscall
totals, except for the dedicated first-trap/hook regression.
- For patching regressions, execute the same syscall site repeatedly and prove
one discovery trap followed by hook entries. The established signature is
calls=32 traps=1 hooks=32.
- For bootstrap and descriptor regressions, prove control state is sealed,
consumed, protected, and hidden from the guest.
- For safety boundaries, assert explicit rejection and no hang.
- Avoid global environment leakage between tests; restore any process state the
test owns.
Evidence Discipline
Record the full commit SHA, host architecture, exact commands, and results.
Distinguish:
- a direct preload/crate test;
- a public Reverie
LiteinstBackend examples test;
- a Hermit CLI run at compatible landed revisions.
The first two are L0 evidence. They do not establish Hermit L1 record or L2
strict verify. State unsupported signals, multi-threading, clocks, and
preemption directly rather than implying deterministic coverage.
1---2name: liteinst-testing3description: "Use when adding LiteInst regressions, selecting focused test coverage, diagnosing guest hangs, or reporting backend and determinism evidence."4metadata:5 source: https://skillmd.com/skills/facebookexperimental/liteinst-testing6---78# LiteInst Testing910## Preconditions1112Tests require Linux x86-64, dynamically linked guest programs, seccomp/SIGSYS,13and permission to load the generated preload DSO. Run process-wide runtime tests14serially with `--test-threads=1`.1516## Coverage Matrix1718Use `tests/strace.rs` for:1920- first-trap patch installation and hook counts;21- built-in strace and compatibility event stability;22- event-fd isolation, spoof rejection, backpressure, and recovery;23- compatibility fork behavior and explicit unsafe clone/exec failures.2425Use `tests/rpc_tool.rs` for:2627- shared coordinator RPC and hook reentry bypass;28- preinstalled, pending, blocked, or spoofed SIGSYS states;29- syscall subscription, thread/process callbacks, and injected exit;30- typed tool guest access and coordinator interaction.3132Use `../reverie-examples/tests/liteinst.rs` for:3334- the public `LiteinstBackend` launcher and bootstrap contract;35- concrete no-op, counter, chaos, strace, and trace tools;36- output, environment, descriptor, allocator, and tool-option behavior.3738## Commands3940Start narrow, then broaden:4142```bash43cargo test -p reverie-liteinst --test strace -- --test-threads=144cargo test -p reverie-liteinst --test rpc_tool -- --test-threads=145cargo test -p reverie-liteinst --all-features -- --test-threads=146cargo test -p reverie-examples --test liteinst -- --test-threads=147cargo fmt --all -- --check48cargo clippy -p reverie-liteinst --all-targets --all-features49```5051Use a bounded external timeout while diagnosing a possible hang, but do not add52large internal sleeps or weaken assertions to mask it. Capture the exact test,53guest command, child/process state, and whether execution reached trap, hook,54tool dispatch, or RPC.5556## Regression Design5758- Test the owning contract at the lowest layer that exposes it.59- Assert externally visible behavior, not incidental log formatting or syscall60 totals, except for the dedicated first-trap/hook regression.61- For patching regressions, execute the same syscall site repeatedly and prove62 one discovery trap followed by hook entries. The established signature is63 `calls=32 traps=1 hooks=32`.64- For bootstrap and descriptor regressions, prove control state is sealed,65 consumed, protected, and hidden from the guest.66- For safety boundaries, assert explicit rejection and no hang.67- Avoid global environment leakage between tests; restore any process state the68 test owns.6970## Evidence Discipline7172Record the full commit SHA, host architecture, exact commands, and results.73Distinguish:7475- a direct preload/crate test;76- a public Reverie `LiteinstBackend` examples test;77- a Hermit CLI run at compatible landed revisions.7879The first two are L0 evidence. They do not establish Hermit L1 record or L280strict verify. State unsupported signals, multi-threading, clocks, and81preemption directly rather than implying deterministic coverage.