Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -32,10 +32,11 @@ internal sealed class FakeDesktopForegroundService : IDesktopForegroundService

public Action<long>? OnRequestForeground { get; set; }

public void RequestForeground(long hwnd)
public bool RequestForeground(long hwnd)
{
ForegroundRequests.Add(hwnd);
OnRequestForeground?.Invoke(hwnd);
return ForegroundRequestSucceeds;
}

/// <summary>
Expand Down
1 change: 1 addition & 0 deletions src/winapp-CLI/WinApp.Cli.Tests/PublicApiSurfaceTests.cs
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@ public class PublicApiSurfaceTests
"CaptureCoordinates",
"CoordinateParser",
"ForegroundCheck",
"ForegroundCheckSnapshot",
"ForegroundGuard",
"ForegroundLostException",
"GestureTargeting",
Expand Down
64 changes: 64 additions & 0 deletions src/winapp-CLI/WinApp.Cli.Tests/UiCommandTests.Mouse.cs
Original file line number Diff line number Diff line change
Expand Up @@ -311,6 +311,70 @@ public async Task Drag_FromMovesDuringSettle_ReturnsTargetMoved()
}

[TestMethod]
[DataRow(1, "before-cursor", false)]
[DataRow(2, "before-button-down", true)]
public async Task Drag_ForegroundDenial_RetainsGateAndRequestObservations(
int rejectingCall, string expectedGate, bool requestSucceeded)
{
_fakeTargetResolver.TargetResult.WindowHandle = 4242;
_fakeUia.FindSingleResult = new UiElement
{
Type = "Image", Selector = "ContentSizer.Sizer", X = 100, Y = 200,
Width = 540, Height = 17, WindowHandle = 7777
};
_fakeDesktopForeground.ForegroundRequestSucceeds = requestSucceeded;
_fakeSystemQuery.ForegroundWindowResult = requestSucceeded ? 7777 : 9000;
_fakeSystemQuery.ProcessIdByHwnd[9000] = 42;
var observedAt = new DateTimeOffset(2026, 1, 2, 3, 4, 5, TimeSpan.Zero);
_fakeForeground.Snapshot = new ForegroundCheckSnapshot(
observedAt, 7777, 7000, true, 8800, observedAt.AddMilliseconds(1), 9900,
observedAt.AddMilliseconds(2), 1234, 1234, 88, 99);
_fakeForeground.CheckResult = _ =>
{
// A later query must not replace either the request observation or the guard's snapshot.
_fakeSystemQuery.ForegroundWindowResult = 5555;
return _fakeForeground.Calls.Count == rejectingCall
? ForegroundCheck.ForegroundNotTarget : ForegroundCheck.Proceed;
};

var command = GetRequiredService<UiDragCommand>();
var exitCode = await ParseAndInvokeWithCaptureAsync(command,
["ContentSizer.Sizer", "1302,893", "-w", "4242", "--json"]);

Assert.AreEqual(1, exitCode);
Assert.AreEqual(0, _fakeMouse.DragCalls.Count);
Assert.AreEqual(rejectingCall - 1, _fakeMouse.MoveCursorCalls.Count);
Assert.AreEqual(rejectingCall, _fakeForeground.Calls.Count);
Assert.AreSequenceEqual(new long[] { 7777 }, _fakeDesktopForeground.ForegroundRequests,
"Diagnostics must not add another activation request.");
Assert.IsTrue(string.IsNullOrWhiteSpace(TestAnsiConsole.Output), "A refusal must not emit a drag success.");

var stderr = ConsoleStdErr.ToString();
var result = System.Text.Json.JsonSerializer.Deserialize<System.Text.Json.JsonElement>(
stderr.AsSpan(stderr.IndexOf('{')).TrimEnd());
var error = result.GetProperty("error");
Assert.AreEqual("code,details,message",
string.Join(',', error.EnumerateObject().Select(p => p.Name).Order()));
Assert.AreEqual("foreground_not_target", error.GetProperty("code").GetString());
Assert.AreEqual(
"Target window is not in the foreground — refusing to drag to avoid acting on the wrong window. Activate the intended window manually, check for a blocking dialog, then retry.",
error.GetProperty("message").GetString());
Assert.AreEqual(System.Text.Json.JsonValueKind.String, error.GetProperty("details").ValueKind);
var details = error.GetProperty("details").GetString()!;
Assert.Contains($"gate={expectedGate};", details);
Assert.Contains("comparedAtUtc=2026-01-02T03:04:05.0000000+00:00;", details);
Assert.Contains("targetHwnd=7777; rootHwnd=7000; rootWasCompared=True; foregroundHwnd=8800;", details);
Assert.Contains("classificationForegroundHwnd=9900;", details);
Assert.Contains("targetPid=1234; rootPid=1234; foregroundPid=88; classificationForegroundPid=99;", details);
Assert.Contains("ownershipMetadata=queried-after-decision;", details);
Assert.Contains("requestedWindowHwnd=4242; resolvedWindowHwnd=4242; resolvedPid=1234;", details);
Assert.Contains("requestTargetHwnd=7777;", details);
Assert.Contains($"requestSucceeded={requestSucceeded};", details);
Assert.Contains($"requestForegroundHwnd={(requestSucceeded ? 7777 : 9000)};", details);
Assert.Contains($"requestForegroundPid={(requestSucceeded ? 1234 : 42)}", details);
}

