vmm-tests

name	vmm-tests
description	Run VMM tests locally with cargo xflowey vmm-tests-run. Load when running or debugging VMM tests, or when you need to understand the petri test framework, artifact handling, or cross-compilation for VMM tests.

Running VMM Tests

VMM tests boot full virtual machines and validate behavior. They live in vmm_tests/vmm_tests/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/vmm_tests. When cross-compiling for Windows from WSL2, --dir on the Windows filesystem (e.g., --dir /mnt/d/vmm_tests) 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/vmm_tests) 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/dev_guide/getting_started/cross_compile.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_tests directly — 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-investigation skill to diagnose failing VMM tests in CI, not this workflow.