PowerToys/.github/skills/ui-tests-local-vm/references/shell-extensions-and-signing.md

Shell extensions & the CI signing constraint

Read this before writing or verifying UI tests for any module with a shell extension (context menu, preview handler, thumbnail provider, drag-drop handler). It is the knowledge that is not obvious from the test framework and caused the most trial-and-error.

The one fact that matters most

CI PR-validation builds are UNSIGNED (codeSign:false). Any test that depends on a sparse-MSIX-packaged shell extension gets 0% on CI, because the package cannot register (0x800B0100 TRUST_E_NOSIGNATURE). A test that passes on your machine (where you self-signed or installed a signed build) can therefore fail 100% on CI.

Preferred fix: sign the MSIX on CI and force-trust it

The workarounds below (driving the classic menu, launching the exe directly) let a test pass on an unsigned build, but they do not exercise the modern Win11 tier-1 context menu — the surface real users see. The faithful fix is to give CI a genuinely signed package plus a test-only trusted root, so registration succeeds and the tests drive the real end-user workflow. This is legitimate because the trust anchor is scoped to the test agent and asserts no security — it just makes Windows treat the CI-built package as sideload-installable, exactly like a developer self-signing locally.

Why signing (not Developer Mode) is required. PowerToys registers each sparse package at module-enable time with PackageManager.AddPackageByUriAsync (src/common/utils/package.h RegisterSparsePackage) — a packaged deployment that demands a signature chaining to a trusted root. Developer Mode / register-by-loose-manifest would only help if the product code called AddPackage -Register AppxManifest.xml, which it does not. So the only route is: sign the .msix and trust the signer.

Mechanism (all three steps must happen before the module is enabled):

1. Create a self-signed code-signing cert whose subject exactly equals the manifest Publisher — every PowerToys context-menu package and the CmdPal PowerToysSparse.msix use CN=Microsoft Corporation, O=Microsoft Corporation, L=Redmond, S=Washington, C=US. The private key is generated on the agent and never leaves it; nothing is committed.
2. Force-trust it via the machine stores: import the public cert into LocalMachine\Root and LocalMachine\TrustedPeople (a self-signed leaf is its own root, and AppX sideload consults TrustedPeople). These import silently, and the CI test agent is elevated (it installs machine-level), so it can write them. Do not import into CurrentUser\Root — the user Root store raises a CryptoAPI consent dialog that fails non-interactively (UI is not allowed in this operation), even when elevated. CurrentUser\TrustedPeople is silent and fine as an extra for per-user deployment; a non-elevated run that cannot write LocalMachine\Root cannot establish machine root trust silently.
3. signtool sign /fd SHA256 every sparse .msix the product will register.

A ready-to-use, publisher-aware implementation ships with this skill: .pipelines/signSparsePackages.ps1. It reads each package's manifest publisher, mints/reuses+trusts a matching cert, and signs only packages that are not already validly signed (so real framework packages like VCLibs are left alone). Point it at whichever tree hosts the packages:

# buildNow (run-in-place) — sign the packages in the downloaded build tree:
.\.pipelines\signSparsePackages.ps1 -PackageRoot "$(Pipeline.Workspace)\$(TestArtifactsName)"

# installed (buildNowSlim / official) — sign after install, before the test enables the module.
# Machine install lands in %ProgramFiles%\PowerToys; per-user install in %LOCALAPPDATA%\PowerToys:
.\.pipelines\signSparsePackages.ps1 `
  -PackageRoot "$env:ProgramFiles\PowerToys","$env:LOCALAPPDATA\PowerToys" `
  -RequiredPackage 'ImageResizerContextMenuPackage.msix'

# local UI-test VM sideload — sign the deployed runtime:
.\.pipelines\signSparsePackages.ps1 -PackageRoot "C:\PowerToysUiTestRun\PowerToys"

