version: "1.0.0" 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()"

Do not pass --dir — it defaults to target/vmm_tests and is only required when cross-compiling for Windows from WSL2, where the output directory must be on the Windows filesystem (e.g., --dir /mnt/d/vmm_tests).

Filter Syntax

Filters use nextest filter expressions:

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 --dir /mnt/d/vmm_tests

Windows from WSL2: The output directory must be on the Windows filesystem (e.g., /mnt/d/...). --dir is required in this case. 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

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 — must be on /mnt/c/ or /mnt/d/, not

in the WSL filesystem.

• 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.