[TestMethod]
[DataRow("100,")]
[DataRow("100,200,300")]
[DataRow("100,abc")]
Expand Down
15 changes: 15 additions & 0 deletions src/winapp-CLI/WinApp.Cli.Tests/UiInjectionReportingTests.cs
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,21 @@ public void TryEnsureForeground_ReportsForegroundNotTargetWithAction()
Assert.Contains("refusing to scroll --wheel", logger.Messages.Single().Message);
}

[TestMethod]
public void TryEnsureForeground_ExistingGuardWithoutSnapshots_StillRejectsAndReportsUnavailable()
{
var logger = new CapturingLogger();
using var output = new StringWriter();

Assert.IsFalse(new StubGuard(ForegroundCheck.ForegroundNotTarget).TryEnsureForeground(
10, logger, json: true, action: "drag", errorOut: output, gate: "before-cursor"));

using var document = System.Text.Json.JsonDocument.Parse(output.ToString());
var error = document.RootElement.GetProperty("error");
Assert.AreEqual("foreground_not_target", error.GetProperty("code").GetString());
Assert.Contains("guardSnapshot=unavailable", error.GetProperty("details").GetString()!);
}

[TestMethod]
public void TryReport_ReturnsTrueForOkWithoutLogging()
{
Expand Down
23 changes: 20 additions & 3 deletions src/winapp-CLI/WinApp.Cli/Commands/UiDragCommand.cs
Original file line number Diff line number Diff line change
Expand Up @@ -181,9 +181,22 @@ protected override async Task<int> ExecuteAsync(ParseResult parseResult, IUiTurn
return 1;
}

string? foregroundRequestDetails = null;
if (targetHwnd != 0)
{
desktopForeground.RequestForeground(targetHwnd);
var requestedAtUtc = DateTimeOffset.UtcNow;
var requestSucceeded = desktopForeground.RequestForeground(targetHwnd);
var observedAtUtc = DateTimeOffset.UtcNow;
var requestForegroundHwnd = (long)systemQuery.GetForegroundWindow();
var metadataAtUtc = DateTimeOffset.UtcNow;
var requestForegroundPid = requestForegroundHwnd == 0
? 0 : systemQuery.GetProcessIdForWindow(requestForegroundHwnd);
foregroundRequestDetails = string.Create(System.Globalization.CultureInfo.InvariantCulture,
$"requestedWindowHwnd={window?.ToString(System.Globalization.CultureInfo.InvariantCulture) ?? "unspecified"}; " +
$"resolvedWindowHwnd={uiTarget.WindowHandle}; resolvedPid={uiTarget.ProcessId}; " +
$"requestTargetHwnd={targetHwnd}; requestAtUtc={requestedAtUtc:O}; requestSucceeded={requestSucceeded}; " +
$"requestObservedAtUtc={observedAtUtc:O}; requestForegroundHwnd={requestForegroundHwnd}; " +
$"requestMetadataAtUtc={metadataAtUtc:O}; requestForegroundPid={requestForegroundPid}");
await Task.Delay(100, cancellationToken);
}

Expand All @@ -208,7 +221,9 @@ protected override async Task<int> ExecuteAsync(ParseResult parseResult, IUiTurn
toY = toStable.Y;

// Verify the target STILL holds the foreground as the first gate before the OS-wide drag.
if (!foregroundGuard.TryEnsureForeground(targetHwnd, logger, json, "drag"))
if (!foregroundGuard.TryEnsureForeground(targetHwnd, logger, json, "drag",
errorOut: parseResult.InvocationConfiguration.Error,
gate: "before-cursor", requestDetails: foregroundRequestDetails))
{
return 1;
}
Expand All @@ -230,7 +245,9 @@ protected override async Task<int> ExecuteAsync(ParseResult parseResult, IUiTurn
fromY = confirmed.CenterY;

// Final foreground gate after the awaited confirm read (focus could shift during it).
if (!foregroundGuard.TryEnsureForeground(targetHwnd, logger, json, "drag"))
if (!foregroundGuard.TryEnsureForeground(targetHwnd, logger, json, "drag",
errorOut: parseResult.InvocationConfiguration.Error,
gate: "before-button-down", requestDetails: foregroundRequestDetails))
{
return 1;
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,8 @@ internal interface IDesktopForegroundService
/// (focus-stealing prevention, a UAC prompt, a locked session); callers must still verify with
/// <see cref="IForegroundGuard"/> before injecting OS-wide input.
/// </summary>
void RequestForeground(long hwnd);
/// <returns>The native request's Boolean result, not a guarantee of continued foreground ownership.</returns>
bool RequestForeground(long hwnd);

/// <summary>
/// Whether <paramref name="hwnd"/> (or its top-level root) currently holds the foreground.
Expand Down Expand Up @@ -60,14 +61,14 @@ internal interface IDesktopForegroundService
/// </remarks>
internal sealed class DesktopForegroundService : IDesktopForegroundService
{
public void RequestForeground(long hwnd)
public bool RequestForeground(long hwnd)
{
if (hwnd == 0)
{
return;
return false;
}

Windows.Win32.PInvoke.SetForegroundWindow(new Windows.Win32.Foundation.HWND((nint)hwnd));
return Windows.Win32.PInvoke.SetForegroundWindow(new Windows.Win32.Foundation.HWND((nint)hwnd));
}

public bool IsForeground(long hwnd)
Expand Down
36 changes: 32 additions & 4 deletions src/winapp-CLI/WinApp.Cli/Helpers/UiInjectionReporting.cs
Original file line number Diff line number Diff line change
Expand Up @@ -24,9 +24,21 @@ internal static class UiInjectionReporting
/// <param name="action">Verb used in the message, e.g. "click", "drag", "scroll --wheel".</param>
public static bool TryEnsureForeground(
this IForegroundGuard guard, long targetHwnd, ILogger logger, bool json, string action,
TextWriter? errorOut = null)
TextWriter? errorOut = null, string? gate = null, string? requestDetails = null)
{
switch (guard.CheckForeground(targetHwnd))
ForegroundCheckSnapshot? snapshot = null;
var outcome = gate is null
? guard.CheckForeground(targetHwnd)
: guard.CheckForeground(targetHwnd, out snapshot);
var details = gate is not null && outcome != ForegroundCheck.Proceed
? FormatForegroundDetails(gate, requestDetails, snapshot)
: null;
if (details is not null && !json)
{
logger.LogError("{ForegroundDetails}", details);
}

switch (outcome)
{
case ForegroundCheck.Proceed:
return true;
Expand All @@ -37,7 +49,7 @@ public static bool TryEnsureForeground(
UiSymbols.Error);
UiJsonError.Emit(json, UiJsonError.CodeNoInteractiveDesktop,
"No interactive desktop is available (session locked or on a secure desktop). Unlock the session and retry.",
errorOut: errorOut);
details: details, errorOut: errorOut);
return false;

case ForegroundCheck.ForegroundNotTarget:
Expand All @@ -47,11 +59,27 @@ public static bool TryEnsureForeground(
UiSymbols.Error, action);
UiJsonError.Emit(json, UiJsonError.CodeForegroundNotTarget,
$"Target window is not in the foreground — refusing to {action} to avoid acting on the wrong window. Activate the intended window manually, check for a blocking dialog, then retry.",
errorOut: errorOut);
details: details, errorOut: errorOut);
return false;
}
}

private static string FormatForegroundDetails(string gate, string? requestDetails, ForegroundCheckSnapshot? snapshot)
{
if (snapshot is null)
{
return $"gate={gate}; guardSnapshot=unavailable; {requestDetails}";
}

return string.Create(System.Globalization.CultureInfo.InvariantCulture,
$"gate={gate}; comparedAtUtc={snapshot.ComparedAtUtc:O}; targetHwnd={snapshot.TargetHwnd}; " +
$"rootHwnd={snapshot.RootHwnd}; rootWasCompared={snapshot.RootWasCompared}; foregroundHwnd={snapshot.ForegroundHwnd}; " +
$"classifiedAtUtc={snapshot.ClassifiedAtUtc:O}; classificationForegroundHwnd={snapshot.ClassificationForegroundHwnd}; " +
$"metadataAtUtc={snapshot.MetadataAtUtc:O}; targetPid={snapshot.TargetProcessId}; rootPid={snapshot.RootProcessId}; " +
$"foregroundPid={snapshot.ForegroundProcessId}; classificationForegroundPid={snapshot.ClassificationForegroundProcessId}; " +
$"ownershipMetadata=queried-after-decision; {requestDetails}");
}

/// <summary>
/// Returns <see langword="true"/> when the target settled (proceed with the gesture). Otherwise logs
/// and emits the matching JSON error (<c>target_moved</c> for a vanished/animating element,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -476,6 +476,7 @@ public void Send(long hwnd, IReadOnlyList<KeyAction> actions, KeyTransport trans
public class FakeForegroundGuard : IForegroundGuard
{
public Func<long, ForegroundCheck>? CheckResult { get; set; }
public ForegroundCheckSnapshot? Snapshot { get; set; }
public record EnsureCall(long TargetHwnd);

public List<EnsureCall> Calls { get; } = [];
Expand Down Expand Up @@ -504,6 +505,13 @@ public ForegroundCheck CheckForeground(long targetHwnd)
var deny = DenyOnCallNumber is int n ? Calls.Count == n : !Allow;
return deny ? DenyReason : ForegroundCheck.Proceed;
}

public ForegroundCheck CheckForeground(long targetHwnd, out ForegroundCheckSnapshot? snapshot)
{
var result = CheckForeground(targetHwnd);
snapshot = result == ForegroundCheck.Proceed ? null : Snapshot;
return result;
}
}

/// <summary>
Expand Down
64 changes: 64 additions & 0 deletions src/winapp-CLI/WinApp.UIAutomation.Tests/ForegroundGuardTests.cs
Original file line number Diff line number Diff line change
Expand Up @@ -95,6 +95,70 @@ public void CheckForeground_ReportsForegroundNotTarget()
Assert.AreEqual(ForegroundCheck.ForegroundNotTarget, ForegroundGuard.CheckForeground(10));
}

