diff --git a/COMPATIBILITY.md b/COMPATIBILITY.md index 988541af1..7584ecdae 100644 --- a/COMPATIBILITY.md +++ b/COMPATIBILITY.md @@ -122,7 +122,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` (`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: `), `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`, `isNodeVisible`, and `locator failure candidate counts` (`LocatorFailureCandidateCountsTests`) 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`), and the cross-realm describe (no second module registry in .NET). A filtered locator that matches nothing or too many lists the candidates each filter step left (tester-army/e2e#1416, `79e2e13d3365`): `LocatorExpression.FilterSpine()` is `filterSpine` (`locator/expression.ts`), and `LocatorEngine.CandidateCountsAsync` is `candidateCounts`, read by `NotFoundAsync` (`notFound` in `resolveCounted`) and `AmbiguousAsync` (`singleOf`, which replaces `assertSingle`), one immediate resolve per prefix of the chain under one 500 ms budget (`StepCountBudget`, `STEP_COUNT_BUDGET_MS`; `Deadline.Min` is `Deadline.min`). A walk that cannot finish says `walk stopped after N of M steps`, a read that fails drops the list, and a cancel surfaces as cancellation. Differences: the port's failure messages are its own (` matched 0 nodes.`), so the list follows on a new line (`candidates left after each filter step, counted after the failure:`) where upstream continues after `; `. The five `filterSpine` its are in `Expression/LocatorExpressionsTests`. 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: `), 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`). +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: `), `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). A recorded browser step maps the engine error it throws the same way (a `Browser` outside a session runs the call bare, like the surface upstream's engine tests call; `Browser.Translated`, upstream's `translated` in `run/fixture-recording.ts`), with ` in