Fix ui/devtools window targeting and unclear error messages by zateutsch · Pull Request #1161 · microsoft/winappCli

Zach Teutsch (zateutsch) · 2026-10-22T00:50:06Z

What and why

winapp ui and winapp devtools sometimes acted on the wrong window, and several errors showed raw codes or .NET type names instead of saying what to do. Now:

Right window. -a <pid> targets the app, not the DevTools inspector (the DevTools window that runs inside the app's process), even when the inspector is in front. -a "My App" prefers the window titled exactly that over "My App 2".
Hex window handles. -w and --root accept 0x hex as well as decimal, so a handle copied from Spy++ or a debugger works. A bad value says what a handle looks like.
Short parse errors. A devtools command with a missing or bad option prints the error and Run 'winapp devtools comments add --help' for usage. instead of the whole help page.
Plain errors. DevTools errors and search output use sentences instead of tokens like no-match or census-cap, and known HRESULTs get a short meaning, for example 0x802B000A (XAML could not be parsed). --of-type Nope says no element has that type. JSON output is unchanged.
Accurate run messages. winapp run no longer says "the app runs without DevTools" when the app exited, or when headless inspection still works. The binding-host message says to relaunch with winapp run --devtools on, and get-source says to rebuild and relaunch.
--devtools off with the app open. winapp run --devtools off used to fail with "still running" when the app was open. It now closes the running copy first, as --devtools on already did.

Fixes #1147

Before / after

winapp ui inspect -w <hex handle> and winapp devtools comments add -a 1 (missing --text), on main and on this branch:

Before

After

Not tested / risks

Behavior change: winapp run now closes a copy of the app running from the same build folder in every mode, including --devtools off and --no-launch. It asks the app to close and ends it after 2 seconds, or right away if the app has no window or is showing a dialog. This is documented in docs/usage.md under run.
I didn't build or run the native C++ message change (DevToolsBindingRelay.cpp and its test) locally.
I checked the inspector-window changes with unit tests and fake window lists, not against a live app with DevTools open.
DevToolsRunTests.Default_ConnectFailure_HumanOutputIsOnePlainLine stalls when the whole class runs in parallel locally but passes alone. This looks pre-existing.

Checklist

Tests added or updated
Tested locally on Windows
Docs, samples, and plugins/winapp/skills/ updated if user-facing behavior changed

- -a by title prefers an exact title match; -a by PID/name skips the in-process DevTools inspector window - -w and --root accept 0x hex handles; bad -w values explain what a handle looks like - devtools parse errors point at --help instead of printing the full help page; the pointer names the full command path - devtools errors and query output use plain sentences instead of raw tokens; known HRESULTs get a meaning - --of-type with a type not in the window says so - step-aside line no longer says the app runs without DevTools when it exited or headless inspection still works - run --devtools off closes the running instance so its files can be replaced - clearer binding-host and get-source stale messages Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 64d9ea83-443c-4cf5-80bc-2611af3c5216

…sing the app - ui element commands no longer fall back to controls in the DevTools inspector when the app lacks them - the inspector title check lives in one place (UiTargetResolver), shared with ui screenshot - 'unknown-child' search truncation gets a plain sentence - usage.md run section and the troubleshoot skill say run closes a copy running from the same layout Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 64d9ea83-443c-4cf5-80bc-2611af3c5216

Copilot

🔵 Needs a closer look

Live inspector targeting and expanded process termination still need Windows runtime verification, and the native C++ change was not built or tested locally.

No open issues 🎉

What changed in this PR

This PR addresses #1147 by improving window selection and error messages across winapp ui and winapp devtools.

Changes:

Prefers app windows over the in-process DevTools inspector and exact titles over partial matches.
Accepts hexadecimal handles, shortens parse errors, and adds clearer failure explanations and recovery steps.
Closes running app copies before registration even with DevTools off, with updated tests and documentation.

File	Description
src/winapp-devtools/test/binding-relay-tests.cpp	Checks the revised binding-host guidance.
src/winapp-devtools/native/WinApp.DevTools.Native/DevToolsBindingRelay.cpp	Recommends relaunching with DevTools enabled.
src/winapp-CLI/WinApp.UIAutomation/Services/UiTargetResolver.cs	Prefers app windows and exact title matches.
src/winapp-CLI/WinApp.UIAutomation/Services/UiAutomationService.cs	Excludes inspector controls from fallback searches.
src/winapp-CLI/WinApp.UIAutomation.Tests/UiTargetResolverTests.cs	Tests inspector filtering and exact-title selection.
src/winapp-CLI/WinApp.UIAutomation.Tests/RealUiAutomationTests.Coverage.cs	Tests that element searches exclude inspector controls.
src/winapp-CLI/WinApp.Cli/Services/DevTools/DevToolsErrors.cs	Explains failure tokens and common Windows error codes.
src/winapp-CLI/WinApp.Cli/Program.cs	Shortens DevTools parse errors and fixes nested help pointers.
src/winapp-CLI/WinApp.Cli/Commands/UiScreenshotCommand.cs	Reuses shared inspector-window detection.
src/winapp-CLI/WinApp.Cli/Commands/SharedUiOptions.cs	Parses decimal and hexadecimal window handles.
src/winapp-CLI/WinApp.Cli/Commands/RunCommand.DevTools.cs	Avoids misleading fallback messages after exit or partial success.
src/winapp-CLI/WinApp.Cli/Commands/RunCommand.cs	Closes running layout processes regardless of DevTools mode.
src/winapp-CLI/WinApp.Cli/Commands/DevToolsQueryOptions.cs	Clarifies query errors while preserving JSON output.
src/winapp-CLI/WinApp.Cli/Commands/DevToolsLiveCommand.cs	Accepts and normalizes hexadecimal root handles.
src/winapp-CLI/WinApp.Cli/Commands/DevToolsGetSourceCommand.cs	Recommends rebuilding and relaunching for stale source.
src/winapp-CLI/WinApp.Cli.Tests/WinAppParserConfigurationTests.cs	Tests handle formats and invalid-value guidance.
src/winapp-CLI/WinApp.Cli.Tests/UiHelpTests.cs	Tests concise DevTools parse-error output.
src/winapp-CLI/WinApp.Cli.Tests/DevToolsRunTests.cs	Tests revised run messages and closing with DevTools off.
src/winapp-CLI/WinApp.Cli.Tests/DevToolsAgentCommandTests.cs	Tests readable error descriptions.
plugins/winapp/skills/winapp-troubleshoot/SKILL.md	Updates guidance for running apps and locked files.
docs/usage.md	Documents automatic app closure and hexadecimal handles.
docs/ui-automation.md	Shows equivalent decimal and hexadecimal handles.
docs/guides/devtools.md	Links app-closure guidance to the run documentation.

_{Review effort: Balanced}

The DevTools e2e test targets inspector controls with -a <pid> (ui wait-for WinAppDevToolsAddComment). Element search already tries the app's main window first, so the filter only blocked that case. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 64d9ea83-443c-4cf5-80bc-2611af3c5216

github-actions · 2026-10-22T02:11:46Z

Build Metrics Report

Validation passed. All required build and validation jobs succeeded.

Binary Sizes

Artifact	Baseline	Current	Delta
CLI (ARM64)	65.05 MB	65.07 MB	📈 +26.0 KB (+0.04%)
CLI (x64)	64.97 MB	65.00 MB	📈 +24.0 KB (+0.04%)
MSIX (ARM64)	26.93 MB	26.94 MB	📈 +8.8 KB (+0.03%)
MSIX (x64)	28.55 MB	28.58 MB	📈 +28.6 KB (+0.10%)
NPM Package	56.12 MB	56.14 MB	📈 +20.3 KB (+0.04%)
NuGet Package	56.27 MB	56.29 MB	📈 +24.6 KB (+0.04%)

.NET Test Results (TRX reports)

Other suites are reflected in the overall validation status above.

✅ 10681 passed, 43 skipped out of 10724 tests in 2268.9s (+17 tests, -315.4s vs. baseline)

Test Coverage

✅ 87.4% line coverage, 81.4% branch coverage · ✅ no change vs. baseline

CLI Startup Time

49ms median (x64, winapp --version) · 📉 -11ms 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))) 1161

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 1161

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

