SKILL.md
Running VMM Tests
VMM tests boot full virtual machines and validate behavior. They live in vmmtests/vmmtests/tests/tests/ and use the petri test framework.
Always use cargo xflowey vmm-tests-run — never raw cargo nextest run -p vmm_tests. The xflowey command handles artifact discovery, dependency building, and test execution automatically.
Quick Start
# Run a specific test
cargo xflowey vmm-tests-run --filter "test(my_test_name)"
# Run all tests matching a prefix
cargo xflowey vmm-tests-run --filter "test(/^boot_/)"
# Run all tests (rarely needed locally)
cargo xflowey vmm-tests-run --filter "all()"Usually you don't need --dir — it defaults to target/vmmtests. When cross-compiling for Windows from WSL2, --dir on the Windows filesystem (e.g., --dir /mnt/d/vmmtests) is required only when the selected tests use disk images that need a Windows filesystem: Hyper-V tests, or tests using VHDX / dynamic VHD1 images. For everything else (streamed disks, or plain fixed VHD1 / VMGS / ISO files), the default WSL-side directory works. vmm-tests-run detects this and errors with a clear message if --dir is required.
Filter Syntax
Filters use nextest filter expressions:
| Expression | Matches |
|---|---|
test(foo) |
Tests with foo in the name |
test(/^boot_/) |
Tests starting with boot_ (regex) |
test(foo) & !test(hyperv) |
foo tests excluding Hyper-V variants |
all() |
Everything |
Platform Targeting
By default, tests build for the current host. Use --target for cross-compilation:
# Cross-compile and run Windows tests from WSL2
cargo xflowey vmm-tests-run --target windows-x64| Target | Description |
|---|---|
windows-x64 |
Windows x86_64 (Hyper-V / WHP) |
windows-aarch64 |
Windows ARM64 (Hyper-V / WHP) |
linux-x64 |
Linux x86_64 |
Windows from WSL2: The default output directory works for most tests. Add --dir on the Windows filesystem (e.g., --dir /mnt/d/vmmtests) only when the selected tests use disk images requiring a Windows filesystem (Hyper-V tests, or VHDX / dynamic VHD1 images); vmm-tests-run errors with a clear message when it's needed. Cross-compilation setup is required first — see Guide/src/devguide/gettingstarted/crosscompile.md.
Artifact Handling (Lazy Fetch)
By default, disk images (VHDs/ISOs) are streamed on demand via HTTP with local SQLite caching. This avoids multi-GB upfront downloads.
--no-lazy-fetch— download all images upfront instead of streaming- Lazy fetch is automatically disabled for Hyper-V tests (they need local files)
--skip-vhd-prompt— skip interactive VHD download prompts (useful for
automation)
Viewing Logs
Test output (petri logs, guest serial, etc.) is shown by default on failure. For full OpenVMM tracing, set the OPENVMM_LOG environment variable:
OPENVMM_LOG=trace cargo xflowey vmm-tests-run --filter "test(foo)"Other Useful Flags
| Flag | Purpose |
|---|---|
--release |
Release build (default: debug) |
--build-only |
Build without running |
--verbose |
Verbose cargo output |
--install-missing-deps |
Auto-install missing system dependencies |
--custom-uefi-firmware <PATH> |
Use a custom UEFI firmware (MSVM.fd) |
--custom-kernel <PATH> |
Use a custom kernel image |
Run cargo xflowey vmm-tests-run --help for the full option list.
Common Pitfalls
- Don't use
cargo nextest run -p vmm_testsdirectly — artifacts won't
be present and tests will fail with missing-artifact errors.
- Windows output dir from WSL — when the selected tests need a Windows
filesystem (Hyper-V tests, or VHDX / dynamic VHD1 images), --dir must be on /mnt/c/ or /mnt/d/, not in the WSL filesystem. Other tests use the default.
- Hyper-V tests — require Hyper-V Administrators group membership and
disable lazy fetch automatically.
- CI failures — use the
openvmm-ci-investigationskill to diagnose
failing VMM tests in CI, not this workflow.