agent management prototype
readme.md

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:

  1. wipe: the harness creates a fresh tmpfs at /snapbox/testing and wipes any existing snapbox state (mounts, boxes, snaps).
  2. mksource: the harness cds into an empty source/ directory and runs mksource. this script creates the files that represent the initial codebase.
  3. ops: the harness cds into source/ and runs ops. this script executes snapbox commands (e.g. box, at-box, take, rmbox) to mutate the source directory. the working directory is source/, so you can just run box mybox without specifying a path.
  4. mkresult: the harness cds into an empty result/ directory and runs mkresult. this script creates the files that represent what the source should look like after ops successfully ran.
  5. diff: the harness recursively diffs source/ and result/. if they match, the test passes. if they differ, the test fails and the diff is printed.

creating a new test #

  1. create a new directory in testing/ (e.g. testing/my_feature_test/).
  2. 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.