diff --git a/COMPATIBILITY.md b/COMPATIBILITY.md index e8203cc78..0e26d8051 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. `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 +- 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. 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 `