# ui-tests-local-vm

Adopt this skill: https://proskills.md/skills/other/microsoft-powertoys-github-skills-ui-tests-local-vm

Page: https://proskills.md/skills/other/microsoft-powertoys-github-skills-ui-tests-local-vm
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: .github/skills/ui-tests-local-vm/SKILL.md
size: 8001
upstream: https://github.com/microsoft/powertoys/blob/main/.github/skills/ui-tests-local-vm/SKILL.md

```text
---
name: ui-tests-local-vm
description: "Run PowerToys UITest.Next suites in persistent Hyper-V VMs over PowerShell Direct. Validate full default and constrained suites on Windows 10 and Windows 11, plus applicable ARM64 guests, then automatically hand implementation tasks to ui-tests-pipeline-ci for commit/push and CI validation. Local green is not end-to-end completion. Use for agentic UI-test iteration, reusable standard-user desktops, payload staging, evidence export, VM customization, clean baselines, or hosts without nested virtualization. Keywords: Hyper-V, local VM, virtual machine, PowerShell Direct, Copy-VMFile, VMBus, checkpoint, unattend, autounattend, ISO, Windows 10 LTSC, Windows 11, ARM64, Windows on ARM, UI tests, UITest.Next, winappcli, TRX, CI handoff."
license: MIT
---

# Local VM UI testing

Run PowerToys `.Next` UI tests in a persistent, interactive Windows VM while keeping product and test
execution off the host. Use this skill as the execution complement to
[ui-tests-migration](../ui-tests-migration/SKILL.md). Restore the baseline checkpoint or recreate the
guest when clean-profile behavior must be validated.

The guest is a Hyper-V virtual machine. Nothing runs nested, so the same scaffold works on x64 and on
Windows on ARM, where nested virtualization is unavailable to any Linux-hosted emulator.

The local correctness gate passes when the **full** suite is green on Windows 10 **and** on
Windows 11, in two separate VMs. Run Windows 10 Enterprise LTSC 2021 first for the fastest
feedback, then run the same unfiltered suite on Windows 11. Differences in the shell, compositor,
theming, and timing break tests that contain nothing Windows 11-specific, and those are exactly
the failures worth catching locally instead of in CI. On a Windows on ARM host, Windows 11 ARM64
is the only practical guest; run it with `-Platform ARM64` and get the Windows 10 half from an x64 host.

Start guests with the default resource profile: 4 vCPUs and 8 GB RAM. Get the target suite fully
green before lowering resources with the `Constrained` profile (1 vCPU and 4 GB RAM).

For **create, migrate, or stabilize** tasks, complete both profiles and then automatically invoke
[ui-tests-pipeline-ci](../ui-tests-pipeline-ci/SKILL.md): pass its access preflight, commit and push
the scoped changes, queue CI, and remain attached until terminal validation. **Do not mark the task
complete at local green or wait for another user request to publish/run CI.** Respect explicit
local-only/no-push/no-CI scope and the Microsoft FTE/access gates. Local execution or VM setup alone
does not authorize publication. See the pipeline skill for the shared completion and blocker rules.

## How the host reaches the guest

| Concern | Mechanism |
|---|---|
| Control channel | PowerShell Direct over VMBus. No listener, port, certificate, or firewall rule in the guest. |
| Bulk payload | `Copy-VMFile` over the Guest Service Interface, ~82 MB/s. The session copy is a fallback and stalls on archives near a gigabyte. |
| Exchange | Guest-local `C:\PowerToysUiTestExchange\<name>`, mirrored by the controller. The host never shares a folder with the guest. |
| Host privilege | Hyper-V access: an elevated shell, or an account in the local **Hyper-V Administrators** group. Creating a guest additionally requires real elevation. |
| Console | `scripts/Get-VmConsoleImage.ps1` renders the framebuffer to PNG, so an agent can read boot and desktop state without VMConnect. |

## When to use this skill

Use it when asked to:

- Create or migrate UI tests and iterate repeatedly without reprovisioning Windows each run.
- Validate Explorer, hotkey, WebView2, shell-extension, foreground, or composed-visual behavior in a
  real interactive desktop.
- Run tests as a true standard user while retaining a separate administrator control channel.
- Reuse unchanged PowerToys, winappcli, and .NET payloads and refresh only changed archives.
- Keep a reproducible local VM baseline with optional .NET 10, WebView2, diagnostics, or `msvsmon`.
- Collect durable `status.json`, TRX, transcripts, logs, screenshots, and failure attachments.
- Compare revisions in one stable VM before confirming the result from a restored checkpoint.

Do not treat a persistent VM as proof of clean-profile behavior. Caches, registrations, settings, and
first-run state survive between runs. Restore the baseline checkpoint or recreate the VM when those
are the behavior under test.

## Relationship to other UI-test skills

| Skill | Owns |
|---|---|
| `ui-tests-migration` | Test design, project scaffolding, framework APIs, assertions, lifecycle, and CI stability. |
| `ui-tests-local-vm` | Fast persistent-VM setup, deployment, interactive execution, evidence export, and iteration. |
| `ui-tests-pipeline-ci` | Required post-local commit/push, access preflight, scoped CI, and terminal sign-off for implementation tasks. |

Do not modify stabilized tests merely to make the local VM green. First prove that the suite executes,
produces assertion-bearing TRX, and has a useful success rate. Classify environment-specific failures
separately unless the task explicitly asks for stabilization.

## Guest OS policy

- Two guests, two full suites. Windows 10 Enterprise LTSC 2021 (build 19044/21H2, newer than the
  Windows 10 20H2 baseline) and Windows 11. Both must be fully green before the local gate passes.
  LTSC is not available through Fido; `-Source Fido -Windows 10` automates Microsoft's official
  mobile-user-agent ISO page and is the practical public default. The public ISO/MCT images are too
  old for .NET 10 CET, so Setup Dynamic Update must bring Win10 to 1904x.5007+ before the baseline.
  Use licensed Microsoft subscription media for LTSC when available, and always record the edition,
  ISO hash, and installed full build ([references/setup.md §3](references/setup.md#3-get-windows-media)).
- Windows 10 runs first: it is the faster loop and surfaces most defects. Windows 11 then runs the
  **same** suite, unfiltered - not only the tests that look Windows 11-specific. A test with no
  Windows 11 content can still fail there, which is the whole reason for the second pass.
- Narrow filters belong to iteration and diagnosis. They are never the evidence for the Windows 11
  pass.
- Give each OS its own VM name, `vm.config.psd1`, VHDX, checkpoints, and exchange. Never upgrade or
  repurpose the Windows 10 guest into the Windows 11 guest; the two baselines must stay independent.
- Surfaces that exist only on Windows 11, such as the tier-1 Explorer context menu, need no special
  handling: the full Windows 11 run already covers them.
- On a Windows on ARM host, use a Windows 11 ARM64 guest with `-Platform ARM64`. Hyper-V does not
  emulate a foreign architecture, so that host cannot supply the Windows 10 x64 pass - run it on an
  x64 host and report both.
- A Windows 11 host requirement does not make Windows 11 the first guest target.
- `-Platform` is not cosmetic: it flows to the guest as the `platform` environment variable, names
  visual baselines, and marks the run as pipeline-like. Use only `x64Win10`, `x64Win11`, or `ARM64`.

## Required reads

Read only what the task needs:

1. [references/setup.md](references/setup.md) - host requirements, scaffolding, media acquisition,
   unattended guest creation, credentials, standard-user desktop, and checkpoint baselines.
2. [references/agentic-loop.md](references/agentic-loop.md) - payload contract, controller usage,
   focused-to-suite iteration, evidence, verdicts, and reset strategy.
3. [references/customization.md](references/customization.md) - persistent image customization,
   .NET 10, WebView2, `msvsmon`, resource profiles, and golden-baseline guidance.
4. [references/troubleshooting.md](references/troubleshooting.md) - guest creation, PowerShell Direct,
   interactive session, scheduled-task, focus, timeout, and export failures.
5. [references/shell-extensions-and-signing.md](references/shell-extens
```

