Features

write automatically covers write, writev, pwrite64. Think in operations, not syscall numbers.

Fault only writes to /data/*.wal — stdout, TCP, and other writes are unaffected. Powered by fd→path resolution via /proc.

deny("EIO", probability="30%") or deny("EIO", trigger="after=5") — intermittent failures and trigger-on-Nth-call.

fault(service) = syscall level. fault(service.interface) = protocol level. Same builtin, different dispatch.

Return HTTP 503 for POST /orders, inject Postgres query errors, drop Kafka messages on specific topics.

parallel(fn1, fn2) runs operations concurrently. Faultbox controls which syscall proceeds first.

Every test run has a seed. Failed? Replay with --seed 42 for identical interleaving — deterministic debugging.

--explore=all tries every permutation (K! orderings). --explore=sample randomly samples for faster coverage.

service(), interface(), depends_on, healthcheck — declare topology as code.

assert_eq(), assert_eventually(), assert_never(), assert_before() — value checks and temporal properties on the syscall trace.

Register happy paths with scenario(), then faultbox generate creates failure tests automatically.

"The WAL write happened before the response" — assert_before() proves ordering guarantees.

--shiviz trace.shiviz produces a space-time diagram with causal arrows between services.

Capture before/after a refactor. faultbox diff shows exactly what behavioral changes you introduced.

binary="./my-service" — fork+exec with seccomp filter. Fastest iteration, no Docker needed.

image="postgres:16" — Docker containers with faultbox-shim entrypoint. Test against real Postgres, Redis, Kafka.

Callbacks that fire on every matching event — fail immediately if an invariant is violated.

partition(orders, inventory, run=scenario) — bidirectional network split, other connectivity intact.

ops={"persist": op(syscalls=["write","fsync"], path="*.wal")} — fault the WAL persist operation, not individual syscalls.