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
4 changes: 2 additions & 2 deletions COMPATIBILITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ Names are C# versions of the JavaScript API: `agent.act` is `ActAsync`, `screen.
- `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. 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
- 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 (`inputValue` on a node with no value, such as a heading or a button, and `isChecked` on a node with no checked state fail with `ACTION_FAILED`, as upstream, tester-army/e2e#1552 `d2556bc`; a field with no value reads `""`, and a checkable role with no state reported reads `false`. The port reads the state through `NodeStates.CheckedReported`, which `Checked` sets, where upstream reads `states.checked !== undefined` (.NET-only); the web engine reports it for a native checkbox or radio and any `aria-checked` node, the mobile engine when the platform spells a state, and the Windows engine for a toggle state or a radio); `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.
- The last read of a wait gets grace (`fix: give the last read of a wait the time of the slowest one`, `57f9ed9`, tester-army/e2e#1464). `Locator.WaitForAsync`, a locator `Expect`, and `ToHaveScreenshotAsync` read through a `ReadWindow` (`Internal/Time.cs`, upstream's `ReadWindow` in `internal/time.ts`; `LocatorEngine.Reads` is upstream's `LocatorEngine.reads`; `Screen.Reads` forwards to it). Each engine locate runs until the wait's deadline plus the slowest read the wait finished (the budget `IEngineSession.LocateAsync` gets), capped by the test timeout (`Screen.BudgetDeadline`, upstream's `budget.deadline`), so a screen that shows up during a slow last read passes. `Time.PollReadsAsync` is `pollReads`, and `PollConditionAsync` is `pollCondition` over a window with no cap. A read the deadline cut off is `ReadWindow.CutOff`: an `OPERATION_TIMEOUT` of a read that started with under one poll tick, or under the slowest read, left (it replaces `cutOffAtDeadline`). A negation counts as held only until the deadline. `LocatorEngine.ResolveExactlyOneAsync` and the other waiting resolves end a wait whose last read was cut off after a read that found nothing as `LOCATOR_NOT_FOUND`, not as `ACTION_FAILED`, and a retry the deadline cut off ends on the failure it was retrying (upstream's `resolveCounted` and `resolveOnce`). An action whose deadline passed before it was sent fails with `ACTION_FAILED` (upstream's `lateAction`). A capture of `ToHaveScreenshotAsync` that outlives its budget is an `OPERATION_TIMEOUT` the poll judges as it judges any read; the message of a failure with no capture is `the last screenshot ran past the timeout`. Differences: the port polls every 50 ms in the locator and 100 ms in screenshots where upstream polls every 100 ms. An engine is handed the read's budget by `IEngineSession.LocateAsync`, `ObserveAsync(TimeSpan, CancellationToken)`, and `ScreenshotAsync(TimeSpan, CancellationToken)` (see the operation budget bullet in the mobile section); an engine that does not override the last two (the web and WinApp engines) drops it, so the window only times its read (a screenshot is cancelled at its budget). `Locator.WaitForAsync` fails with `LOCATOR_NOT_FOUND`, as upstream. A positioned tap whose target became visible past the deadline is `ACTION_FAILED` too (`LocatorEngine.PerformWithinAsync`, upstream's `performWithin`). Tests: `Time/PollConditionTests` (the five `pollReads` and `ReadWindow` its), `LocatorWaitFor/ASlowLastReadTests`, `LocatorEngine/LocatorEngineResolveRetryContractTests` and `LocatorEnginePerformContractTests` ('never sends an action whose target resolved past the deadline'), and `ScreenshotAssertions/ToHaveScreenshotTests` (the two capture-timeout its).
- `locator.waitFor` with `attached`, `detached`, `visible` (default), and `hidden`, as `WaitForAsync(new LocatorWaitForOptions { State, Timeout })`. The timeout defaults to the action timeout. `LocatorWaitForOptions` is named apart from `agent.waitFor`'s `WaitForOptions`. A timeout fails with `LOCATOR_NOT_FOUND` (`locator did not become <state>: <locator>`), and a passing `waitFor` verifies an earlier `act`, as upstream (`verifies: true` is `Screen.NotifyVerified`). The timeout carries `Details` as upstream's does (the locator, what it asked for, and how long it waited; see [Trace page](#trace-page))
Expand Down Expand Up @@ -757,7 +757,7 @@ The tree is a subset of upstream's: names follow upstream's accname rules, and n

A web screenshot (`toHaveScreenshot`, failure evidence) hides the text caret with a stylesheet adopted into every frame and shadow root, closed ones included, and takes it back afterwards, as upstream's `screenshot-caret.ts`; Playwright's `caret: 'hide'` would write an inline `caret-color` a hydrating framework reads as a mismatch. It works under a `style-src` policy. The port has one web screenshot path, so there is no separate observation-pixels capture. Not ported: upstream's `leaves the caret to the adopted stylesheet instead of editing element styles` (`observe.test.ts`) and the frame stubs added to `observation-capture.test.ts` and `semantic-fallback.test.ts`, which fake `page.screenshot` and `page.frames()`; the port has no fake page. The three `screenshot-caret.test.ts` tests are `Partial_`: Playwright's page cannot be spied on, so they sample the page inside the helper, not inside the engine's own capture.

The snapshot leaves out a checkbox's or radio's value, which `inputValue` still reads (`on` by default).
The snapshot leaves out a checkbox's or radio's value, which `inputValue` still reads (`on` by default). `uncheck` on a checked native radio is `NOT_ACTIONABLE`; on a `role="radio"` it clicks, as upstream and Playwright, and the failure when the click leaves it checked names the radio group.

The page script reads the text selected inside the focused input, textarea, or `contenteditable` host into `SemanticNode.Selection`, as upstream does. A caret, an unfocused field, and a secure field have none. The agent snapshot lists it as `selection="..."` after the field's value, verbatim and escaped (a lone space counts, an empty selection does not), as upstream does. The runner drops it from a field whose value or text holds a registered secret, and from a field cut at its length limit when the selection is not in the part shown. Differences: the port's `press` has no `times`, so one call presses the key once; and the snapshot shows a `value` as it is, a newline included, where upstream escapes it.

Expand Down
17 changes: 17 additions & 0 deletions docs-site/src/content/docs/api/E2E.Engine/NodeStates.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,23 @@ public bool Checked { get; init; }
```


**Value:** [bool](https://learn.microsoft.com/dotnet/api/system.boolean)

<a id="E2E_Engine_NodeStates_CheckedReported_"></a>
<a id="E2E_Engine_NodeStates_CheckedReported"></a>

### CheckedReported


```csharp
public bool CheckedReported { get; init; }
```


The platform reported a checked state for the node, true or false. Setting [Checked](#E2E_Engine_NodeStates_Checked) reports it; a node with none
(a button, a heading) leaves it false, and `IsChecked` fails on it unless its role carries a checked state. List it after
[Checked](#E2E_Engine_NodeStates_Checked) in an initializer to override that (.NET-only; upstream reads the state as nullable).

**Value:** [bool](https://learn.microsoft.com/dotnet/api/system.boolean)

<a id="E2E_Engine_NodeStates_Disabled_"></a>
Expand Down
8 changes: 5 additions & 3 deletions docs-site/src/content/docs/api/E2E/Locator.md
Original file line number Diff line number Diff line change
Expand Up @@ -818,9 +818,9 @@ public Task<string> InputValueAsync(CancellationToken cancellationToken = defaul
```


Waits up to the action timeout for one match, then reads an input value once, the empty string when the node has none. Does not retry for a value and does not verify an earlier `act`. A checkbox or
Waits up to the action timeout for one match, then reads an input value once, the empty string for a field with none. Does not retry for a value and does not verify an earlier `act`. A checkbox or
radio reads its value attribute, `on` when it has none, whatever its checked state. Fails with
`POLICY_DENIED` on a secure field.
`POLICY_DENIED` on a secure field, and with `ACTION_FAILED` on a node with no value, such as a heading or a button.

**Parameters**

Expand All @@ -841,7 +841,7 @@ public Task<bool> IsCheckedAsync(CancellationToken cancellationToken = default)
```


Waits up to the action timeout for one match, then reads its checked state once.
Waits up to the action timeout for one match, then reads its checked state once. A checkable role with no state reported reads false. Fails with `ACTION_FAILED` on a node with no checked state, such as a button or a heading.

**Parameters**

Expand Down Expand Up @@ -1363,6 +1363,8 @@ public Task UncheckAsync(ActionOptions? options = null, CancellationToken cancel
```


Unchecks a checkbox, switch, or `role="radio"` with one click. A checked native radio button fails with `ACTION_FAILED`: only another radio in its group clears it.

**Parameters**

| Name | Type | Description |
Expand Down
2 changes: 1 addition & 1 deletion docs-site/src/content/docs/docs/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -123,7 +123,7 @@ await Screen.GetByTestId("feed").ScrollUntilVisibleAsync(row, new ScrollUntilVis

## Errors

A locator reports an engine failure in the test's own codes, with the engine's error as `InnerException`: `NOT_ACTIONABLE`, `ACTION_MAY_HAVE_COMMITTED`, and `OPERATION_TIMEOUT` are `ACTION_FAILED`, a stale node or a missing frame is `LOCATOR_NOT_FOUND`, an ambiguous frame is `LOCATOR_AMBIGUOUS`, and `INVALID_STATE` is `APP_NOT_OPEN`. `CANCELLED` and `ENGINE_FAILURE` keep their codes (category `infrastructure`), and `UNSUPPORTED_CAPABILITY` is a `ConfigurationException`. A `locator.WaitForAsync` that runs out fails with `LOCATOR_NOT_FOUND` (`locator did not become <state>: <locator>`), not `TIMEOUT`, and a pass verifies the acts before it. A stale node found by an action is looked up again, within the action timeout, before the action fails.
A locator reports an engine failure in the test's own codes, with the engine's error as `InnerException`: `NOT_ACTIONABLE`, `ACTION_MAY_HAVE_COMMITTED`, and `OPERATION_TIMEOUT` are `ACTION_FAILED`, a stale node or a missing frame is `LOCATOR_NOT_FOUND`, an ambiguous frame is `LOCATOR_AMBIGUOUS`, and `INVALID_STATE` is `APP_NOT_OPEN`. `ACTION_FAILED` is also what `InputValueAsync()` throws on a node with no value (a heading, a button) and `IsCheckedAsync()` on a node with no checked state; a field with no value still reads `""`, and a checkable role with no state reported still reads `false`. `CANCELLED` and `ENGINE_FAILURE` keep their codes (category `infrastructure`), and `UNSUPPORTED_CAPABILITY` is a `ConfigurationException`. A `locator.WaitForAsync` that runs out fails with `LOCATOR_NOT_FOUND` (`locator did not become <state>: <locator>`), not `TIMEOUT`, and a pass verifies the acts before it. A stale node found by an action is looked up again, within the action timeout, before the action fails.

When a filtered locator (a chain with at least one `Filter(...)`, and any `First()` or `Nth(n)` after it) matches nothing or too many, the `LOCATOR_NOT_FOUND` or `LOCATOR_AMBIGUOUS` message ends with `candidates left after each filter step, counted after the failure:` and one line per step, innermost first, with the locator so far and how many nodes it left. A step that narrowed too much or too little names itself. The counts come from one extra read per step after the failure, so a page that changed since can disagree with the failing attempt. All the reads share one 500 ms budget: a chain that cannot finish says `walk stopped after N of M steps`, and a read that fails leaves the list out. A locator without a filter step gets no list.

Expand Down
Loading
Loading