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
1 change: 1 addition & 0 deletions COMPATIBILITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -410,6 +410,7 @@ The port installs the skill with `npx skills add hardkoded/e2e-dotnet` and regis
- Upstream's known-viewport fix (`fix(mobile): keep the known viewport when the app reads smaller than the screen`, `7674a2c`, tester-army/e2e#1291) is ported. `DeviceSession.Project` learns a snapshot's viewport only when it is plainly the screen's: the first one the session reads, the one it knows, or that one rotated (`SameScreen`, upstream's `sameScreen`; two sizes within a point are one screen, since rects from the tree carry fractions). `ViewportForAsync` (upstream's `viewportFor`) checks a tree of any other size against the device's screenshot, in either orientation, before it replaces the known one: a screenshot reports the portrait size even in landscape, so it confirms a size but cannot pick the orientation. The size it checks against is `DeviceSupport.LogicalScreenSize` (upstream's `logicalScreenSize`): the screenshot's logical dimensions, else its pixel dimensions over its density. A simulator's screenshot reports those; a real device's reports neither, so there the tree's size is taken as it comes. A screenshot that fails during that check fails the observation, as upstream's does. `TraceScreen` and `MaskedScreenshotAsync` size the trace screen and the secure-field masks by the known viewport, not the tree's. On iOS, a swipe from a sheet's grabber can pull down Notification Center, and the app's tree behind it reported a third of the screen (130x281 on a 390x844 device), which misplaced every rect and tap after it. Upstream records this only in its changeset; its skill references and docs say nothing about it, so `SKILL.md` and `docs/` have nothing to mirror. Tests: in `Engine/ObservationTests`, 'keeps the known viewport for an app drawn smaller than the screen, and follows a rotation' (new) and 'measures the screen in the viewport the snapshot publishes, and in its tree when it publishes none' (split into two harnesses, as upstream's); in `Engine/DeviceFixtureDismissingAKeyboardThatHasNoDismissKeyTests`, 'drags at the centre of a screen rotated since the last observation' (new), since the keyboard drag measures its start through `ViewportForAsync` too.
- Upstream's input budget (`fix(mobile): bound each input by its budget`, `14b77d3`, tester-army/e2e#1073) is ported. An input (a tap or other node action, a point action, typing, a key, `back`, a keyboard dismissal, and the node `LongPressAsync`, `HoverAsync`, `DragToAsync`, and `SwipeAsync` the port has in place of upstream's `longPress`, `hover`, `dragTo`, and `swipe` actions) runs its device commands under `InputBudget` (`DeviceSupport.cs`, upstream's `support.ts`): with no budget left the input is not sent and fails with `OPERATION_TIMEOUT`, an input that does not answer in time fails with `ACTION_MAY_HAVE_COMMITTED`, one sent with almost no budget left still gets 250 ms to answer, a hold (a long press or timed swipe) at least as long as the budget left is refused with `NOT_ACTIONABLE`, and each command of a multi-command input (a key on an unfocused field) is sent on its own. Launches and artifacts are unbounded. Snapshots are bounded since #869 (see the next bullet). Differences: upstream reads the budget per call, from `operation.timeoutMs`, which is the call's `timeout` or `actionTimeout`. The port's session calls carry no timeout, so every input gets `DeviceSession.ActionTimeout`, which `MobileStartInfo.ActionTimeout` sets (`EngineStartOptions.ActionTimeout` fills it), as the web engine's operations get the action timeout. `DeviceSession.InputBudget` is upstream's `inputBudget` and `DeviceSession.SendInputAsync` its `sendInput`. `InputBudget`'s `track` is an `Action<Task>` that registers the task (upstream's returns the promise it is given); see [In-flight commands](#in-flight-commands). The `OperationContext.signal` doc change in `docs/reference/engine.mdx` and `contract.ts` has no counterpart: the port has no `OperationContext`. Tests: in `Engine/ObservationTests`, 'ends %s, hung on %s, at its budget as possibly committed' (a theory of the same seven entries; the screen swipe is a `perform` on the root), 'sends nothing once a settling target spent the budget, and no keystroke once a focus tap used it up', and 'refuses a long press that holds longer than its timeout leaves, before sending it' (also on the node `LongPressAsync`); in `Support/SupportHelpersTests`, 'sends an input with what is left of its budget, and reports one cut off as possibly committed'. These run on real timers of a few hundred milliseconds, where upstream's fake timers do not wait. 'lets a locate outlive its budget' was replaced in #869.
- Upstream's Compose Multiplatform text fields on iOS (`mobile reads Compose Multiplatform text fields on iOS`, `75ae2ab`, tester-army/e2e#1427) are ported in part. `SnapshotProjection.ProjectSnapshot` reads the placeholder an empty iOS field folds into its label (upstream's `foldedPlaceholder` in `nodes.ts`, `FoldedPlaceholder` here): for an empty (no value), editable, non-secure iOS field that reports no placeholder of its own, whose only child is a `StaticText` with no children, and whose label is a non-empty name, then `, `, then that child's text, that text is the field's `Placeholder`, the child is left out of the tree, and the name is the label before `, ` (a non-empty `ContentDescription` stays the name, and that label is then the `Text`). A field of any other shape keeps its label and children as reported. The private record `Folded` is a .NET-only name for upstream's inline `{ label, placeholder, child }` object. Test: 'reads the placeholder an empty Compose Multiplatform field folds into its label' in `Nodes/SnapshotProjectionTests`. `mayTakeText` and `NodeBinding.takesText` (`nodes.ts`, `surface.ts`) are ported (#850): `SnapshotProjection.MayTakeText` and `NodeBinding.TakesText`, set in `Bind` from the node with its children. `DeviceActions.PerformAsync` refuses a `fill` or `clear` whose node does not take text with `UNSUPPORTED_CAPABILITY` (the message of upstream's `refuseFill`, `RefuseFill` here), before the action and again on the binding found by a fresh snapshot taken just before typing (upstream's `relocated`; `DeviceSession.RelocatedAsync`, with the transition wait split out as `WaitForTransitionAsync`, upstream's `waitForTransition`). Tests: 'Acts_on_an_unclassified_iOS_field', 'Rejects_an_unclassified_iOS_element', and 'Rejects_an_unclassified_iOS_element_that_gained_a_control_before_typing' in `Engine/InputFreshnessTests`. Differences: a fill or clear now reads the field again, so it costs one more `capture.snapshot` than before. Upstream's `relocated` `input` flag is ported with #751.
- Upstream's screen swipe transition wait (`fix(mobile): wait for transitions before screen swipes`, `f45d9f8`, tester-army/e2e#1564) is ported. A test's screen swipe (`OperationContext.Test`) waits out the remaining `TransitionMilliseconds` budget before it scrolls, through `DeviceSession.WaitOutTransitionAsync` (upstream's `waitOutTransition`), which is capped by the input's own budget and throws `OPERATION_TIMEOUT` rather than send a scroll the transition cannot finish for. `WaitForTransitionAsync` and `SettledAsync` take that budget too, so an arriving control's wait is capped the same way. Tests: the screen-swipe `it`s in `Engine/DeterministicActionsTests` (the tight-budget ones observe no screen root, since the first look of a session is real-time and can outlast a sub-frame budget; they use the screen root's ref directly, which the swipe needs), and 'gives a screen swipe the remaining transition budget after an alert is dismissed' in `Engine/DeviceFixtureTests`. One upstream `it` is partial: 'does not send a 20 ms or 20.5 ms capped screen swipe when its timer wakes before the wall-clock deadline' depends on a `Date.now` mock that lags the timer, which the port's fake clock has no equivalent of, so the port's `Partial_Does_not_send_a_capped_screen_swipe_the_transition_outlasts` checks only that the capped swipe is not sent.
- Upstream's mobile input revalidation (`fix(mobile): revalidate input bindings before fill and clear`, `b309bcd`, tester-army/e2e#1410) and keyboard transitions (`fix(mobile): reobserve targets after keyboard transitions`, `bdd7315`, tester-army/e2e#1297) are ported. `DeviceSession.RelocatedAsync` takes `forInput` (upstream's `input` flag of `relocated`; `input` is the `InputBudget` here). With it, a truncated or sparse capture, a node the capture no longer lists, or a changed `InputPurpose`, `Disabled`, `Secure`, or `Hidden` is a retryable `NODE_STALE` before anything is typed, and `DeviceActions.PerformAsync` sets it for `fill` and `clear`. `ProjectedSnapshot.KeyboardVisible` (set in `Project` from `KeyboardShowing`) and `NodeBinding.KeyboardVisible` stand for upstream's `ProjectedScreen` type (`ProjectedSnapshot & { keyboardVisible }`), which C# has no intersection type for. `LatestScreen` and `MarkAction(ProjectedSnapshot?)` replace `LatestIndex` and the index-based `MarkAction` (upstream's `latestScreen` and `markAction(before: ProjectedScreen)`), and `WaitForTransitionAsync` acts at once on an unmoved control only when the keyboard state of the screen before the action equals the control's. `DeviceErrors.StaleOr` also maps `target_still_moving` with `details.dispatched: no` to a retryable `NODE_STALE`. The `agent-input-stale.test.ts` file of #1410 is already ported in part (`AgentInputStale/SecretFillStaleRetryTests`); its replay half still needs a project runner, `credentials`, and the `secret.fill` policy event, which the port lacks. Tests: the `input freshness` `it`s in `Engine/InputFreshnessTests`, the three keyboard `it`s in `Engine/DeterministicActionsTests`, and 'retries a moving target only when no input was dispatched' in `Errors/ErrorTranslationTests`.
- Upstream's WebDriver element-type fix (`fix(mobile): read XCUIElementType class names as their XCTest types`, `3f9a7d8`, tester-army/e2e#1133) is ported. `SnapshotProjection.NormalizeKind` is upstream's `normalizeKind` in `nodes.ts`: it drops `^XCUIElementType(?=[A-Z])` (`XcuiElementTypePrefix`, a .NET `[GeneratedRegex]` for upstream's inline regex) before it maps the type, so the `XCUIElementTypeButton` that agent-device's WebDriver runtime reports on hosted Appium clouds reads as `Button`. `DeviceSession.KeyboardShowing` is upstream's `keyboardShowing` in `surface.ts`: it routes node types through `NormalizeKind`, so an `XCUIElementTypeKeyboard` counts as a shown keyboard. Upstream records this only in its changeset; its skill references and docs say nothing about it, so `SKILL.md` and `docs/` have nothing to mirror. Tests: in `Nodes/SnapshotProjectionTests`, 'reads the XCUIElementType class names a WebDriver session reports as the native XCTest types'; in `Engine/DeviceFixtureDismissingAKeyboardThatHasNoDismissKeyTests`, 'reads an XCUIElementTypeKeyboard from a WebDriver session as a shown keyboard'.
- Upstream's held-device skip (`mobile: skip booted devices another agent-device session holds`, `9e53c40`, tester-army/e2e#1379) is ported. `BootedDevices` (`DevicePool.cs`, upstream's class in `pool.ts`) skips a booted device whose inventory entry has a `claimedBy.session` that is not one of this target's own slot sessions, logs the skipped ones, and fails `prepare` with a non-retryable `ENGINE_FAILURE` when every booted device is held. `BootedDevice` is upstream's interface of that name, as a record. `LifecycleTests.Skips_a_booted_device_another_agent_device_session_holds_keeps_one_its_own_slot_session_holds_and_fails_when_every_booted_one_is_held` ports the `lifecycle` `it` of `engine.test.ts`, whole.
Expand Down
4 changes: 2 additions & 2 deletions docs-site/src/content/docs/get-started/mobile.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -100,9 +100,9 @@ await Expect.That(Device.Locator("role=navigation-bar id=About")).ToBeVisibleAsy
await Device.Locator("id=SW_VERSION_SPECIFIER role=button").TapAsync();
```

Every action on a node pins its ref to the capture that issued it, so a ref a newer capture replaced is never sent to a different element. If the control changed during the `TransitionMilliseconds` wait (500 ms by default), the action fails with a retryable `NODE_STALE` and a locator resolves it again within its timeout. A direct `Device` call such as `DragToAsync` does not retry, so it surfaces the `NODE_STALE`. Unmoved controls are acted on immediately only when keyboard visibility is unchanged: opening or closing the keyboard also uses the remaining `TransitionMilliseconds` budget. A `target_still_moving` refusal from agent-device that reports `dispatched: no` is a retryable `NODE_STALE` as well.
Every action on a node pins its ref to the capture that issued it, so a ref a newer capture replaced is never sent to a different element. If the control changed during the `TransitionMilliseconds` wait (500 ms by default), the action fails with a retryable `NODE_STALE` and a locator resolves it again within its timeout. When the action's own timeout runs out before the transition does, the action fails with a non-retryable `OPERATION_TIMEOUT` and sends nothing. A direct `Device` call such as `DragToAsync` does not retry, so it surfaces the `NODE_STALE`. Unmoved controls are acted on immediately only when keyboard visibility is unchanged: opening or closing the keyboard also uses the remaining `TransitionMilliseconds` budget. A `target_still_moving` refusal from agent-device that reports `dispatched: no` is a retryable `NODE_STALE` as well.

A step of your test does not wait for the screen to settle after it acts: it checks its outcome with `Expect`, and it only waits out `TransitionMilliseconds` for a control that came with the last action. The agent's actions settle first, because it reads the screen right after acting. `Device.BackAsync` settles too, as `MobileOptions.Settle` says. The engine tells the two apart by the `OperationContext` of the call (`OperationContext.Test` or `OperationContext.Agent`). `DeviceSession.Origin` and `ActionOrigin` are obsolete and go in the next release: pass an `OperationContext` to the `PerformAsync`, `PerformAtAsync`, `SwipeAsync`, or `BackAsync` overload instead.
A step of your test does not wait for the screen to settle after it acts: it checks its outcome with `Expect`, and it only waits out `TransitionMilliseconds` for a control that came with the last action. A screen swipe in a test waits out the remaining `TransitionMilliseconds` budget before it scrolls. The agent's actions settle first, because it reads the screen right after acting. `Device.BackAsync` settles too, as `MobileOptions.Settle` says. The engine tells the two apart by the `OperationContext` of the call (`OperationContext.Test` or `OperationContext.Agent`). `DeviceSession.Origin` and `ActionOrigin` are obsolete and go in the next release: pass an `OperationContext` to the `PerformAsync`, `PerformAtAsync`, `SwipeAsync`, or `BackAsync` overload instead.

`FillAsync` and `ClearAsync` read the field again before typing. A field the fresh capture no longer lists, a changed input purpose or secure, disabled, or hidden state, or an incomplete capture fails with a retryable `NODE_STALE` before anything is typed, and the locator resolves it again. A node that cannot take text fails with `UNSUPPORTED_CAPABILITY`.

Expand Down
Loading
Loading