[TestMethod]
[DataRow(10L, 10L, 20L, ForegroundCheck.Proceed)]
[DataRow(20L, 20L, 20L, ForegroundCheck.Proceed)]
[DataRow(20L, 30L, 40L, ForegroundCheck.ForegroundNotTarget)]
[DataRow(0L, 0L, 40L, ForegroundCheck.NoInteractiveDesktop)]
[DataRow(0L, 20L, 40L, ForegroundCheck.ForegroundNotTarget)]
[DataRow(20L, 0L, 40L, ForegroundCheck.NoInteractiveDesktop)]
[DataRow(10L, 0L, 40L, ForegroundCheck.Proceed)]
public void CheckForeground_SnapshotRetainsOriginalReadsAndDecision(
long firstForeground, long secondForeground, long rootHwnd, ForegroundCheck expected)
{
var calls = new List<string>();
ConfigureReads();
Assert.AreEqual(expected, ForegroundGuard.CheckForeground(10));
var originalCalls = calls.ToArray();

calls.Clear();
ConfigureReads();
var result = new RealForegroundGuard().CheckForeground(10, out var snapshot);

Assert.AreEqual(expected, result);
Assert.AreSequenceEqual(originalCalls, calls.Take(originalCalls.Length).ToArray(),
"Diagnostics must preserve both foreground reads and the comparison's root lookup order.");
Assert.AreEqual(2, calls.Count(c => c.StartsWith("foreground", StringComparison.Ordinal)));
if (expected == ForegroundCheck.Proceed)
{
Assert.IsNull(snapshot);
Assert.AreSequenceEqual(originalCalls, calls, "Accepted checks need no diagnostic ownership queries.");
return;
}

Assert.IsNotNull(snapshot);
ForegroundGuard.s_getForegroundWindow = () => throw new AssertFailedException("Do not re-read foreground for retained diagnostics.");
Assert.AreEqual(firstForeground, snapshot.ForegroundHwnd);
Assert.AreEqual(secondForeground, snapshot.ClassificationForegroundHwnd);
Assert.AreEqual(rootHwnd, snapshot.RootHwnd);
Assert.AreEqual(firstForeground != 0, snapshot.RootWasCompared);
Assert.AreEqual(110u, snapshot.TargetProcessId);
Assert.AreEqual((uint)(rootHwnd + 100), snapshot.RootProcessId);
Assert.AreEqual(firstForeground == 0 ? 0u : (uint)(firstForeground + 100), snapshot.ForegroundProcessId);
Assert.AreEqual(secondForeground == 0 ? 0u : (uint)(secondForeground + 100), snapshot.ClassificationForegroundProcessId);

void ConfigureReads()
{
var foregrounds = new Queue<long>([firstForeground, secondForeground]);
ForegroundGuard.s_getForegroundWindow = () =>
{
var hwnd = foregrounds.Dequeue();
calls.Add($"foreground:{hwnd}");
return new HWND((nint)hwnd);
};
ForegroundGuard.s_getRootAncestor = hwnd =>
{
calls.Add($"root:{(nint)hwnd}");
return new HWND((nint)rootHwnd);
};
ForegroundGuard.s_getProcessIdForWindow = hwnd =>
{
calls.Add($"pid:{hwnd}");
return (uint)(hwnd + 100);
};
}
}

