Add scoped typed targeting to explicit UI invoke

[Nikola Metulev (nmetulev)]

Description

Allow winapp ui invoke --action to reuse the UI read-query filters (--root, --type, --class-name). A filtered explicit action must match exactly one element in the requested app or window; it confirms the same live UIA provider inside the coordinated desktop turn before acting, without switching to a replacement, another window, or an invokable ancestor. Supplying filters without --action is rejected, leaving automatic invoke unchanged.

Usage Example

winapp ui invoke Open --type Button -w <dialog-HWND> --action invoke

Zero matches, ambiguous matches, stale elements and invalid filters fail without acting. Use winapp ui inspect -w <dialog-HWND> to find a current selector or narrow the query.

Related Issue

N/A

Type of Change

• ✨ New feature
• 📝 Documentation
• 🧪 Test update

Checklist

• New tests added for new functionality
• Tested locally on Windows (nonactivating live UIA fixture)
• docs/usage.md updated
• Shipped UI automation skill updated

Screenshots / Demo

The example above is an illustrative CLI interaction; this change has no visual UI. No recording was captured because the Sandbox target could not be prepared.

Additional Notes

Focused CLI tests: 147 passed; focused UIAutomation tests: 116 passed. Debug solution build passed with zero warnings/errors. The repository build completed with -SkipTests (full packaging/docs before integrating the latest base), and -SkipAll republished both architectures after integrating main. Plugin and CLI schema validations passed. The full test run is not green locally: the initial run hit inaccessible api.nuget.org; a session-scoped mirror let 311 Node tests pass, but an unrelated GuestProcessHostTests.WaitForExit_AwaitsOutputDeliveryBeforeReadingMore timed out. CI is pending; this draft does not assert readiness.

Sandbox smoke testing was attempted twice with the published CLI. Target provisioning failed on the host's Sandbox share operation with E_ACCESSDENIED (sandbox_start_failed), so no guest interaction or host UI timing substitution was performed. A useful tooling improvement would be to distinguish a running-but-unattached Sandbox that cannot share from an ordinary startup failure and suggest actionable recovery beyond a generic retry/restart. No performance improvement is claimed.

AI Description

This section is auto-generated by AI when the PR is opened or updated. To opt out, delete this entire section including the marker comments.

[github-actions]

Build Metrics Report

Validation passed. All required build and validation jobs succeeded.

Binary Sizes

Artifact	Baseline	Current	Delta
CLI (ARM64)	57.29 MB	57.29 MB	📈 +1.5 KB (+0.00%)
CLI (x64)	57.33 MB	57.33 MB	📈 +2.0 KB (+0.00%)
MSIX (ARM64)	23.79 MB	23.79 MB	📈 +1.4 KB (+0.01%)
MSIX (x64)	25.26 MB	25.26 MB	📈 +0.7 KB (+0.00%)
NPM Package	49.63 MB	49.64 MB	📈 +2.7 KB (+0.01%)
NuGet Package	49.74 MB	49.74 MB	📈 +1.8 KB (+0.00%)

.NET Test Results (TRX reports)

Other suites are reflected in the overall validation status above.

✅ 7897 passed, 37 skipped out of 7934 tests in 1210.7s (+18 tests, -57.9s vs. baseline)

Test Coverage

✅ 86.3% line coverage, 80.9% branch coverage · ✅ no change vs. baseline

CLI Startup Time

65ms median (x64, winapp --version) · ✅ no change vs. baseline

Try This Build

Installs the MSIX for your architecture, replacing any previously installed build. Needs the GitHub CLI — the command offers to install it and sign you in if it is missing.

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/microsoft/winappCli/main/scripts/winapp-pr.ps1))) 932

Switching between builds often?

Put the tool on your PATH once:

& ([scriptblock]::Create((irm https://raw.githubusercontent.com/microsoft/winappCli/main/scripts/winapp-pr.ps1))) -AddToPath

Then this build is just:

winapp-pr 932

Run winapp-pr with no arguments to pick from a list of open PRs.

---

Updated 2026-09-24 18:33:01 UTC · commit 70edcaf · workflow run