From 412a0a8317a3b2968d109137aa0391db234f98e4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dar=C3=ADo=20Kondratiuk?= Date: Wed, 4 Nov 2026 19:47:25 -0300 Subject: [PATCH 1/2] Match text and labels on the DOM, as Playwright does (Closes #1072, Closes #1073, Closes #1074) The web engine answered getByText with the control of a label and with a placeholder, found no text inside a button, and joined adjacent blocks with a space. Text now reads the DOM text, a label query reads the label sources, and a leaf lists its inline text. The three ported tests run as upstream wrote them. Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01Ls2e1yaZFgZ3FEJkYScfkK --- COMPATIBILITY.md | 2 +- docs-site/src/content/docs/api/E2E/Screen.md | 8 +- skills/e2e-dotnet/references/writing-tests.md | 7 +- src/E2E/Engine/Observation.cs | 13 +++ src/E2E/Engine/PageScript.cs | 76 ++++++++++-------- src/E2E/Engine/WebEngine.cs | 6 ++ src/E2E/Locator/Screen.cs | 25 ++++-- .../LocatorQuery/LocatorQueryTests.cs | 13 +-- .../SelectorsGetBy/SelectorsGetByTests.cs | 57 ++++++------- tests/E2E.Tests/TextQuery/TextQueryTests.cs | 79 +++++++++++++++++++ 10 files changed, 194 insertions(+), 92 deletions(-) create mode 100644 tests/E2E.Tests/TextQuery/TextQueryTests.cs diff --git a/COMPATIBILITY.md b/COMPATIBILITY.md index d5038a4d4..74a5bbf59 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. `getByLabel` matches any node whose accessible name matches, as the upstream reference resolver does. On the web, upstream resolves text, label, and `hasText` through Playwright on the real DOM, and the port reads the same things off its tree: `getByText` and `hasText` match the element's DOM text (every descendant's text in place, no separator between two blocks, a button input's value, script and style text left out), so a placeholder, a title, an `aria-label`, or the control a label names is no text, and the label itself answers; `getByLabel` matches the node's `aria-label`, the elements its `aria-labelledby` names, and its `