[TestMethod]
public void RealForegroundGuard_DelegatesToForegroundGuard()
{
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
// Copyright (c) Microsoft Corporation and Contributors. All rights reserved.
// Licensed under the MIT License.

namespace Microsoft.Windows.SDK.BuildTools.WinApp.UIAutomation;

/// <summary>Retained observations from a rejected foreground check, not a later foreground query.</summary>
/// <remarks>
/// The comparison and desktop classification use separate foreground reads. Process IDs, and the root
/// when it was not compared, are queried afterward at <paramref name="MetadataAtUtc"/>. These observations
/// are not atomic; a zero process ID means the window's process could not be determined.
/// </remarks>
/// <param name="ComparedAtUtc">UTC time immediately before the foreground comparison.</param>
/// <param name="TargetHwnd">Window the check was asked to protect.</param>
/// <param name="RootHwnd">Target's top-level root, or zero when unavailable.</param>
/// <param name="RootWasCompared">Whether the root came from the comparison rather than the metadata read.</param>
/// <param name="ForegroundHwnd">Foreground window observed by the comparison, or zero.</param>
/// <param name="ClassifiedAtUtc">UTC time immediately before the desktop-classification foreground read.</param>
/// <param name="ClassificationForegroundHwnd">Foreground window observed by the second read, or zero.</param>
/// <param name="MetadataAtUtc">UTC time immediately before querying diagnostic window ownership.</param>
/// <param name="TargetProcessId">Process owning the target at the metadata read.</param>
/// <param name="RootProcessId">Process owning the root at the metadata read.</param>
/// <param name="ForegroundProcessId">Process owning the comparison's foreground handle at the metadata read.</param>
/// <param name="ClassificationForegroundProcessId">Process owning the second read's handle at the metadata read.</param>
public sealed record ForegroundCheckSnapshot(
Comment thread
azchohfi marked this conversation as resolved.
Resolved
DateTimeOffset ComparedAtUtc,
long TargetHwnd,
long RootHwnd,
bool RootWasCompared,
long ForegroundHwnd,
DateTimeOffset ClassifiedAtUtc,
long ClassificationForegroundHwnd,
DateTimeOffset MetadataAtUtc,
uint TargetProcessId,
uint RootProcessId,
uint ForegroundProcessId,
uint ClassificationForegroundProcessId);
Loading
Loading