Writing tests

How to register tests, organise a file, use assertions, skip cleanly, log diagnostic data, and pick per-test metadata.

How to create, boot, snapshot, restore, pause, reset, and inject files into VMs. How profiles map to kernel/initrd choices, and how multiple profiles let one test run against different kernels.

Patterns for vm:run (sync, shell-form vs direct exec, env, cwd, stdin, timeouts), vm:run_async (Process handles, signals, stdout/stderr streams), and worker-side variants.

Patterns for guest-side file I/O — read_file/write_file vs open_file, mode tables, seek/tell, tail streams, stat, listdir, mkdir, unlink, rename, and ioctl over open handles.

How to attach disks, read and write sectors directly, and inject EIO and slow I/O faults to exercise guest-side error recovery.

How to wire VMs into bridges, partition them symmetrically and directionally, inject latency / drop rate / bandwidth limits, isolate single VMs, capture pcap, and route to the outside world via uplink.

Patterns for the three stream userdata types — when to use next vs read_until vs expect vs drain, how to handle EOF, what creation_site is for, and how snapshots interact with live streams.

How to use sub-labs to organise multi-VM topologies, claim resources from the pool, synchronise across workers with barriers, snapshot and restore whole labs, and use lab fixtures for cached setups.