Skip to content
Merged
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
2 changes: 1 addition & 1 deletion COMPATIBILITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
18 changes: 12 additions & 6 deletions src/E2E/Engine/PageScript.cs
Original file line number Diff line number Diff line change
Expand Up @@ -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 = "";
Expand Down Expand Up @@ -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;
Expand Down Expand Up @@ -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);
Expand Down Expand Up @@ -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) });
}
Expand Down
7 changes: 4 additions & 3 deletions src/E2E/Locator/LocatorEngine.cs
Original file line number Diff line number Diff line change
Expand Up @@ -430,9 +430,10 @@ internal async Task<SemanticNode> ResolveExactlyOneAsync(LocatorExpression expre
/// <summary>
/// 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 <paramref name="anyState"/> a hidden or disabled match is acted on too, as for a scroll into view,
/// which needs no visibility.
/// </summary>
internal async Task PerformAsync(LocatorExpression expression, Func<Deadline, CancellationToken, Task<LocatorAction>> build, TimeSpan? timeout, CancellationToken token)
internal async Task PerformAsync(LocatorExpression expression, Func<Deadline, CancellationToken, Task<LocatorAction>> build, TimeSpan? timeout, CancellationToken token, bool anyState = false)
{
var started = Clock.GetUtcNow();
var deadline = started + TimeoutOf(timeout);
Expand All @@ -448,7 +449,7 @@ internal async Task PerformAsync(LocatorExpression expression, Func<Deadline, Ca
{
var node = await ResolveCountedAsync(expression, token, reads, sampled: rounds > 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);
Expand Down
23 changes: 19 additions & 4 deletions src/E2E/Locator/Screen.cs
Original file line number Diff line number Diff line change
Expand Up @@ -973,17 +973,17 @@ internal Task<IReadOnlyList<SemanticNode>> ResolveAsync(CancellationToken cancel
/// More than one match fails at once.
/// </summary>
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);

/// <summary>
/// <see cref="ActAsync(LocatorAction, ActionOptions, CancellationToken)"/> 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.
/// </summary>
private Task ActAsync(string api, Func<Deadline, CancellationToken, Task<LocatorAction>> build, ActionOptions? options, string? label, Action? check, CancellationToken cancellationToken) =>
private Task ActAsync(string api, Func<Deadline, CancellationToken, Task<LocatorAction>> 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);
});

/// <summary>
Expand Down Expand Up @@ -1578,11 +1578,26 @@ private static List<SemanticNode> 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,
};
}
}
}

/// <summary>
/// The matches with a box when there are any (a node that reports no <c>Rect</c> 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.
/// </summary>
private static List<SemanticNode> BoxedFirst(List<SemanticNode> 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))
Expand Down
22 changes: 22 additions & 0 deletions tests/E2E.Tests/LocatorEngine/LocatorEnginePerformContractTests.cs
Original file line number Diff line number Diff line change
Expand Up @@ -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<LocatorAction>();
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<LocatorAction.ScrollIntoView>(Assert.Single(performed));
}

[Fact]
public async Task Never_sends_an_action_whose_target_resolved_past_the_deadline()
{
Expand Down
14 changes: 14 additions & 0 deletions tests/E2E.Tests/LocatorEngine/LocatorEngineVisibleQueriesTests.cs
Original file line number Diff line number Diff line change
Expand Up @@ -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<string>();
var screen = ScreenOver([label], tapped);

await screen.GetByText("Click me").TapAsync();

Assert.Equal(["label"], tapped);
}

/// <summary>A locator engine over an engine that answers every locate with <paramref name="nodes"/>, and keeps the expressions it was asked.</summary>
private static E2E.LocatorEngine EngineAnswering(IReadOnlyList<SemanticNode> nodes, List<LocatorExpression> expressions) => new(new LocatorEngineOptions
{
Expand Down
Loading
Loading