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. `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 `<label>` text, not its content. A regular expression is tested against that text with whitespace collapsed, where Playwright tests the raw text. 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
8 changes: 4 additions & 4 deletions docs-site/src/content/docs/api/E2E/Screen.md
Original file line number Diff line number Diff line change
Expand Up @@ -108,7 +108,7 @@ public Locator GetByLabel(TextMatch label, TextMatchOptions options)
```


Creates a lazy accessible-label query: any node whose accessible name matches.
Creates a lazy accessible-label query: any node whose accessible name matches. On a web page, a node whose `aria-label`, `aria-labelledby` target, or `<label>` text matches.

**Parameters**

Expand All @@ -129,7 +129,7 @@ public Locator GetByLabel(TextMatch label, bool exact = true)
```


Creates a lazy accessible-label query: any node whose accessible name matches.
Creates a lazy accessible-label query: any node whose accessible name matches. On a web page, a node whose `aria-label`, `aria-labelledby` target, or `<label>` text matches.

**Parameters**

Expand Down Expand Up @@ -303,7 +303,7 @@ public Locator GetByText(TextMatch text, TextMatchOptions options)


Creates a lazy visible-text query. It answers with the innermost match, such as a
`<strong>` inside a paragraph. Text inside a control's label answers with the control.
`<strong>` inside a paragraph. The text of a label answers with the label, not the control it names.

**Parameters**

Expand All @@ -325,7 +325,7 @@ public Locator GetByText(TextMatch text, bool exact = true)


Creates a lazy visible-text query. It answers with the innermost match, such as a
`<strong>` inside a paragraph. Text inside a control's label answers with the control.
`<strong>` inside a paragraph. The text of a label answers with the label, not the control it names.

**Parameters**

Expand Down
7 changes: 5 additions & 2 deletions skills/e2e-dotnet/references/writing-tests.md
Original file line number Diff line number Diff line change
Expand Up @@ -95,8 +95,11 @@ Members of `E2ETest` in both frameworks:
case-insensitive substring, or a .NET `Regex`.
- `GetByText` and `GetByLabel` return the innermost match, so a container
echoing its child does not count twice: `GetByText("$42.00")` finds the
`<strong>` in `<p>Order total: <strong>$42.00</strong></p>`. Text inside a
control's `<label>` answers with the control.
`<strong>` in `<p>Order total: <strong>$42.00</strong></p>`. On a web page,
`GetByText` matches the DOM text only: the `<label>` answers, not the control
it names, and a placeholder, a title, or an `aria-label` is no text.
`GetByLabel` finds a control by its `aria-label`, its `aria-labelledby`
target, or its `<label>`.
- Roles follow HTML-AAM, and `img` aliases `image`. An inline `<svg>` is an
`image`. An `<img alt="">` is decoration and matches nothing, unless it has
a `title`, a `tabindex`, or a global ARIA attribute: then it is an `image`.
Expand Down
13 changes: 13 additions & 0 deletions src/E2E/Engine/Observation.cs
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,19 @@ public sealed class SemanticNode
/// </summary>
internal IReadOnlyList<SemanticNode> InlineNodes { get; init; } = [];

/// <summary>
/// The text of the DOM as Playwright's text engine reads it: every descendant's text in place, with no separator between blocks.
/// Null on a surface with no such text. A web query by text or <c>hasText</c> matches it, in place of <see cref="Name"/> and
/// <see cref="Text"/>, which read the rendered text and the accessible name.
/// </summary>
internal string? DomText { get; init; }

/// <summary>
/// What a label query finds the node by on the web: its <c>aria-label</c>, the elements its <c>aria-labelledby</c> names, and its
/// <c>&lt;label&gt;</c> elements (upstream's <c>labels</c> of a raw node). Null on a surface whose label is its <see cref="Name"/>.
/// </summary>
internal IReadOnlyList<string>? Labels { get; init; }

public string? Value { get; init; }

/// <summary>The text selected inside the focused field or editing host. Null for a caret, an unfocused field, or a secure one.</summary>
Expand Down
Loading
Loading