microsoft/openvmm

Public

mirrored from https://github.com/microsoft/openvmmAvailable

Watch0 Fork0 Star0

Code Commits Issues Pull requests Actions Insights Security

9a4e9aa40a5fd024b2cafb6e4fbc2fab9f8b583b

Find a branch or tag

Branches

9a4e9aa40a5fd024b2cafb6e4fbc2fab9f8b583b

Clone

HTTPS

Download ZIP

openvmm/Guide/src/dev_guide/tests

Guide/src/dev_guide/tests/vmm.md

165lines · modecode

Raw Download

Latest commit unavailable.

unknown

1	`# VMM Tests`
2
3	`The OpenVMM repo contains a set of "heavyweight" VMM tests that fully boot a`
4	`virtual machine and run validation against it. Unlike Unit tests, these are all`
5	centralized in a single top-level `vmm_tests` directory.
6
7	`The OpenVMM PR and CI pipelines will run the full test suite on all supported`
8	`platforms; you'd typically run only the tests relevant to the changes you're`
9	`working on.`
10
11	`## Running VMM Tests (Flowey)`
12
13	`The easiest way to run the VMM tests locally is using the`
14	`cargo xflowey vmm-tests` command. To see the most up-to-date options, run:
15	`cargo xflowey vmm-tests --help`. When running Hyper-V tests, you will need
16	`to use an administrator terminal window (this works even if you are running`
17	`from WSL2). When running Windows tests, the output dir should be on the`
18	`Windows file system. For example, from WSL2:`
19
20	```bash
21	`cargo xflowey vmm-tests --target windows-x64 --dir /mnt/e/vmm_tests`
22	```
23
24	`This command will build or download all the test dependencies and copy them`
25	`to a self-contained folder that can be copied to another system for testing.`
26	`The folder will contain scripts for installing dependencies`
27	`(install_deps.ps1 on Windows) and running the tests (run.ps1 on Windows).`
28	`You can either specify a list of flags to disable certain tests and avoid`
29	`building/downloading some dependencies, or you can specify a custom`
30	`[nextest filter](https://nexte.st/docs/filtersets/) and list of artifacts.`
31	`In this case, all possible dependencies will be obtained since deriving them`
32	`from a test filter is not yet supported.`
33
34	`## Running VMM Tests (Manual)`
35
36	```admonish tip
37	`Note: We recommend using [cargo-nextest](https://nexte.st/) to run unit / VMM`
38	tests. It is a significant improvement over the built-in `cargo test` runner,
39	`and is the test runner we use in all our CI pipelines.`
40
41	You can install it locally by running: `cargo install cargo-nextest --locked`
42
43	`See the [cargo-nextest](https://nexte.st/) documentation for more info.`
44	```
45
46	You can directly invoke `cargo test` or `cargo nextest` to run the vmm
47	`tests manually.`
48
49	`Unlike Unit Tests, VMM tests may rely on additional external artifacts in order`
50	`to run. e.g: Virtual Disk Images, pre-built OpenHCL binaries, UEFI / PCAT`
51	`firmware blobs, etc.`
52
53	`As such, the first step in running a VMM test is to ensure you have acquired all`
54	`external test artifacts it may depend upon.`
55
56	`The VMM test infrastructure does not automatically fetch / rebuild`
57	`necessary artifacts unless you are using [flowey](#running-vmm-tests-flowey).`
58	`However, the test infrastructure is designed to report clear`
59	`and actionable error messages whenever a required test artifact cannot be found,`
60	`which provide detailed instructions on how to build / acquire the missing`
61	`artifact. Some dependencies can only be built on Linux (OpenHCL and Linux`
62	`pipette, for example). If you are building on Linux and want to run Windows`
63	`guest tests, pipette will need to be`
64	`[cross compiled for Windows](#linux-cross-compiling-pipetteexe).`
65
66	```admonish warning
67	`cargo nextest run` won't rebuild any of your changes. Make sure you `cargo build`
68	or `cargo xflowey igvm [RECIPE]` first!
69	```
70
71	`VMM tests are run using standard Rust test infrastructure, and are invoked via`
72	`cargo test` / `cargo nextest`.
73
74	```bash
75	`cargo nextest run -p vmm_tests [TEST_FILTERS]`
76	```
77
78	`For example, to run a simple VMM test that simply boots using UEFI:`
79
80	```bash
81	`cargo nextest run -p vmm_tests multiarch::openvmm_uefi_x64_frontpage`
82	```
83
84	`And, for further example, to rebuild everything* and run all* the tests`
85	`(see below for details on these steps):`
86
87	`*This will not work for Hyper-V tests. TMK tests need additional build steps.`
88
89	```bash
90	`# Install (most) of the dependencies; cargo nextest run may tell you`
91	`# about other deps.`
92	`rustup target add x86_64-unknown-none`
93	`rustup target add x86_64-unknown-uefi`
94	`rustup target add x86_64-pc-windows-msvc`
95	`sudo apt install clang-tools-14 lld-14`
96
97	`cargo install cargo-nextest --locked`
98
99	`cargo xtask guest-test download-image`
100	`cargo xtask guest-test uefi --bootx64`
101
102	`# Rebuild all, and run all tests`
103	`cargo build --target x86_64-pc-windows-msvc -p pipette`
104	`cargo build --target x86_64-unknown-linux-musl -p pipette`
105
106	`cargo build --target x86_64-pc-windows-msvc -p openvmm`
107
108	`cargo xflowey build-igvm x64-test-linux-direct`
109	`cargo xflowey build-igvm x64-cvm`
110	`cargo xflowey build-igvm x64`
111
112	`cargo nextest run --target x86_64-pc-windows-msvc -p vmm_tests --filter-expr 'all() & !test(hyperv) & !test(tmk)'`
113	```
114
115	### \[Linux] Cross-compiling `pipette.exe`
116
117	These commands might use the test agent (`pipette`) that is put inside the VM,
118	`and if the host machine OS and the guest machine OS are different, a setup`
119	`is required for cross-building. The recommended approach is to use WSL2 and`
120	`cross-compile using the freely available Microsoft Visual Studio Build Tools`
121	`or Microsoft Visual Studio Community Edition as described in`
122	`[\[WSL2\] Cross Compiling from WSL2 to Windows](../getting_started/cross_compile.md)`
123
124	`If that is not possible, here is another option that relies on [MinGW-w64](https://www.mingw-w64.org/)`
125	`and doesn't require installing Windows:`
126
127	```bash
128	`# Do 1 once, do 2 as needed.`
129	`#`
130	`# 1. Setup the toolchain`
131	`rustup target add x86_64-pc-windows-gnu`
132	`sudo apt-get install mingw-w64-x86-64-dev`
133	`mingw-genlib -a x86_64 ./support/pal/api-ms-win-security-base-private-l1-1-1.def`
134	`sudo mv libapi-ms-win-security-base-private-l1-1-1.a /usr/x86_64-w64-mingw32/lib`
135
136	`# 2. Build Pipette (builds target/x86_64-pc-windows-gnu/debug/pipette.exe first)`
137	`cargo build --target x86_64-pc-windows-gnu -p pipette`
138	```
139
140	```bash
141	`# Run a test`
142	`cargo nextest run -p vmm_tests multiarch::openvmm_uefi_x64_windows_datacenter_core_2022_x64_boot`
143	```
144
145	`### Printing logs for VMM Tests`
146
147	`In order to see the OpenVMM logs while running a VMM test, do the following:`
148	1. Add the `--no-capture` flag to your `cargo nextest` command.
149	2. Set `OPENVMM_LOG=trace`, replacing `trace` with the log level you want to view.
150
151	`## Writing VMM Tests`
152
153	`To streamline the process of booting and interacting VMs during VMM tests, the`
154	OpenVMM project uses a in-house test framework/library called `petri`.
155
156	`The library does not yet have a stable API, so at this time, the best way to`
157	`learn how to write new VMM tests is by reading through the existing corpus of`
158	`tests (start with vmm_tests/vmm_tests/tests/tests/multiarch.rs),`
159	as well as reading through `petri`'s rustdoc-generated API docs.
160
161	The tests are currently generated using a macro (`#[vmm_test]`) that allows
162	`the same test body to be run in a variety of scenarios, with different guest`
163	`operating systems, firmwares, and VMMs (including Hyper-V, which is useful`
164	`for testing certain OpenHCL features that aren't supported when using`
165	`OpenVMM as the host VMM).`
166

microsoft/openvmm

Branches

Tags

Clone