test-on-vm
EXPERIMENTAL. Run locally built WinUI interaction tests on a Hyper-V VM through PowerShell Direct. Use when asked to run WinUI tests on a local VM.
- License 许可
- MIT
- 最近更新
- 2026-11-14
- Stars
- ★ 8.6k
- Forks
- 965
01 前言 Front Matter
- name
- test-on-vm
- description
- EXPERIMENTAL. Run locally built WinUI interaction tests on a Hyper-V VM through PowerShell Direct. Use when asked to run WinUI tests on a local VM.
03 SKILL.md 正文
Run WinUI Tests on a Hyper-V VM
Run tools\run-tests-on-vm.ps1 through initrun.ps1. It refreshes the local
test payload, deploys it to the VM, performs required machine setup, and runs
tests on the VM's interactive desktop.
This skill and script are experimental and may not be stable.
Before You Run
Build the repository first. Follow the build skill:
.\initrun.ps1 .\build.cmd /q
Also verify:
- The VM is running with an unlocked desktop and a logged-in user.
- The caller is a local admin or a member of Hyper-V Administrators.
- The command uses
initial_waitof at least 180 seconds.
If Hyper-V permissions are missing, stop and ask the user to make the change
themselves. Never run Add-LocalGroupMember or open an elevated shell on their
behalf, even with their approval.
Tell the user to run whoami in their original, non-elevated PowerShell window
and copy the account name. Then have them open a separate PowerShell (pwsh)
window using Run as administrator and run this command, replacing
<account-from-whoami> with the copied name:
Add-LocalGroupMember -Group 'Hyper-V Administrators' -Member '<account-from-whoami>'
Tell the user to sign out and back in afterward. Wait for them to confirm they have completed these steps before retrying the test.
The first run prompts for VM credentials in a separate window and caches them
encrypted under ~\.winui-test. Use -ResetCredential to replace them.
Run Tests
# Run a specific test
.\initrun.ps1 .\tools\run-tests-on-vm.ps1 -VMName <vm> <testname>
# Wildcard match
.\initrun.ps1 .\tools\run-tests-on-vm.ps1 -VMName <vm> *CommandBar*
# Force full copy instead of incremental
.\initrun.ps1 .\tools\run-tests-on-vm.ps1 -VMName <vm> -FullCopy <testname>
# Stop a stuck test run
.\initrun.ps1 .\tools\run-tests-on-vm.ps1 -VMName <vm> -Stop
Payload Rules
By default, the script runs test\CreateTestPayload.ps1 to refresh
TestPayload\<flavor> from the current build outputs, then deploys changed
files incrementally.
-FullCopystill refreshes the local payload, then copies all of it to the VM.- Use
-SkipPayloadrarely. It deploys the existing local payload without refreshing it. Use it only when that payload is known to be current or when intentionally testing stale binaries. Never use it merely to save time.
Useful Options
| Option | Purpose |
|---|---|
-Platform |
x86, x64, or arm64; uses $env:BUILDPLATFORM, then defaults to x64 |
-Configuration |
chk or fre; uses $env:_BuildType, then defaults to chk |
-FullCopy |
Copy the full refreshed payload instead of only changes |
-SkipPayload |
Rare: deploy the existing payload without refreshing it |
-SkipPrerun |
Skip testmachine-prerun.cmd |
-ForcePrerun |
Run testmachine-prerun.cmd again |
-Credential |
Supply a PSCredential instead of using the prompt/cache |
-ResetCredential |
Clear the cached credential for this VM |
-Stop |
Stop the active test and clean up |
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
Could not launch app, foreground-window errors, or an empty UIA tree |
VM desktop is locked or not visible | Keep the VM desktop unlocked and active |
Failed to connect to VM |
VM not running or wrong credentials | Start the VM; use -ResetCredential to re-enter credentials |
| Permission error | Need Hyper-V Administrators membership | Stop and have the user follow the permission steps above |
| Incomplete payload or prerun failure | Stale payload or partial deployment | Omit -SkipPayload; retry with -FullCopy if needed |
Crash Dumps
The first prerun configures full crash dumps under C:\dumps on the VM, with
up to three dumps per process. Pull one back through PowerShell Direct:
$vmName = "<vm>"
$credentialKey = $vmName -replace '[^a-zA-Z0-9]', '_'
$cred = Import-Clixml "~\.winui-test\vmcred-$credentialKey.xml"
$destination = Join-Path $env:TEMP "WinUIDumps"
New-Item -ItemType Directory -Path $destination -Force | Out-Null
$session = New-PSSession -VMName $vmName -Credential $cred
try {
Invoke-Command -Session $session { Get-ChildItem C:\dumps\*.dmp }
Copy-Item -FromSession $session -Path "C:\dumps\<dump>.dmp" -Destination $destination
}
finally {
Remove-PSSession $session
}
Always access ".winui-test" via "~.winui-test", without changing the "~" to some other form.
For a quick local analysis:
cdb -z "$env:TEMP\WinUIDumps\<dump>.dmp" -c "!analyze -v; ~*k; q"
04 同仓库更多 Skills
analyze-session
Opens a WinUI Profiler session file (.sqlite) and answers questions about a WinUI 3 app's performance from it with the winui-profiler tools: how the launch went, UI-thread ticks and slow ticks, regions of interest (navigations, flyouts and dialogs opening, focus changes), and the UI elements and composition visuals the events mention. Use it when someone asks why a WinUI app is slow to start or draws slowly, what a tick did, what happened around a navigation or to an element, or what a session holds, and for /winui-profiler:analyze-session [session.sqlite | folder].
test-suite-setup
Complete end-to-end setup and execution of the WinUI3 test suite locally. Delegates building to the build skill, then handles test payload creation, machine setup, and running all tests.
bt-build
Fast incremental C++/MSBuild builds using bt. Use when the user wants to compile, build, check what's dirty, or query build dependencies in a repo that has .vcxproj files. Prefer bt over invoking MSBuild directly for inner-loop source changes (.cpp, .h, .idl, .xaml, .appxmanifest).
code-review
Review changes in microsoft/microsoft-ui-xaml. Use when reviewing code or pull requests in this repository.
code-coverage-calculation
EXPERIMENTAL. Calculate code coverage of a WinUI control or component (for example "calculate coverage of control TitleBar") by running only that component's tests on a local Hyper-V VM against the local build. Supports controls in Microsoft.UI.Xaml.Controls.dll and Microsoft.UI.Xaml.Controls.Tabular.dll, and dxaml types in Microsoft.ui.xaml.dll. Reports per-file and per-function line coverage that matches the ADO Code Coverage tab. Use for "calculate/measure/get coverage of <control>", "how much do <control>'s tests cover", or "coverage before/after my tests" when you have a local build and a VM.