snapbox testing harness #
this directory contains the regression testing suite for snapbox. because snapbox relies heavily on mount namespaces, overlay filesystems, and sudo privileges, standard unit tests don't cut it. this harness spins up an isolated tmpfs and runs snapbox commands against it to verify behavior end-to-end.
directory structure #
├── testing │ ├── readme.md # this file │ ├── run_tests # the main test runner script │ ├── test1 # a barebones proof-of-concept test │ │ ├── mksource # populates the initial "source of truth" directory │ │ ├── ops # runs snapbox commands against the source │ │ └── mkresult # populates the expected final state directory │ └── test2 │ ├── ...
how it works #
for every test directory found, the run_tests script executes the following lifecycle:
- wipe: the harness creates a fresh
tmpfsat/snapbox/testingand wipes any existing snapbox state (mounts, boxes, snaps). - mksource: the harness
cds into an emptysource/directory and runsmksource. this script creates the files that represent the initial codebase. - ops: the harness
cds intosource/and runsops. this script executes snapbox commands (e.g.box,at-box,take,rmbox) to mutate the source directory. the working directory issource/, so you can just runbox myboxwithout specifying a path. - mkresult: the harness
cds into an emptyresult/directory and runsmkresult. this script creates the files that represent what the source should look like afteropssuccessfully ran. - diff: the harness recursively diffs
source/andresult/. if they match, the test passes. if they differ, the test fails and the diff is printed.
creating a new test #
- create a new directory in
testing/(e.g.testing/my_feature_test/). - create three executable bash scripts inside it:
mksource #
this sets up your baseline. you are running inside an empty directory.
#!/usr/bin/env bash
mkdir -p src
echo "fn main() {}" > src/main.rs
ops #
this is where you use snapbox. you are running inside source/, so . is the target.
#!/usr/bin/env bash
set -euo pipefail
box dev
# do some work in the box (use a subshell if the command execs)
(at-box dev bash -c 'echo " println!(\"hello\");" >> src/main.rs')
# promote the changes back to source
echo "y" | take dev > /dev/null
rmbox dev
mkresult #
this is what source/ should look like after ops is done. you are running inside an empty directory.
#!/usr/bin/env bash
mkdir -p src
echo "fn main() {}
println!(\"hello\");" > src/main.rs
running the tests #
first time setup:
none! as long as snapbox is installed (via the main install.sh and box-init), you're good to go. the test harness uses the standard snapbox-priv wrapper to mount its isolated testing tmpfs at /snapbox/testing.
running the suite:
bash testing/run_tests
note: the test harness will completely wipe /snapbox/ state (snaps, boxes, runs) between tests to ensure a clean slate. it will prompt you if it detects existing boxes/snaps before starting.