diff --git a/COMPATIBILITY.md b/COMPATIBILITY.md index a2757e433..0ec214bed 100644 --- a/COMPATIBILITY.md +++ b/COMPATIBILITY.md @@ -35,7 +35,7 @@ Names are C# versions of the JavaScript API: `agent.act` is `ActAsync`, `screen. - NUnit `[Test]`, `[SetUp]`, `[TearDown]`, `[OneTimeSetUp]`, and `[OneTimeTearDown]` - `Assert.Ignore`, `[Retry]`, `[Timeout]`, and `[Category]` -- Screen queries: role, text, label, test id, placeholder, display value, `filter` (`hasText`, `hasNotText`, `has`, and `hasNot`), `or`, `first`, `last`, `nth`. A locator offers every query kind, scoped to its matches' descendants. Every query takes a `TextMatch`: a string or a .NET `Regex`, tested against the whitespace-normalized text. A string matches the whole text, case-sensitively, unless `exact` is false, which makes it a case-insensitive substring, as upstream. `RoleOptions` carries `name`, `checked`, `disabled`, `selected`, `expanded`, `pressed`, and `level`, and `img` is read as `image`. A role query never matches a hidden node; the other kinds keep hidden nodes unless `Visible` is set, as upstream. `getByLabel` matches any node whose accessible name matches, as the upstream reference resolver does. Options are C# objects (`RoleOptions`, `TextMatchOptions`) instead of object literals, and `filter({ hasText, hasNotText, has, hasNot })` is the overloads `Filter(TextMatch)` and `Filter(Locator)` plus `Filter(hasText, hasNotText, has, hasNot)`, whose four parameters are optional and named (.NET-only: the named-argument form of upstream's options object). `hasNotText` (tester-army/e2e#1037, `a481fd3`) drops a match whose subtree text matches, with `hasText`'s substring rules (an empty string matches everything, so it drops every match). `hasNot` (#1334, `6c8e71f`) drops a match whose subtree resolves the inner locator, resolved inside each match as `has` is, and a display-value `hasNot` is `UNSUPPORTED_CAPABILITY` in the core resolver as `has` is. A `Filter()` with none of the four is `INVALID_LOCATOR` (`filter() requires hasText, hasNotText, has, and/or hasNot`). Upstream's refusal of an unknown key (`visible`) or a non-object options has no port, since the parameters are typed. On iOS a plain React Native `View` has no children in the tree, so `hasNot` keeps every such row (see the mobile guide) Regular expressions use .NET syntax, not ECMAScript. `GetByTestId` also takes `Exact`, which upstream's `getByTestId` does not. `locator.or(other)` (upstream #1049) is `Or(Locator)`: a `union` expression that matches either branch once, in document order, and stays strict (`LOCATOR_AMBIGUOUS`; add `First()` when both may match). Both locators must come from the same screen and attempt, else `INVALID_LOCATOR`. `LocatorResolver.Resolve` and `DeviceLocator.ResolveExpression` resolve the union. Differences: the parameter is typed, so upstream's refusal of a non-locator has no port (`null` is an `ArgumentNullException`); and upstream's `UNSUPPORTED_CAPABILITY` for a display-value branch has no port, since the port's engines resolve over their tree. Web branches with different frame-selector chains fail with `UNSUPPORTED_CAPABILITY` (`locator.or requires both branches in the same document`) as upstream's `frameSelectors` does +- Screen queries: role, text, label, test id, placeholder, display value, `filter` (`hasText`, `hasNotText`, `has`, and `hasNot`), `or`, `first`, `last`, `nth`. A locator offers every query kind, scoped to its matches' descendants. Every query takes a `TextMatch`: a string or a .NET `Regex`, tested against the whitespace-normalized text. A string matches the whole text, case-sensitively, unless `exact` is false, which makes it a case-insensitive substring, as upstream. `RoleOptions` carries `name`, `checked`, `disabled`, `selected`, `expanded`, `pressed`, and `level`, and `img` is read as `image`. A role query never matches a hidden node; the other kinds keep hidden nodes unless `Visible` is set, as upstream. `ScrollIntoViewAsync` acts on a hidden or disabled match, as upstream's `performUntil` reads no state (the web engine's Playwright call needs no visibility); every other action still waits for an enabled match. A text query leaves out a match with no box (a `Rect` with a zero side; a node that reports no `Rect` counts as boxed) when a match with a box exists, because upstream's web tree lists no box-less node and this tree does (a zero-sized input inside a label does not stand in for the label). A label's text is listed when its control has no box. `getByLabel` matches any node whose accessible name matches, as the upstream reference resolver does. Options are C# objects (`RoleOptions`, `TextMatchOptions`) instead of object literals, and `filter({ hasText, hasNotText, has, hasNot })` is the overloads `Filter(TextMatch)` and `Filter(Locator)` plus `Filter(hasText, hasNotText, has, hasNot)`, whose four parameters are optional and named (.NET-only: the named-argument form of upstream's options object). `hasNotText` (tester-army/e2e#1037, `a481fd3`) drops a match whose subtree text matches, with `hasText`'s substring rules (an empty string matches everything, so it drops every match). `hasNot` (#1334, `6c8e71f`) drops a match whose subtree resolves the inner locator, resolved inside each match as `has` is, and a display-value `hasNot` is `UNSUPPORTED_CAPABILITY` in the core resolver as `has` is. A `Filter()` with none of the four is `INVALID_LOCATOR` (`filter() requires hasText, hasNotText, has, and/or hasNot`). Upstream's refusal of an unknown key (`visible`) or a non-object options has no port, since the parameters are typed. On iOS a plain React Native `View` has no children in the tree, so `hasNot` keeps every such row (see the mobile guide) Regular expressions use .NET syntax, not ECMAScript. `GetByTestId` also takes `Exact`, which upstream's `getByTestId` does not. `locator.or(other)` (upstream #1049) is `Or(Locator)`: a `union` expression that matches either branch once, in document order, and stays strict (`LOCATOR_AMBIGUOUS`; add `First()` when both may match). Both locators must come from the same screen and attempt, else `INVALID_LOCATOR`. `LocatorResolver.Resolve` and `DeviceLocator.ResolveExpression` resolve the union. Differences: the parameter is typed, so upstream's refusal of a non-locator has no port (`null` is an `ArgumentNullException`); and upstream's `UNSUPPORTED_CAPABILITY` for a display-value branch has no port, since the port's engines resolve over their tree. Web branches with different frame-selector chains fail with `UNSUPPORTED_CAPABILITY` (`locator.or requires both branches in the same document`) as upstream's `frameSelectors` does - Actions: tap, click (an alias of tap), doubleTap (`DblClickAsync` is an alias), fill (a string or a `Secret`), pressSequentially, press, check, uncheck, clear, selectOption, focus, scrollIntoView. They wait up to the action timeout for exactly one enabled, visible match. `selectOption` takes a string that matches an option value or label, or a `SelectOption` with exactly one of `Label`, `Value`, or a nonnegative `Index` (upstream's `{ label }`, `{ value }`, `{ index }`; the document engine refuses `Index`). Upstream's plain string means a label only; the port keeps matching a value or a label. `ActionOptions.Timeout` overrides the wait per action (`PressSequentiallyOptions` adds `Delay`). The web engine's own Playwright wait still uses the configured action timeout - Locator reads: `textContent`, `inputValue`, `getAttribute`, `isVisible`, `isHidden`, `isEnabled`, `isDisabled`, `isChecked`, `boundingBox`, `count`, `all`, `allTextContents`. A read of one node (`textContent`, `inputValue`, `getAttribute`, `isEnabled`, `isDisabled`, `isChecked`, `boundingBox`) waits for its one match until the action timeout, then reads once with no retry for a value; `isVisible`, `isHidden`, `count`, `all`, and `allTextContents` answer from the current screen at once. No read verifies an earlier `act`. `textContent` and `allTextContents` collapse each whitespace run to one space and trim, as upstream. A single-node read fails with `LOCATOR_NOT_FOUND` when nothing matches before the action timeout ends - `screen.tree()` and `screen.debug()` (commit `d7ec0ec`) are `Screen.TreeAsync` and `Screen.DebugAsync`. One observation of the whole screen, rendered by `FailureEvidence.Listing` (the trace's screen at failure, upstream's `prepareObservation`): one node per line, children indented, secrets redacted, cut at the observation byte limit (262144). A node the page does not show is left out. A step of kind `screen`. `DebugAsync` writes the text to `Console.Out`, where a test framework picks it up. Differences: `Timeout` bounds the read with a linked token and fails with `OPERATION_TIMEOUT`, where upstream passes it to the engine operation. A `Locator` has no `TreeAsync`, so upstream's refusal on a locator is a compile error. On a `FrameScreen` they refuse with `INVALID_ARGUMENT`, as upstream's do. The same commit's change to print test output without the `list` reporter, and to keep stdout for `--reporter json`, is not ported: the port has no runner. `screen-tree.test.ts` is `ScreenTree/ScreenTreeTests` and `ScreenDebugTests` (not ported: the refusal on a locator, the unknown option, and `sdk-types.ts`'s checks, which a typed API makes compile errors); `screen-tree-secrets.test.ts` is `ScreenTreeSecrets/ScreenTreeTests` (through a session over a fake engine). `run-user-output.test.ts`'s two new cases are not ported with the runner change. diff --git a/src/E2E/Engine/PageScript.cs b/src/E2E/Engine/PageScript.cs index af40c796d..d6ecf4b24 100644 --- a/src/E2E/Engine/PageScript.cs +++ b/src/E2E/Engine/PageScript.cs @@ -733,7 +733,7 @@ internal static class PageScript if (directTexts.has(el)) return directTexts.get(el); let out = ""; for (const child of el.childNodes) { - if (child.nodeType === Node.TEXT_NODE) out += child.nodeValue ?? ""; + if (child.nodeType === 3) out += child.nodeValue ?? ""; } out = out.replace(/\s+/g, " ").trim(); if (out && getComputedStyle(el).getPropertyValue("content-visibility") === "hidden") out = ""; @@ -794,8 +794,8 @@ internal static class PageScript const lineRunOf = (el) => { let out = ""; for (const child of renderedChildrenOf(el)) { - if (child.nodeType === Node.TEXT_NODE) out += child.nodeValue ?? ""; - if (child.nodeType !== Node.ELEMENT_NODE) continue; + if (child.nodeType === 3) out += child.nodeValue ?? ""; + if (child.nodeType !== 1) continue; if (flowsInLine(child)) { out += lineRunOf(child); continue; @@ -854,9 +854,15 @@ internal static class PageScript return labelledBy.get(id) ?? []; }; // Text inside a label of a control, or in an element a role's - // aria-labelledby names, is the labelled element's name already. + // aria-labelledby names, is the labelled element's name already. A + // control with no box carries nothing a person can aim at, so the + // label keeps its text and a text query finds the label. const namesControl = (el) => { - if (el.closest("label")?.control) return true; + const control = el.closest("label")?.control; + if (control) { + const box = control.getBoundingClientRect(); + if (box.width > 0 && box.height > 0) return true; + } if (!el.id || document.getElementById(el.id) !== el) return false; return referencesOf(el.id).some((ref) => { const role = roleOf(ref); @@ -886,7 +892,7 @@ internal static class PageScript const inlineNodesOf = (parent, isHidden) => { const out = []; for (const child of renderedChildrenOf(parent)) { - if (child.nodeType !== Node.ELEMENT_NODE || !flowsInLine(child) || listed(child, roleOf(child))) continue; + if (child.nodeType !== 1 || !flowsInLine(child) || listed(child, roleOf(child))) continue; const text = cut(lineRunOf(child), Infinity); if (text) out.push({ ref: stamp(child), text, hidden: isHidden, attributes: attributesOf(child, false), rect: rectOf(child), children: inlineNodesOf(child, isHidden) }); } diff --git a/src/E2E/Locator/LocatorEngine.cs b/src/E2E/Locator/LocatorEngine.cs index 9b09078ec..223550985 100644 --- a/src/E2E/Locator/LocatorEngine.cs +++ b/src/E2E/Locator/LocatorEngine.cs @@ -430,9 +430,10 @@ internal async Task ResolveExactlyOneAsync(LocatorExpression expre /// /// Performs exactly one action against exactly one enabled match. Stale nodes are re-resolved while the deadline remains; a possibly /// committed action is never repeated. An action that itself names other nodes (dragTo) is built per attempt, so its nodes are - /// re-resolved together with the source. + /// re-resolved together with the source. With a hidden or disabled match is acted on too, as for a scroll into view, + /// which needs no visibility. /// - internal async Task PerformAsync(LocatorExpression expression, Func> build, TimeSpan? timeout, CancellationToken token) + internal async Task PerformAsync(LocatorExpression expression, Func> build, TimeSpan? timeout, CancellationToken token, bool anyState = false) { var started = Clock.GetUtcNow(); var deadline = started + TimeoutOf(timeout); @@ -448,7 +449,7 @@ internal async Task PerformAsync(LocatorExpression expression, Func 0, () => Stopwatch.GetElapsedTime(resolveStamp)).ConfigureAwait(false); rounds++; - if (node is { States.Disabled: false, States.Hidden: false }) + if (node is not null && (anyState || node is { States.Disabled: false, States.Hidden: false })) { var waitedMs = rounds > 1 ? (long)Stopwatch.GetElapsedTime(resolveStamp).TotalMilliseconds : 0; var action = await build(window, token).ConfigureAwait(false); diff --git a/src/E2E/Locator/Screen.cs b/src/E2E/Locator/Screen.cs index 0c9116b58..34db4662a 100644 --- a/src/E2E/Locator/Screen.cs +++ b/src/E2E/Locator/Screen.cs @@ -973,17 +973,17 @@ internal Task> ResolveAsync(CancellationToken cancel /// More than one match fails at once. /// private Task ActAsync(LocatorAction action, ActionOptions? options, CancellationToken cancellationToken) => - ActAsync("locator." + LocatorEngine.ApiName(action), (_, _) => Task.FromResult(action), options, null, () => _screen.Engine.CheckAction(action), cancellationToken); + ActAsync("locator." + LocatorEngine.ApiName(action), (_, _) => Task.FromResult(action), options, null, () => _screen.Engine.CheckAction(action), cancellationToken, anyState: action is LocatorAction.ScrollIntoView); /// /// for an action built once the node is found, with the step's /// label and a check that runs inside the step before the node is resolved. /// - private Task ActAsync(string api, Func> build, ActionOptions? options, string? label, Action? check, CancellationToken cancellationToken) => + private Task ActAsync(string api, Func> build, ActionOptions? options, string? label, Action? check, CancellationToken cancellationToken, bool anyState = false) => _screen.RunStepAsync(StepKind.Locator, api, label ?? Query.Describe(), () => { check?.Invoke(); - return _screen.Engine.PerformAsync(Query, build, options?.Timeout, _screen.Token(cancellationToken)); + return _screen.Engine.PerformAsync(Query, build, options?.Timeout, _screen.Token(cancellationToken), anyState); }); /// @@ -1578,11 +1578,26 @@ private static List Resolve(LocatorExpression query, IReadOnlyList ? candidates : tree.DescendantsOf(Resolve(query.Parent, candidates, tree, includeHidden), candidates); var matches = pool.Where(node => Matches(node, query, includeHidden)).ToList(); - return query.Kind is "text" or "label" ? tree.InnermostOnly(matches) : matches; + return query.Kind switch + { + "text" => tree.InnermostOnly(BoxedFirst(matches)), + "label" => tree.InnermostOnly(matches), + _ => matches, + }; } } } + /// + /// The matches with a box when there are any (a node that reports no Rect counts as boxed). Upstream's web tree lists no node that has no box, so a zero-sized control inside a shown + /// label never stands in for the label as its innermost match; this tree lists such a node, so it is left out here instead. + /// + private static List BoxedFirst(List matches) + { + static bool Boxed(SemanticNode node) => node.Rect is not { Width: <= 0 } and not { Height: <= 0 }; + return matches.Any(Boxed) ? matches.Where(Boxed).ToList() : matches; + } + private static bool UsesDisplayValue(LocatorExpression query) => query.Kind == "displayValue" || (query.Source is not null && UsesDisplayValue(query.Source)) diff --git a/tests/E2E.Tests/LocatorEngine/LocatorEnginePerformContractTests.cs b/tests/E2E.Tests/LocatorEngine/LocatorEnginePerformContractTests.cs index 0122b51e3..9cd93fc13 100644 --- a/tests/E2E.Tests/LocatorEngine/LocatorEnginePerformContractTests.cs +++ b/tests/E2E.Tests/LocatorEngine/LocatorEnginePerformContractTests.cs @@ -85,6 +85,28 @@ public async Task Maps_NOT_ACTIONABLE_to_ACTION_FAILED_without_retrying() Assert.Equal(1, performs); } + [Fact] + public async Task NET_only_sends_the_action_to_a_hidden_node_and_leaves_its_actionability_to_the_engine() + { + // Upstream's performUntil reads no state; Playwright waits for the node to be actionable, and scrollIntoView needs no visibility. + var performed = new List(); + var screen = new Screen( + _ => Task.FromResult(new Observation { Route = "/", Roots = [new SemanticNode { Ref = "node-1", Text = "Hello", States = new NodeStates { Hidden = true } }] }), + (_, action, _) => + { + performed.Add(action); + return Task.CompletedTask; + }, + () => CancellationToken.None, + () => { }, + TimeSpan.FromMilliseconds(300), + TimeSpan.FromMilliseconds(300)); + + await screen.GetByText("Hello").ScrollIntoViewAsync(); + + Assert.IsType(Assert.Single(performed)); + } + [Fact] public async Task Never_sends_an_action_whose_target_resolved_past_the_deadline() { diff --git a/tests/E2E.Tests/LocatorEngine/LocatorEngineVisibleQueriesTests.cs b/tests/E2E.Tests/LocatorEngine/LocatorEngineVisibleQueriesTests.cs index c974a68e3..8ffa696e6 100644 --- a/tests/E2E.Tests/LocatorEngine/LocatorEngineVisibleQueriesTests.cs +++ b/tests/E2E.Tests/LocatorEngine/LocatorEngineVisibleQueriesTests.cs @@ -95,6 +95,20 @@ public async Task Names_the_predicate_in_the_ambiguity_message_when_two_visible_ Assert.Contains("getByText(\"Save\", visible: true)", error.Message, StringComparison.Ordinal); } + [Fact] + public async Task NET_only_a_text_query_resolves_a_shown_label_over_the_zero_sized_control_inside_it() + { + // Upstream's web tree lists no box-less node; this one does, so the text query leaves it out of the innermost pick. + var control = new SemanticNode { Ref = "input", Role = "textbox", Name = "Click me", Rect = new BoundingBox(68, 8, 0, 0) }; + var label = new SemanticNode { Ref = "label", Text = "Click me", Rect = new BoundingBox(8, 8, 60, 18), Children = [control] }; + var tapped = new List(); + var screen = ScreenOver([label], tapped); + + await screen.GetByText("Click me").TapAsync(); + + Assert.Equal(["label"], tapped); + } + /// A locator engine over an engine that answers every locate with , and keeps the expressions it was asked. private static E2E.LocatorEngine EngineAnswering(IReadOnlyList nodes, List expressions) => new(new LocatorEngineOptions { diff --git a/tests/E2E.Tests/PageScriptGlobals/PageScriptGlobalsTests.cs b/tests/E2E.Tests/PageScriptGlobals/PageScriptGlobalsTests.cs new file mode 100644 index 000000000..cf5c7398e --- /dev/null +++ b/tests/E2E.Tests/PageScriptGlobals/PageScriptGlobalsTests.cs @@ -0,0 +1,49 @@ +// Copyright 2026 TesterArmy. +// Modified by Dario Kondratiuk. +// SPDX-License-Identifier: Apache-2.0 + +using E2E.Engine; + +namespace E2E.Tests.PageScriptGlobals; + +/// +/// .NET-only: the page script reads nothing from the page's own globals, so a page that removes one still observes and acts. Upstream's +/// testbed test ('should click the button if window.Node is removed' in click.e2e.ts) checks it through a tap. +/// +[Collection(BrowserCollection.Name)] +public sealed class PageScriptGlobalsTests +{ + [Fact] + public async Task NET_only_observes_a_page_that_deleted_window_Node() + { + await using var session = await new WebEngine(headless: true).StartAsync(new EngineStartOptions(), CancellationToken.None); + await session.OpenAsync("about:blank", CancellationToken.None); + var page = WebEngine.SurfaceOf(session)!.Page(); + await page.SetContentAsync("

