The testing framework here allows you to write code to configure libkrun (using the public API) and run some specific code in the guest.
The tests can be run using make test (from the main libkrun directory).
You can also run ./run.sh inside the tests directory. It uses static linking by default. To test the shared libraries directly on Linux, build the local prefix and set the library paths from inside tests/:
make test-prefix # from the repository root
cd tests
KRUN_TEST_FFI=1 \
PKG_CONFIG_PATH="$(realpath ../test-prefix/lib64/pkgconfig)" \
LIBKRUN_LIB_PATH="$(realpath ../test-prefix/lib64)" \
./run.sh test-
Install required build tools:
brew install lld xz rustup target add aarch64-unknown-linux-musl
-
Install libkrunfw from the libkrun Homebrew tap:
brew tap libkrun/krun brew trust libkrun/krun brew install libkrunfw
For a source build, follow the libkrunfw macOS instructions, then run
make test LIBKRUNFW_SRC=/path/to/libkrunfwto install that firmware intotest-prefix/for the tests.make testincludes the Homebrew libkrunfw path automatically.
make testTo add a test, add a Rust module under tests/test_cases/src/, implement the required host and guest methods (see existing tests), and register it in tests/test_cases/src/lib.rs.
FreeBSD guest tests run on Linux (amd64, arm64) and macOS (arm64) hosts. They require two external assets that are not bundled in the repository.
-
Install required tools:
- macOS:
bsdtaris built-in (/usr/bin/bsdtar) - Linux:
sudo apt-get install libarchive-tools(providesbsdtar) - Linux/macOS amd64: add the Rust cross-compilation target:
rustup target add x86_64-unknown-freebsd
- Linux/macOS arm64:
aarch64-unknown-freebsdhas no prebuilt stdlib in rustup, so a nightly toolchain with rust-src component is needed:rustup +nightly-2026-01-25 component add rust-src
- macOS:
-
Build the FreeBSD sysroot and
init-freebsd(from the libkrun root directory):make BUILD_BSD_INIT=1 -- init/init-binary/init-freebsd
This downloads
freebsd-sysroot/base.txz, extracts it tofreebsd-sysroot/, and compilesinit/init-binary/init-freebsd. -
The FreeBSD kernel is downloaded and cached automatically by
run.sh(from a Firecracker-optimized release on x86_64 ordownload.freebsd.orgon aarch64). To use a locally provided kernel instead, setKRUN_TEST_FREEBSD_KERNEL_PATHbefore 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
With the sysroot/init assets built, run.sh (or make test) will automatically:
- Cache the x86_64 kernel at
target/freebsd-kernel/freebsd-kern.binor the aarch64 kernel attarget/freebsd-kernel/boot/kernel/kernel.bin - Cross-compile the
guest-agentfor FreeBSD - Build
target/freebsd-test-rootfs.isofrominit-freebsd+ the FreeBSDguest-agent - Set
KRUN_TEST_FREEBSD_KERNEL_PATHandKRUN_TEST_FREEBSD_ISO_PATHfor the runner
FreeBSD tests are skipped (not failed) when the kernel or ISO are unavailable, so the test suite still passes without FreeBSD assets.