Where it is wired in CI. This runs in .pipelines/v2/templates/job-test-project.yml after the download/install steps and before Run UI Tests. It recursively searches the run-in-place artifact and complete machine/per-user install roots. Windows 11/ARM64 Image Resizer and all-module jobs pass -RequiredPackage ImageResizerContextMenuPackage.msix, so missing, unsigned, or untrusted setup fails at the prerequisite instead of surfacing later as a product-test failure. Jobs that do not exercise Image Resizer keep signing best-effort because their suites can guard unavailable modern packages:

  - pwsh: |
      $roots = @(
        "$(Pipeline.Workspace)\$(TestArtifactsName)",
        "$env:ProgramFiles\PowerToys",
        "$env:LOCALAPPDATA\PowerToys")
      if ($requiresImageResizer) {
        & "$(build.sourcesdirectory)\.pipelines\signSparsePackages.ps1" `
          -PackageRoot $roots -RequiredPackage 'ImageResizerContextMenuPackage.msix'
      } else {
        try { & "$(build.sourcesdirectory)\.pipelines\signSparsePackages.ps1" -PackageRoot $roots }
        catch { Write-Host "##vso[task.logissue type=warning]Sparse MSIX signing skipped: $($_.Exception.Message)" }
      }
    displayName: "Sign sparse MSIX packages (test trust)"

Prerequisite: signtool.exe. The script finds it across PATH, any Windows Kits install (all versions, plus the App Certification Kit), and a restored SDK BuildTools NuGet package; as a last resort it fetches the public Microsoft.Windows.SDK.BuildTools package from nuget.org, so an agent without the SDK still works given outbound access. Verified end-to-end in a local Win11 VM — the unsigned package fails Add-AppxPackage / AddPackageByUriAsync with 0x800B0100, and after signSparsePackages.ps1 signs it and the cert is force-trusted (LocalMachine\Root + TrustedPeople) the same registration succeeds and the package appears in Get-AppxPackage.

Caveat — CmdPal at install time. The installer's custom action stages/registers PowerToysSparse.msix during install (installer/PowerToysSetupCustomActionsVNext/CustomAction.cpp), before any test-time signing step runs. Signing after install still covers every module that registers at enable time (ImageResizer / PowerRename / FileLocksmith / NewPlus). If CmdPal's own packaged registration is the thing under test on an installed build, the package must instead be signed at build time (self-sign in the build stage and publish the public .cer for the test stage to trust) — the run-in-place buildNow path avoids this because nothing registers until the test enables it.

With this in place a test can drive the modern surface directly on CI. ModernRegistered() (below) becomes a portability guard for unsigned environments rather than a reason to avoid the modern menu.

Two shell-extension tiers

Tier	Mechanism	Signing	Unsigned CI PR build
Modern (Win11 tier-1 context menu, IExplorerCommand)	sparse MSIX package	required	❌ cannot register
Classic ("Show more options", Win10 default menu, most preview/thumbnail handlers)	registry COM (HKCU\Software\Classes\...\SystemFileAssociations\<ext>\ShellEx\...)	none	✅ works

Rule: you have two options on an unsigned CI build. (A, preferred) sign the modern package and force-trust it (see Preferred fix above) so the test drives the real Win11 tier-1 menu. (B, fallback) drive the signing-free surface — the classic COM menu, or launch the module exe directly with the files (the PowerRename pattern; the exe often has a CLI/FilesArgument). If you take the fallback, only assert the modern/tier-1 surface when the package is actually registered, so it runs on signed/official/installed builds only:

private static bool ModernRegistered() =>
    new Windows.Management.Deployment.PackageManager()
        .FindPackagesForUser(string.Empty)
        .Any(p => p.Id.Name.Contains("<PackageName>", StringComparison.OrdinalIgnoreCase));

Then: OpenContextMenu(useClassicMenu: !ModernRegistered()), and gate modern assertions behind if (ModernRegistered()).

Debug vs Release — why local != CI

• The classic registry-COM handler is usually gated #if defined(ENABLE_REGISTRATION) || defined(NDEBUG), so it is compiled out of local Debug builds and present only in CI Release (NDEBUG). To exercise the classic menu against a local Debug runtime, rebuild the extension DLL with ENABLE_REGISTRATION added to its <PreprocessorDefinitions>.
• The sparse .msix in build output is unsigned; registering it locally needs a self-signed cert whose subject == the package Publisher and that cert trusted (admin). CI does neither.
• Both handlers typically self-gate on the module's enabled flag at query time (classic QueryContextMenu returns E_FAIL, modern GetState returns ECS_HIDDEN), so the entry tracks the Settings toggle without re-registration.
• Modules register handlers at enable time (runtime), and an already-running Explorer will not surface a freshly-registered handler until the shell restarts — restart explorer.exe once after enabling (see PreviewPane / File Explorer add-ons tests).

Reproduce CI's classic scenario on a local (signed) VM

1. Rebuild the extension DLL with ENABLE_REGISTRATION and deploy it into the guest runtime (C:\PowerToysUiTestRun\PowerToys\WinUI3Apps\).
2. Neutralize the sparse package so enable() cannot register it: rename its .msix and Get-AppxPackage *<Package>* | Remove-AppxPackage -AllUsers. This mirrors CI's unsigned failure.
3. The ModernRegistered() detection now returns false → the tests drive the classic menu exactly as CI does. Use Invoke-GuestScript.ps1 for the guest-side steps.

Slow-agent / cross-arch robustness

Shell-extension tests are especially prone to slow-agent and ARM64-only races that you often cannot reproduce on a local VM (even constrained to 1 core, see customization.md — you cannot emulate ARM64 on an x64 host, so reason from the failure video/screenshot). The robustness patterns — re-select before every attempt, retryable transient popups, verify fixtures reached disk, and slow-path timeouts — are test design and live with the rest of the Explorer/shell test guidance in ui-tests-migration explorer-shell-tests.md.