## File: README.md
upstream: https://github.com/microsoft/powertoys/blob/main/README.md

````text
<p align="center">
    <picture>
      <source media="(prefers-color-scheme: light)" srcset="./doc/images/readme/pt-hero.light.png" />
      <img src="./doc/images/readme/pt-hero.dark.png" />
  </picture>
</p>
<h1 align="center">
  <span>Microsoft PowerToys</span>
</h1>
<p align="center">
  <span align="center">Microsoft PowerToys is a collection of utilities that help you customize Windows and streamline everyday tasks.</span>
</p>
<h3 align="center">
  <a href="#-installation">Installation</a>
  <span> · </span>
  <a href="https://aka.ms/powertoys-docs">Documentation</a>
  <span> · </span>
  <a href="https://aka.ms/powertoys-releaseblog">Blog</a>
  <span> · </span>
  <a href="#-whats-new">Release notes</a>
</h3>

## 🔨 Utilities

PowerToys includes over 30 utilities to help you customize and optimize your Windows experience:

|   |   |   |
| --- | --- | --- |
| [<img src="doc/images/icons/AdvancedPaste.png" alt="Advanced Paste icon" height="16"> Advanced Paste](https://aka.ms/PowerToysOverview_AdvancedPaste) | [<img src="doc/images/icons/Always%20On%20Top.png" alt="Always on Top icon" height="16"> Always on Top](https://aka.ms/PowerToysOverview_AoT) | [<img src="doc/images/icons/Awake.png" alt="Awake icon" height="16"> Awake](https://aka.ms/PowerToysOverview_Awake) |
| [<img src="doc/images/icons/Color%20Picker.png" alt="Color Picker icon" height="16"> Color Picker](https://aka.ms/PowerToysOverview_ColorPicker) | [<img src="doc/images/icons/Command%20Not%20Found.png" alt="Command Not Found icon" height="16"> Command Not Found](https://aka.ms/PowerToysOverview_CmdNotFound) | [<img src="doc/images/icons/Command Palette.png" alt="Command Palette icon" height="16"> Command Palette](https://aka.ms/PowerToysOverview_CmdPal) |
| [<img src="doc/images/icons/Crop%20And%20Lock.png" alt="Crop and Lock icon" height="16"> Crop And Lock](https://aka.ms/PowerToysOverview_CropAndLock) | [<img src="doc/images/icons/Environment%20Manager.png" alt="Environment Variables icon" height="16"> Environment Variables](https://aka.ms/PowerToysOverview_EnvironmentVariables) | [<img src="doc/images/icons/FancyZones.png" alt="FancyZones icon" height="16"> FancyZones](https://aka.ms/PowerToysOverview_FancyZones) |
| [<img src="doc/images/icons/File%20Explorer%20Preview.png" alt="File Explorer Add-ons icon" height="16"> File Explorer Add-ons](https://aka.ms/PowerToysOverview_FileExplorerAddOns) | [<img src="doc/images/icons/File%20Locksmith.png" alt="File Locksmith icon" height="16"> File Locksmith](https://aka.ms/PowerToysOverview_FileLocksmith) | [<img src="doc/images/icons/GrabAndMove.png" alt="Grab And Move icon" height="16"> Grab And Move](https://aka.ms/PowerToysOverview_GrabAndMove) |
| [<img src="doc/images/icons/Host%20File%20Editor.png" alt="Hosts File Editor icon" height="16"> Hosts File Editor](https://aka.ms/PowerToysOverview_HostsFileEditor) | [<img src="doc/images/icons/Image%20Resizer.png" alt="Image Resizer icon" height="16"> Image Resizer](https://aka.ms/PowerToysOverview_ImageResizer) | [<img src="doc/images/icons/Keyboard%20Manager.png" alt="Keyboard Manager icon" height="16"> Keyboard Manager](https://aka.ms/PowerToysOverview_KeyboardManager) |
| [<img src="doc/images/icons/Light Switch.png" alt="Light Switch icon" height="16"> Light Switch](https://aka.ms/PowerToysOverview_LightSwitch) | [<img src="doc/images/icons/Find My Mouse.png" alt="Mouse Utilities icon" height="16"> Mouse Utilities](https://aka.ms/PowerToysOverview_MouseUtilities) | [<img src="doc/images/icons/MouseWithoutBorders.png" alt="Mouse Without Borders icon" height="16"> Mouse Without Borders](https://aka.ms/PowerToysOverview_MouseWithoutBorders) |
| [<img src="doc/images/icons/NewPlus.png" alt="New+ icon" height="16"> New+](https://aka.ms/PowerToysOverview_NewPlus) | [<img src="doc/images/icons/Peek.png" alt="Peek icon" height="16"> Peek](https://aka.ms/PowerToysOverview_Peek) | [<img src="doc/images/icons/PowerDisplay.png" alt="PowerDisplay icon" height="16"> PowerDisplay](https://aka.ms/PowerToysOverview_PowerDisplay) |
| [<img src="doc/images/icons/PowerRename.png" alt="PowerRename icon" height="16"> PowerRename](https://aka.ms/PowerToysOverview_PowerRename) | [<img src="doc/images/icons/PowerToys%20Run.png" alt="PowerToys Run icon" height="16"> PowerToys Run](https://aka.ms/PowerToysOverview_PowerToysRun) | [<img src="doc/images/icons/PowerAccent.png" alt="Quick Accent icon" height="16"> Quick Accent](https://aka.ms/PowerToysOverview_QuickAccent) |
| [<img src="doc/images/icons/Registry%20Preview.png" alt="Registry Preview icon" height="16"> Registry Preview](https://aka.ms/PowerToysOverview_RegistryPreview) | [<img src="doc/images/icons/MeasureTool.png" alt="Screen Ruler icon" height="16"> Screen Ruler](https://aka.ms/PowerToysOverview_ScreenRuler) | [<img src="doc/images/icons/Shortcut%20Guide.png" alt="Shortcut Guide icon" height="16"> Shortcut Guide](https://aka.ms/PowerToysOverview_ShortcutGuide) |
| [<img src="doc/images/icons/PowerOCR.png" alt="Text Extractor icon" height="16"> Text Extractor](https://aka.ms/PowerToysOverview_TextExtractor) | [<img src="doc/images/icons/WindowHopper.png" alt="Window Hopper icon" height="16"> Window Hopper](https://aka.ms/PowerToysOverview_WindowHopper) | [<img src="doc/images/icons/Workspaces.png" alt="Workspaces icon" height="16"> Workspaces](https://aka.ms/PowerToysOverview_Workspaces) |
| [<img src="doc/images/icons/ZoomIt.png" alt="ZoomIt icon" height="16"> ZoomIt](https://aka.ms/PowerToysOverview_ZoomIt) |   |   |

## 📦 Installation

For detailed installation instructions and system requirements, visit the [installation docs](https://learn.microsoft.com/windows/powertoys/install).

But to get started quickly, choose one of the installation methods below:
<br/><br/>
<details open>
<summary><strong>Download the .exe file from GitHub</strong></summary>
<br/>

Go to the [PowerToys GitHub releases](https://aka.ms/installPowerToys), scroll down and select **Assets** to reveal the installation files, and choose the one that matches your architecture and install scope. For most devices, that would be _x64 per-user_.

</details>

<details>
<summary><strong>Microsoft Store</strong></summary>
<br/>
You can easily install PowerToys from the Microsoft Store:
<p>
  <a style="text-decoration:none" href="https://aka.ms/getPowertoys">
    <picture>
      <source media="(prefers-color-scheme: light)" srcset="doc/images/readme/StoreBadge-dark.png" width="148" />
      <img src="doc/images/readme/StoreBadge-light.png" width="148" />
  </picture></a>
</p>
</details>

<details>
<summary><strong>WinGet</strong></summary>
<br/>
Download PowerToys from [WinGet](https://github.com/microsoft/winget-cli#installing-the-client). Updating PowerToys via winget will respect the current PowerToys installation scope. To install PowerToys, run the following command from the command line / PowerShell:

- User scope installer (default)

```powershell
winget install Microsoft.PowerToys -s winget
```

- Machine-wide scope installer

```powershell
winget install --scope machine Microsoft.PowerToys -s winget
```
</details>

<details>
<summary><strong>Other methods</strong></summary>
<br/>
There are [community driven install methods](https://learn.microsoft.com/windows/powertoys/install#community-driven-install-tools) such as Chocolatey and Scoop. If these are your preferred install solutions, you can find the install instructions there.
</details>

## ✨ What's new?

[![What's new image](doc/images/readme/Release-Banner.png)](https://github.com/microsoft/PowerToys/releases)

To see what's new, check out the [release notes](https://github.com/microsoft/PowerToys/releases/).

## 🛣️ Roadmap

For [v0.103][github-next-release-work], we're working on a new Awake flyout, improving Screen Ruler, and continuing to modernize more utilities with WinUI 3.

## ❤️ PowerToys Community

The PowerToys team is extremely grateful to have the [support of an amazing active community][community-link]. The
````
