AGENT SKILL

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

  • -FullCopy still refreshes the local payload, then copies all of it to the VM.
  • Use -SkipPayload rarely. 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

microsoft
microsoft/microsoft-ui-xaml

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

★ 8.6k
microsoft
microsoft/microsoft-ui-xaml

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.

测试与质量Skill与智能体开发
★ 8.6k
microsoft
microsoft/microsoft-ui-xaml

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

★ 8.6k
microsoft
microsoft/microsoft-ui-xaml

code-review

Review changes in microsoft/microsoft-ui-xaml. Use when reviewing code or pull requests in this repository.

开发工程师代码审查
★ 8.6k
microsoft
microsoft/microsoft-ui-xaml

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.

开发工程师Skill与智能体开发
★ 8.6k