# Vmm Tests

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

- Skill: `microsoft/vmm-tests` (Agent Skill)
- Install (CLI): `npx skillmds@latest add microsoft/vmm-tests`
- Raw SKILL.md: https://api.skillmd.com/api/skills/microsoft/vmm-tests/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Microsoft (https://skillmd.com/u/microsoft)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/microsoft/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

```bash
# 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](https://nexte.st/docs/filtersets/):

| 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:

```bash
# 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:

```bash
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.