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 @@ -38,7 +38,7 @@ Names are C# versions of the JavaScript API: `agent.act` is `ActAsync`, `screen.
- 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.
- 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`; `Screen.Reads` is `LocatorEngine.reads`). 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. `Locator.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 (`Locator.PerformWithinAsync`, upstream's `performWithin`). Tests: `Time/PollConditionTests` (the five `pollReads` and `ReadWindow` its), `LocatorWaitFor/ASlowLastReadTests`, `LocatorEngine/LocatorEngineResolveRetryContractTests` (four its) and `LocatorEnginePerformContractTests` ('never sends an action whose target resolved past the deadline'), and `ScreenshotAssertions/ToHaveScreenshotTests` (the two capture-timeout its).
- 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))
- Locator expectations: visible, hidden, attached, enabled, disabled, checked, selected, expanded, focused, text, contained text, value, attribute, accessible name, and count. They poll until the assertion timeout, or the matcher's own `timeout`. `Not` inverts a matcher, which then passes after 1000 ms of continuous truth (or the whole budget when it is shorter). Text matchers take the same `TextMatch` as queries, `ignoreCase`, and a list form. The boolean flags are `visible`, `attached`, `enabled`, and `isChecked` (`checked` is a C# keyword)
- `toHaveScreenshot` as `Expect.That(Screen).ToHaveScreenshotAsync(name, options)` and the same on a locator, with `Not` and `Expect.Soft(locator)`; see [Visual comparison](#visual-comparison)
Expand Down Expand Up @@ -120,7 +120,7 @@ Names are C# versions of the JavaScript API: `agent.act` is `ActAsync`, `screen.

## Error codes that differ

A locator reports an engine failure as upstream's `translateLocatorError` (`LocatorResolver.TranslateLocatorError`, over `ErrorSerializer.TranslateEngineError`, upstream's `translateEngineError`, `internal/errors.ts`) does, with the engine error as `InnerException` and the locator's description added to the message (#846): `NOT_ACTIONABLE` and `ACTION_MAY_HAVE_COMMITTED` are `ACTION_FAILED`, `OPERATION_TIMEOUT` is `ACTION_FAILED` (`operation timed out: <locator>`), `NODE_STALE` and `FRAME_NOT_FOUND` are `LOCATOR_NOT_FOUND`, `FRAME_AMBIGUOUS` is `LOCATOR_AMBIGUOUS`, and `INVALID_STATE` is `APP_NOT_OPEN`. `CANCELLED` is an `EngineException` of that code (`operation cancelled`), `UNSUPPORTED_CAPABILITY` is a `ConfigurationException` (category `configuration`), and `ENGINE_FAILURE`, any other engine code, and an error that is no e2e error are an `EngineException` `ENGINE_FAILURE` (category `infrastructure`), each with the original error as `InnerException`, as upstream's `translateEngineError` wraps them (#885). Differences: an `OperationCanceledException` is returned as it is, so a caller's cancel stays a cancel. The port applies the translation to the locator's resolve (including the resolve over an observation) and to its actions; it has no read by reference to translate. An action whose engine call finds a retryable stale node resolves the locator again and repeats the action while its deadline remains, as upstream's `performUntil` does; an action that may have committed is never repeated. An action whose deadline passed before it was sent is not sent: it fails with `ACTION_FAILED` (`operation timed out before the tap was sent: <locator>`), as upstream's `lateAction` (#869). Tests: `LocatorEngine/TranslateLocatorErrorMappingTableTests` (the `translateLocatorError mapping table` describe; the seven rows with the port's codes are `Partial_`) and the perform `it`s of `LocatorEngine/LocatorEnginePerformContractTests`. All six perform `it`s are ported; `marks every action it performs with the test origin` is `Partial_`: the port has no `LocatorEngine` class, so it checks the origin at the session a `Screen` step reaches (`OriginRecordingEngine`) and not at the `LocatorEngine` that adds it.
A locator reports an engine failure as upstream's `translateLocatorError` (`LocatorEngine.TranslateLocatorError`, over `ErrorSerializer.TranslateEngineError`, upstream's `translateEngineError`, `internal/errors.ts`) does, with the engine error as `InnerException` and the locator's description added to the message (#846): `NOT_ACTIONABLE` and `ACTION_MAY_HAVE_COMMITTED` are `ACTION_FAILED`, `OPERATION_TIMEOUT` is `ACTION_FAILED` (`operation timed out: <locator>`), `NODE_STALE` and `FRAME_NOT_FOUND` are `LOCATOR_NOT_FOUND`, `FRAME_AMBIGUOUS` is `LOCATOR_AMBIGUOUS`, and `INVALID_STATE` is `APP_NOT_OPEN`. `CANCELLED` is an `EngineException` of that code (`operation cancelled`), `UNSUPPORTED_CAPABILITY` is a `ConfigurationException` (category `configuration`), and `ENGINE_FAILURE`, any other engine code, and an error that is no e2e error are an `EngineException` `ENGINE_FAILURE` (category `infrastructure`), each with the original error as `InnerException`, as upstream's `translateEngineError` wraps them (#885). Differences: an `OperationCanceledException` is returned as it is, so a caller's cancel stays a cancel. The port applies the translation to the locator's resolve (including the resolve over an observation) and to its actions; it has no read by reference to translate. `LocatorEngine` (`Locator/LocatorEngine.cs`, upstream's `locator/engine.ts`, #994) owns the resolve, the retries, the deadlines, the engine events, and the operation context a call carries (`OperationContext.Test`); `Screen` and `Locator` pass it their query. Differences: its session is the set of calls in `LocatorEngineOptions` (.NET-only: the attempt reads the screen through its scope), a locate answers the nodes themselves so `read`, `readNow`, `readAllNow`, and `tryRead` read a resolve and have no `session.read` to go stale, `fillSecret` and `pressSequentially` are not engine methods (a secret fill and a typed text are engine actions), and `DeadlineFor` is upstream's `deadline` (`Deadline` is the type's name). `LocatorEngine/` ports the `read retry`, `resolve retry`, `perform`, `readAllNow`, `reads that do not wait`, `translateLocatorError`, `visible queries`, and `isNodeVisible` describes; not ported: the its that need `session.read` to go stale (read retry 1 to 3, read contract, readAllNow stale and failure, readNow stale between resolve and read), `secret fill` (no engine `fillSecret`), `AttemptBudget.capped` (no `AttemptBudget`), the cross-realm describe (no second module registry in .NET), and the `locator failure candidate counts` describe (#1001). An action whose engine call finds a retryable stale node resolves the locator again and repeats the action while its deadline remains, as upstream's `performUntil` does; an action that may have committed is never repeated. An action whose deadline passed before it was sent is not sent: it fails with `ACTION_FAILED` (`operation timed out before the tap was sent: <locator>`), as upstream's `lateAction` (#869). Tests: `LocatorEngine/TranslateLocatorErrorMappingTableTests` (the `translateLocatorError mapping table` describe; the seven rows with the port's codes are `Partial_`) and the perform `it`s of `LocatorEngine/LocatorEnginePerformContractTests`. All six perform `it`s are ported; `marks every action it performs with the test origin` runs on the `LocatorEngine` itself (`ScriptedLocatorEngine`, upstream's `makeEngine`), and a .NET-only test checks that `E2ESession` wires that origin to the engine a test's step reaches (`OriginRecordingEngine`).

## Locator actions

Expand Down
6 changes: 3 additions & 3 deletions src/E2E/Expect/ScreenshotCapture.cs
Original file line number Diff line number Diff line change
Expand Up @@ -42,11 +42,11 @@ private Task<T> ReadAsync<T>(Func<TimeSpan, CancellationToken, Task<T>> read, Ca
catch (Exception ex) when (bounded.IsCancellationRequested && !cancellationToken.IsCancellationRequested
&& (ex is OperationCanceledException || ex is EngineException { Code: EngineErrorCodes.OperationTimeout or EngineErrorCodes.Cancelled } || ex.InnerException is OperationCanceledException))
{
throw LocatorResolver.TranslateLocatorError(new EngineException(EngineErrorCodes.OperationTimeout, "the screenshot outlived its budget", retryable: false, ex));
throw LocatorEngine.TranslateLocatorError(new EngineException(EngineErrorCodes.OperationTimeout, "the screenshot outlived its budget", retryable: false, ex));
}
catch (EngineException ex) when (ex.Code == EngineErrorCodes.OperationTimeout)
{
throw LocatorResolver.TranslateLocatorError(ex);
throw LocatorEngine.TranslateLocatorError(ex);
}
});

Expand All @@ -62,7 +62,7 @@ public async Task<Capture> CaptureAsync(CancellationToken cancellationToken)
{
try
{
await screen.PerformAsync(node, new LocatorAction.ScrollIntoView(), cancellationToken).ConfigureAwait(false);
await screen.Engine.SessionPerformAsync(node, new LocatorAction.ScrollIntoView(), cancellationToken).ConfigureAwait(false);
}
catch (Exception ex) when (ex is EngineException { Code: EngineErrorCodes.NodeStale } or TestException { Code: "LOCATOR_NOT_FOUND" })
{
Expand Down
Loading
Loading