Repository navigation
Explain which foreground check refused a drag - #1385
Alexandre Zollinger Chohfi (azchohfi) wants to merge 3 commits into
Conversation
Report the rejecting gate and retained request/check observations in the existing error.details string without changing foreground acceptance or input dispatch. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
🟡 Changes recommended
The new public ForegroundCheckSnapshot record is missing from ExpectedUiAutomationTypes, causing the public API surface test to fail until the expected exports are updated.
1 open issue
What changed in this PR
This PR adds diagnostics to winapp ui drag refusals so users can identify which foreground safety check rejected the drag. It preserves both checks and the existing error code, message, and JSON structure.
Changes:
- Records the rejecting check, window handles, process IDs, and observation times in
error.details. - Captures the foreground request’s result while keeping separate observations clearly labeled.
- Adds headless tests for both refusal points, retained observations, and guards without snapshot support.
| File | Description |
|---|---|
| src/winapp-CLI/WinApp.UIAutomation/Input/RealForegroundGuard.cs | Delegates checks that return diagnostic snapshots. |
| src/winapp-CLI/WinApp.UIAutomation/Input/IForegroundGuard.cs | Adds an optional snapshot overload for existing implementations. |
| src/winapp-CLI/WinApp.UIAutomation/Input/ForegroundGuard.cs | Retains rejection observations without changing decisions. |
| src/winapp-CLI/WinApp.UIAutomation/Input/ForegroundCheckSnapshot.cs | Defines the diagnostic snapshot and observation semantics. |
| src/winapp-CLI/WinApp.UIAutomation.TestSupport/FakeUiServices.cs | Supports snapshots in the fake foreground guard. |
| src/winapp-CLI/WinApp.UIAutomation.Tests/ForegroundGuardTests.cs | Tests preserved decisions and foreground-read order. |
| src/winapp-CLI/WinApp.Cli/Helpers/UiInjectionReporting.cs | Formats diagnostic details for foreground refusals. |
| src/winapp-CLI/WinApp.Cli/Helpers/IDesktopForegroundService.cs | Returns the native foreground request’s Boolean result. |
| src/winapp-CLI/WinApp.Cli/Commands/UiDragCommand.cs | Captures request observations and labels both safety checks. |
| src/winapp-CLI/WinApp.Cli.Tests/UiInjectionReportingTests.cs | Tests reporting when snapshots are unavailable. |
| src/winapp-CLI/WinApp.Cli.Tests/UiCommandTests.Mouse.cs | Tests both refusal points and verifies no drag is sent. |
| src/winapp-CLI/WinApp.Cli.Tests/FakeDesktopForegroundService.cs | Returns a configurable foreground request result. |
Review effort: Balanced
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Build Metrics ReportValidation passed. All required build and validation jobs succeeded. Binary Sizes
.NET Test Results (TRX reports)Other suites are reflected in the overall validation status above. ✅ 11435 passed, 44 skipped out of 11479 tests in 2026.9s (+10 tests, +319.7s vs. baseline) Test Coverage✅ 87.4% line coverage, 81.6% branch coverage · ✅ no change vs. baseline CLI Startup Time57ms median (x64, Updated 2026-11-21 01:08:58 UTC · commit |

What and why
When
winapp ui dragrefuses input because another window is in front, its error now identifies which of the two safety checks rejected the drag. The existingerror.detailsstring includes the window handles (Windows window IDs), process IDs, observation times, and the result of the existing foreground request. This lets a captured failure distinguish a failed foreground request from a later foreground change.The error code, message and JSON schema stay unchanged. Both safety checks remain, and a rejected drag sends no mouse-button input. This adds diagnostics, not a fix for the previously reported foreground loss.
Related to microsoft/microsoft-ui-reactor#1601.
Before / after
Before — the recorded v0.8.0 failure, whose error path is unchanged on the base branch, reported
foreground_not_targetwithout identifying the failing check.After — passing headless tests capture either
gate=before-cursororgate=before-button-downinside the existingerror.detailsstring.Observed headless output excerpts
These excerpts use synthetic window and process IDs from the tests, not a live desktop capture.
Both cases also retain the comparison's
foregroundHwnd=8800and the separate classification read'sclassificationForegroundHwnd=9900. Later process-ID lookups are explicitly labeledownershipMetadata=queried-after-decisionrather than presented as one atomic observation.Not tested / risks
No new live-desktop refusal or terminal screenshot was captured because this work has no authorized desktop-input slot. A separately authorized consumer run of the original diagnostic build passed both foreground checks but still resized from 140 to 196 instead of 200. It did not establish the cause of the earlier foreground failures or fix the sizing discrepancy.
Current-head CI passed, including packaging, UI E2E and samples. Local validation was headless. Window ownership can change between reads, so the diagnostics retain and label separate observations rather than claiming an atomic snapshot.
Checklist
plugins/winapp/skills/updated if user-facing behavior changed — not needed, command syntax and recovery instructions are unchangedNotes for reviewers
The existing
CheckForeground(long)API remains. The additive snapshot overload preserves both foreground reads and their order. Existing custom guards can continue implementing the original interface methods and explicitly report unavailable diagnostic snapshots.Validation for head
37a79f8291c8e6a8dbdde79450f25fd0111318a8Earlier full local build at diagnostic commit
d1b2dbe2d03ffdaf104c37c5348115e0e92789a0The consumer used that original x64 executable with SHA256
3A3294E4BA9F3E5BF145D2208C41DB03FAD7A739CD7E639BE85B449EB9961F20, version0.8.1-azchohfi-guarded-input-diagnostics.42. No installed binary was replaced.