Updated 2026-10-22 23:01:07 UTC · commit 5008a8e · workflow run

Jaylyn Barbee (Jaylyn-Barbee) · 2026-10-22T20:44:34Z

🤖 AI-generated review (winappcli pr-review skill) — verify before acting.

PR Review — zateutsch-validate-ui-window-targeting-issue vs main

Decision

Merge. The solution builds, the related tests pass, and the new handle parsing and short error messages worked against a real Notepad window. I found one optional docs inaccuracy.

Must fix

None. The PR can merge as it is.

Non-blocking

The docs promise a 2-second grace period that some apps don't get

What is wrong: docs/usage.md says winapp run "asks it to close and ends it after 2 seconds". The close request (CloseMainWindow) only works when the app has a main window that can take input. Otherwise the request returns false and Kill() runs right away. Two common cases hit this:
- console or tray apps, which have no window
- apps showing a modal dialog, such as "Save changes?", because the main window is disabled while the dialog is open
Show me: Start a WPF app from its layout and open a "Save changes?" dialog in it. Then run winapp run . --no-launch. Actual: the app is ended at once. Expected (per the docs): winapp asks it to close and waits 2 seconds.
Why it matters: Before this PR, only DevTools runs closed the app. Now --devtools off, --no-launch, and non-WinUI apps (WPF, console, Electron and others) close it too. Those users have the least reason to expect it, and the docs tell them they have 2 seconds to save.
Smallest fix: Correct the sentence, for example: "winapp asks it to close and ends it after 2 seconds, or right away if it has no window or is showing a dialog."
Location: docs/usage.md:777, src/winapp-CLI/WinApp.Cli/Commands/RunCommand.DevTools.cs:218

