flowey: add new vmm-tests-run command

.github/copilot-instructions.md

@@ -85,6 +85,14 @@ Run tests with cargo-nextest in the specific packages you are modifying:
 cargo nextest run -p <package-name>
 ```
 
+For VMM test validation during development, use `cargo xflowey vmm-tests-run`:
+```bash
+# Run a specific test
+cargo xflowey vmm-tests-run --filter "test(my_test_name)" --dir <output-dir>
+```
+This automatically discovers artifacts, builds dependencies, and runs tests.
+See `Guide/src/dev_guide/tests/vmm.md` for details.
+
 - **Unit tests** — spread throughout crates in `#[cfg(test)]` blocks.
   Should be fast, isolated, and not require root/administrator access.
   Add `use test_with_tracing::test;` in test modules so that `tracing`

Cargo.lock

@@ -2069,6 +2069,7 @@ dependencies = [
  "flowey_lib_hvlite",
  "log",
  "serde",
+ "serde_json",
  "target-lexicon",
  "vmm_test_images",
 ]
@@ -2095,10 +2096,12 @@ dependencies = [
 name = "flowey_lib_hvlite"
 version = "0.0.0"
 dependencies = [
+ "anyhow",
  "crossterm",
  "flowey",
  "flowey_lib_common",
  "igvmfilegen_config",
+ "log",
  "powershell_builder",
  "serde",
  "serde_json",

Guide/src/dev_guide/dev_tools/xflowey.md

@@ -11,6 +11,7 @@ Some particularly notable pipelines:
 
 - `cargo xflowey build-igvm` - primarily dev-tool used to build OpenHCL IGVM files locally
 - `cargo xflowey restore-packages` - restores external packages needed to compile and run OpenVMM / OpenHCL
+- `cargo xflowey vmm-tests-run` - build and run VMM tests with automatic artifact discovery. Use `--filter "test(name)"` to run specific tests
 
 ## `xflowey` vs `xtask`
 

Guide/src/dev_guide/tests/vmm.md

@@ -82,26 +82,46 @@ locally, set the following environment variable: `PETRI_REPORT_UNSTABLE_FAIL=1`
 
 ## Running VMM Tests (Flowey)
 
-The easiest way to run the VMM tests locally is using the
-`cargo xflowey vmm-tests` command. To see the most up-to-date options, run:
-`cargo xflowey vmm-tests --help`. When running Hyper-V tests, you will need
-to use an administrator terminal window (this works even if you are running
-from WSL2). When running Windows tests, the output dir should be on the
-Windows file system. For example, from WSL2:
+The easiest way to run VMM tests locally is `cargo xflowey vmm-tests-run`. It
+automatically discovers required artifacts, builds dependencies, and runs your
+tests in a single command.
+
+To run a **specific test** (or set of tests), use `--filter` with a
+[nextest filter](https://nexte.st/docs/filtersets/) expression:
 
 ```bash
-cargo xflowey vmm-tests --target windows-x64 --dir /mnt/e/vmm_tests
+cargo xflowey vmm-tests-run --filter "test(my_test_name)" --dir /tmp/vmm-tests-run
 ```
 
-This command will build or download all the test dependencies and copy them
-to a self-contained folder that can be copied to another system for testing.
-The folder will contain scripts for installing dependencies
-(install_deps.ps1 on Windows) and running the tests (run.ps1 on Windows).
-You can either specify a list of flags to disable certain tests and avoid
-building/downloading some dependencies, or you can specify a custom
-[nextest filter](https://nexte.st/docs/filtersets/) and list of artifacts.
-In this case, all possible dependencies will be obtained since deriving them
-from a test filter is not yet supported.
+### Targeting a Platform
+
+By default, `vmm-tests-run` builds for the current host. Use `--target` to
+build for a different platform. The supported targets are:
+
+| Target | Description |
+|--------|-------------|
+| `windows-x64` | Windows x86_64 (Hyper-V / WHP) |
+| `windows-aarch64` | Windows ARM64 (Hyper-V / WHP) |
+| `linux-x64` | Linux x86_64 |
+
+**Cross-compiling for Windows from WSL2** is fully supported, you can build
+and run Windows VMM tests directly from your WSL2 shell. This requires the
+cross-compilation environment to be set up first.
+
+Then target Windows as usual. The output directory **must** be on the Windows
+filesystem (e.g., `/mnt/d/...`):
+
+```bash
+cargo xflowey vmm-tests-run --target windows-x64 --dir /mnt/d/vmm_tests
+```
+
+For full cross-compilation setup instructions, see
+[Cross Compiling for Windows](../getting_started/cross_compile.md).
+
+When running Hyper-V tests, your user account must be a member of the
+Hyper-V Administrators group.
+
+To see all available options: `cargo xflowey vmm-tests-run --help`.
 
 ## Running VMM Tests (Manual)
 
@@ -133,7 +153,7 @@ which provide detailed instructions on how to build / acquire the missing
 artifact. Some dependencies can only be built on Linux (OpenHCL and Linux
 pipette, for example). If you are building on Linux and want to run Windows
 guest tests, pipette will need to be
-[cross compiled for Windows](#linux-cross-compiling-pipetteexe). 
+[cross compiled for Windows](#linux-cross-compiling-pipetteexe).
 
 ```admonish warning
 `cargo nextest run` won't rebuild any of your changes. Make sure you `cargo build`

Guide/src/user_guide/openhcl/run/hyperv.md

@@ -76,7 +76,7 @@ Use the `-GuestStateIsolationType OpenHCL` parameter to `New-VM`. The following
 
 ```powershell
 # Names, directories, etc.
-# cargo xflowey will do some heavy lifting for you. You can run `cargo xflowey vmm-tests --build-only --dir /mnt/q/win-vmm-tests ...` from your WSL to get images, compiled OpenHCL, etc. See [cross-compile](../../../dev_guide/getting_started/cross_compile.md) and [vmm-test](../../../dev_guide/tests/vmm.md) docs for additional info.
+# cargo xflowey will do some heavy lifting for you. You can run `cargo xflowey vmm-tests-run --build-only --dir /mnt/q/win-vmm-tests ...` from your WSL to get images, compiled OpenHCL, etc. See [cross-compile](../../../dev_guide/getting_started/cross_compile.md) and [vmm-test](../../../dev_guide/tests/vmm.md) docs for additional info.
 $repoDir = "home\<your-wsl-username-for-example>\openvmm" # for prereqs below, the path relative to the root of your WSL file system where you have cloned the openvmm repo
 
 $VmName = "OpenHCLTestVM"
@@ -144,7 +144,7 @@ While these steps guide you to create a second SCSI controller, your generation
 
 ```powershell
 # Names, directories, etc.
-# cargo xflowey will do some heavy lifting for you. You can run `cargo xflowey vmm-tests --build-only --dir /mnt/q/win-vmm-tests ...` from your WSL to get images, compiled OpenHCL, etc. See [cross-compile](../../../dev_guide/getting_started/cross_compile.md) and [vmm-test](../../../dev_guide/tests/vmm.md) docs for additional info.
+# cargo xflowey will do some heavy lifting for you. You can run `cargo xflowey vmm-tests-run --build-only --dir /mnt/q/win-vmm-tests ...` from your WSL to get images, compiled OpenHCL, etc. See [cross-compile](../../../dev_guide/getting_started/cross_compile.md) and [vmm-test](../../../dev_guide/tests/vmm.md) docs for additional info.
 $repoDir = "home\<your-wsl-username-for-example>\openvmm" # for prereqs below, the path relative to the root of your WSL file system where you have cloned the openvmm repo
 
 $VmName = "OpenHCLTestVM"

Guide/src/user_guide/openvmm/run.md

@@ -60,7 +60,7 @@ If you ran `cargo xflowey restore-packages`, the firmware is at:
 .packages/hyperv.uefi.mscoreuefi.AARCH64.RELEASE/MsvmAARCH64/RELEASE_VS2022/FV/MSVM.fd # aarch64
 ```
 
-If you used `cargo xflowey vmm-tests --build-only --dir <out>`, the firmware
+If you used `cargo xflowey vmm-tests-run --build-only --dir <out>`, the firmware
 is copied into that output directory under the same relative path.
 
 Alternatively, set the environment variable so you don't need the flag each time:
@@ -154,11 +154,11 @@ This example will boot OpenHCL in Linux direct mode, running a minimal shell
 inside VTL2. This is the same configuration used by the `openhcl_linux_direct_x64`
 integration tests.
 
-First, build the test artifacts from Linux or WSL using `vmm-tests --build-only`.
+First, build the test artifacts from Linux or WSL using `vmm-tests-run --build-only`.
 The IGVM must be built on Linux:
 
 ```shell
-cargo xflowey vmm-tests --build-only --dir <out> --target windows-x64
+cargo xflowey vmm-tests-run --build-only --dir <out> --target windows-x64
 ```
 
 ```admonish tip

flowey/flowey_hvlite/Cargo.toml

@@ -18,6 +18,7 @@ anyhow.workspace = true
 clap = { workspace = true, features = ["derive"] }
 log.workspace = true
 serde = { workspace = true, features = ["std"] }
+serde_json.workspace = true
 target-lexicon = { workspace = true, features = ["serde_support"] }
 
 [lints]

flowey/flowey_hvlite/src/pipelines/mod.rs

@@ -3,15 +3,15 @@
 
 use flowey::pipeline::prelude::*;
 use restore_packages::RestorePackagesCli;
-use vmm_tests::VmmTestsCli;
+use vmm_tests_run::VmmTestsRunCli;
 
 pub mod build_docs;
 pub mod build_igvm;
 pub mod build_reproducible;
 pub mod checkin_gates;
 pub mod custom_vmfirmwareigvm_dll;
 pub mod restore_packages;
-pub mod vmm_tests;
+pub mod vmm_tests_run;
 
 #[derive(clap::Subcommand)]
 #[expect(clippy::large_enum_variant)]
@@ -34,8 +34,8 @@ pub enum OpenvmmPipelines {
     /// Install tools needed to build OpenVMM
     RestorePackages(RestorePackagesCli),
 
-    /// Build and run VMM tests
-    VmmTests(VmmTestsCli),
+    /// Build and run VMM tests with automatic artifact discovery
+    VmmTestsRun(VmmTestsRunCli),
 }
 
 #[derive(clap::Subcommand)]
@@ -63,7 +63,7 @@ impl IntoPipeline for OpenvmmPipelines {
                 OpenvmmPipelinesCi::BuildDocs(cmd) => cmd.into_pipeline(pipeline_hint),
             },
             OpenvmmPipelines::RestorePackages(cmd) => cmd.into_pipeline(pipeline_hint),
-            OpenvmmPipelines::VmmTests(cmd) => cmd.into_pipeline(pipeline_hint),
+            OpenvmmPipelines::VmmTestsRun(cmd) => cmd.into_pipeline(pipeline_hint),
         }
     }
 }