End-to-end tests #

The testing framework here allows you to write code to configure libkrun (using the public API) and run some specific code in the guest.

Running the tests: #

The tests can be ran using make test (from the main libkrun directory). You can also run ./run.sh inside the test directory. When using the ./run.sh script you probably want specify the PKG_CONFIG_PATH enviroment variable, otherwise you will be testing the system wide installation of libkrun.

Running on macOS #

Prerequisites #

1. Install required build tools:

   brew install lld xz
   rustup target add aarch64-unknown-linux-musl
   

2. Install libkrunfw - either via homebrew:

   brew install libkrunfw
   

   Or build from source:

   curl -LO https://github.com/containers/libkrunfw/releases/download/v5.2.0/libkrunfw-prebuilt-aarch64.tgz
   tar -xzf libkrunfw-prebuilt-aarch64.tgz
   cd libkrunfw
   make
   sudo make install
   

   If installed from source, add /usr/local/lib to your library path:

   export DYLD_LIBRARY_PATH="/usr/local/lib:${DYLD_LIBRARY_PATH}"
   

   The test harness automatically handles the library path for homebrew installations.

Running tests #

make test

Adding tests #

To add a test you need to add a new rust module in the test_cases directory, implement the required host and guest side methods (see existing tests) and register the test in the test_cases/src/lib.rs to be ran.

FreeBSD guest tests #

FreeBSD guest tests run on Linux (amd64, arm64) and macOS (arm64) hosts. They require two external assets that are not bundled in the repository.

Prerequisites #

1. Install required tools:

   • macOS: bsdtar is built-in (/usr/bin/bsdtar)
   • Linux: sudo apt-get install libarchive-tools (provides bsdtar)
   • Linux/macOS amd64: add the Rust cross-compilation target:

     rustup target add x86_64-unknown-freebsd
     

   • Linux/macOS arm64: aarch64-unknown-freebsd has no prebuilt stdlib in rustup, so a nightly toolchain with rust-src component is needed:

     rustup +nightly-2026-01-25 component add rust-src
     

2. Build the FreeBSD sysroot and init-freebsd (from the libkrun root directory):

   make BUILD_BSD_INIT=1 -- init/init-freebsd
   

   This downloads freebsd-sysroot/base.txz, extracts it to freebsd-sysroot/, and compiles init/init-freebsd.

3. The FreeBSD kernel is downloaded and cached automatically by run.sh (from download.freebsd.org). To use a locally-provided kernel instead, set KRUN_TEST_FREEBSD_KERNEL_PATH before running:

   export KRUN_TEST_FREEBSD_KERNEL_PATH="/path/to/boot/kernel/kernel"      # amd64
   export KRUN_TEST_FREEBSD_KERNEL_PATH="/path/to/boot/kernel/kernel.bin"  # arm64
   

Running FreeBSD tests #

With the sysroot/init assets built, run.sh (or make test) will automatically:

• Download and cache target/freebsd-kernel/boot/kernel/kernel[.bin] if not already present
• Cross-compile the guest-agent for FreeBSD
• Build target/freebsd-test-rootfs.iso from init-freebsd + the FreeBSD guest-agent
• Set KRUN_TEST_FREEBSD_KERNEL_PATH and KRUN_TEST_FREEBSD_ISO_PATH for the runner

FreeBSD tests are skipped (not failed) when the kernel or ISO are unavailable, so the test suite still passes without FreeBSD assets.