Testing

This guide covers running tests and building test VMs for Capsa development.

Running Tests

Unit Tests

# Linux
cargo test-linux --lib

# macOS
cargo test-macos --lib

Integration Tests

Integration tests require actual hypervisor access:

# Linux (requires /dev/kvm)
cargo test-linux -- --test-threads=1

# macOS (requires Virtualization.framework entitlements)
cargo test-macos -- --test-threads=1

Single Thread

Integration tests must run with --test-threads=1 to avoid resource contention. Multiple VMs competing for the same ports or sockets will cause failures.

Running Specific Tests

# Run a specific integration test
cargo test-linux --test boot_test

# Run tests matching a name
cargo test-linux test_console

Doc Tests

cargo test-linux --doc
cargo test-macos --doc

Linting

# Check formatting
cargo fmt --all -- --check

# Run clippy
cargo clippy-linux -- -D warnings    # Linux
cargo clippy-macos -- -D warnings    # macOS

Building Test VMs

Test VMs are NixOS-based minimal systems built specifically for testing Capsa features.

Building

# For x86_64 (Intel/AMD Linux, Intel Mac)
nix-build nix/test-vms -A x86_64 -o result-vms

# For aarch64 (Apple Silicon)
nix-build nix/test-vms -A aarch64 -o result-vms

This creates a result-vms symlink containing:

• kernel - Linux kernel (bzImage format)
• initrd - Initial ramdisk with test utilities
• disk.img - Root filesystem (for disk tests)

Available Test VMs

The test VM system provides several configurations:

VM	Description
default	Universal VM with networking, disk, and vsock support
with-disk	Default + pre-created disk image
uefi	UEFI-bootable VM for testing UEFI boot

Using Test VMs in Code

use capsa::test_utils::{test_vm, BOOT_SUCCESS_MESSAGE};
use std::time::Duration;

#[tokio::test]
async fn my_test() {
    let vm = test_vm("default")
        .cpus(2)
        .memory_mb(512)
        .build()
        .await
        .expect("Failed to build VM");

    let console = vm.console().await.unwrap();
    console
        .wait_for_timeout(BOOT_SUCCESS_MESSAGE, Duration::from_secs(30))
        .await
        .unwrap();

    // Your test here...
}

Troubleshooting

KVM Not Available (Linux)

Error: Backend unavailable: KVM device /dev/kvm not accessible

Solutions:

1. Ensure KVM module is loaded: sudo modprobe kvm_intel or kvm_amd
2. Check permissions: sudo chmod 666 /dev/kvm (or use udev rules)
3. Add user to kvm group: sudo usermod -aG kvm $USER

Entitlement Errors (macOS)

Error: The operation couldn't be completed. (Virtualization error -1)

Solution: Ensure you're running within the dev shell which provides codesign-run for automatic signing.

VZD Not Found (macOS)

Error: capsa-apple-vzd not found

Solutions:

1. Set CAPSA_VZD_PATH environment variable
2. Build vzd: cargo build -p capsa-apple-vzd
3. Run within the dev shell

Test Timeouts

If tests hang or timeout:

1. Ensure you're using --test-threads=1
2. Check that test VMs are built (result-vms exists)
3. Verify hypervisor access (/dev/kvm on Linux)