What was exercised

dotnet build src/winapp-CLI/winapp.sln -c Debug: succeeded with 0 warnings and 0 errors.
dotnet test WinApp.UIAutomation.Tests (the class that holds the target-resolver tests): 47 of 47 passed.
dotnet test WinApp.Cli.Tests limited to the parser, help, DevTools command, and DevTools run test classes: 230 of 230 passed.
Built CLI against a real Notepad window (HWND, the Windows window handle, 3999620):
- ui inspect -w 3999620 and ui inspect -w 0x3D0784 inspected the same window.
- ui screenshot -w 0X3D0784 saved the screenshot.
- ui inspect -w notepad and -w 0xFFFFFFFFFFFFFFFF printed "'…' is not a window handle…" plus a one-line help pointer, and exited with code 1.
- ui inspect -a "Untitled - Notepad" and -a <pid> picked the right window.
devtools comments add -a 1: printed "Option '--text' is required." and Run 'winapp devtools comments add --help' for usage. with no full help page.
- With --json, it printed the same JSON error envelope as before.
- A bare devtools comments still shows the group's help.
Not exercised:
- Release build: dotnet publish failed on this machine because vswhere.exe was not on PATH. This is a local tool setup problem, not a PR defect, so all runs used the Debug binary.
- Inspector window open: I did not test -a <pid> skipping the inspector or devtools search reaching inspector controls with DevTools open in a live WinUI app. Unit tests cover both paths. Confirming them needs a WinUI app started with winapp run --devtools on.
- Closing a running app: I did not test winapp run --devtools off or --no-launch closing a live app. Unit tests cover the close.
- Native C++ message change: I did not build or run it.

Jaylyn Barbee (Jaylyn-Barbee)

Approved with one optional fix.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 64d9ea83-443c-4cf5-80bc-2611af3c5216

Zach Teutsch (zateutsch) · 2026-10-22T22:15:16Z

Jaylyn Barbee (@Jaylyn-Barbee) Fixed in 5008a8e: the
un\ docs now say winapp ends the app right away if it has no window or is showing a dialog.

Zach Teutsch (zateutsch) and others added 2 commits October 21, 2026 20:46

Copilot AI balanced review requested due to automatic review settings October 22, 2026 00:50

Zach Teutsch (zateutsch) added the agent-preparing Agent is addressing feedback or completing required validation and CI label Oct 22, 2026

Copilot started reviewing on behalf of Zach Teutsch (zateutsch) October 22, 2026 00:50

View session

github-code-quality Bot found potential problems Oct 22, 2026

View reviewed changes

Comment thread src/winapp-CLI/WinApp.Cli/Services/DevTools/DevToolsErrors.cs

Copilot AI reviewed Oct 22, 2026

View reviewed changes

Zach Teutsch (zateutsch) added ready-for-review Agent work and technical checks complete; awaiting review or re-review, not approval or merge and removed agent-preparing Agent is addressing feedback or completing required validation and CI labels Oct 22, 2026

Jaylyn Barbee (Jaylyn-Barbee) approved these changes Oct 22, 2026

View reviewed changes

Chiara Mooney (chiaramooney) approved these changes Oct 22, 2026

View reviewed changes

Say when winapp run ends the app without waiting

5008a8e

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 64d9ea83-443c-4cf5-80bc-2611af3c5216

Navigation Menu

Repository navigation

Fix ui/devtools window targeting and unclear error messages - #1161

Fix ui/devtools window targeting and unclear error messages#1161
Zach Teutsch (zateutsch) wants to merge 4 commits into
mainfrom
zateutsch-validate-ui-window-targeting-issue

Zach Teutsch (zateutsch) commented Oct 22, 2026 •

edited

Loading

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

github-actions Bot commented Oct 22, 2026 •

edited

Loading

Uh oh!

Jaylyn Barbee (Jaylyn-Barbee) commented Oct 22, 2026

Uh oh!

Jaylyn Barbee (Jaylyn-Barbee) left a comment

Uh oh!

Zach Teutsch (zateutsch) commented Oct 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

Zach Teutsch (zateutsch) commented Oct 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What and why

Before / after

Not tested / risks

Checklist

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

🔵 Needs a closer look

Uh oh!

github-actions Bot commented Oct 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Build Metrics Report

Binary Sizes

.NET Test Results (TRX reports)

Test Coverage

CLI Startup Time

Try This Build

Uh oh!

Jaylyn Barbee (Jaylyn-Barbee) commented Oct 22, 2026

PR Review — zateutsch-validate-ui-window-targeting-issue vs main

Decision

Must fix

Non-blocking

The docs promise a 2-second grace period that some apps don't get

What was exercised

Uh oh!

Jaylyn Barbee (Jaylyn-Barbee) left a comment

Choose a reason for hiding this comment

Uh oh!

Zach Teutsch (zateutsch) commented Oct 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Zach Teutsch (zateutsch) commented Oct 22, 2026 •

edited

Loading

github-actions Bot commented Oct 22, 2026 •

edited

Loading