Some text

"); + await page.EvaluateAsync("() => { delete window.Node; }"); + + var observation = await session.ObserveAsync(CancellationToken.None); + + var button = Flatten(observation.Roots).First(node => node.Role == "button"); + await session.PerformAsync(button, new LocatorAction.Tap(), CancellationToken.None); + Assert.Equal("yes", await page.EvaluateAsync("() => document.body.dataset.clicked")); + Assert.Contains(Flatten(observation.Roots), node => node.Text == "Some text"); + } + + [Fact] + public async Task NET_only_lists_the_text_of_a_label_whose_control_has_no_box() + { + await using var session = await new WebEngine(headless: true).StartAsync(new EngineStartOptions(), CancellationToken.None); + await session.OpenAsync("about:blank", CancellationToken.None); + var page = WebEngine.SurfaceOf(session)!.Page(); + await page.SetContentAsync(""); + + var found = await session.LocateAsync(LocatorExpression.For("text", "Click me", new TextMatchOptions(), "text"), TimeSpan.FromSeconds(5), CancellationToken.None); + + var label = Assert.Single(found); + Assert.Null(label.Role); + Assert.True(label.Rect is { Width: > 0, Height: > 0 }); + } + + private static IEnumerable Flatten(IEnumerable nodes) => nodes.SelectMany(node => (IEnumerable)[node, .. Flatten(node.Children)]); +}