@testingbot/mobilewright-driver 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 0.7.0 — 2026-11-10
+
+### Added
+- **Exact per-test reporting.** The driver reads Playwright's `test.info()`
+  inside `connect()`/`disconnect()` (which run inside the test), so each
+  session's test and outcome are known exactly instead of reconstructed from
+  timestamps. With `sessionPerTest` each session is named after its test as it
+  starts (`describe › title (retry N)`) and gets its verdict when the test
+  ends; pooled sessions fail if any test on them failed. Every test in the
+  Playwright report links to its TestingBot session. The timing-based join
+  remains as the fallback.
+- **Element screenshots.** `locator.screenshot()` is cropped to the element
+  (points → pixels via the screen scale) and `screenshot({ scale })`
+  downscales; previously both returned the full screen.
+- **`screen.goBack()` on iOS** performs the system left-edge back swipe
+  instead of throwing.
+- **`snapshotTuning`** option, on by default: `waitForIdleTimeout: 0` (plus
+  `animationCoolOffTimeout: 0` on iOS) once per session. Measured on
+  production: fill + assert 7.3s → 3.5s on an Android emulator, 3.4s → 2.95s
+  on an iOS simulator. `false` keeps the server defaults.
+- **`visibility: 'bounds'`** option: judge `isVisible` by frame size, like
+  local mobilecli.
+- **`allocationRetryDelay`** option: a "no device available" error while the
+  run holds no session is retried with backoff (5s doubling to 30s) until
+  the pool gives up. mobilewright's pool only retries when one of its own
+  slots is released, so such a test previously idled until its timeout.
+
+### Fixed
+- `fill()` / `clearText()` on iOS now clear the focused field through its
+  element reference. XCUITest's page source has no focused flag, and React
+  Native fields put the caret at the start, so the old backspace fallback
+  never removed anything (`fill('7')` on a field holding `0` gave `70`).
+- Rotated `sessionPerTest` sessions now correct the test's `device.model` /
+  `device.osVersion` annotations, which described the pool slot's first
+  session.
+
 ## 0.6.0 — 2026-10-28
 
 Tracks `@mobilewright/protocol` 0.0.67.

package/README.md

@@ -93,9 +93,11 @@ Regexes and version ranges work on both real and virtual devices: real devices r
 
 ## Sessions, naming, and reporting
 
-- By default a device slot's TestingBot session is reused across tests (fast: you pay device startup once). Sessions that hosted exactly one test are named after that test with its own pass/fail; sessions that hosted several get a run summary (e.g. `12/12 tests passed`).
-- Set **`sessionPerTest: true`** for one session, video, and named verdict **per test** — the clearest dashboard, at the cost of device startup on every test.
-- Tests are matched to sessions by **worker identity first**: the driver stamps Playwright's worker index on each session as it records it, and the run report reports the same index per test, so a test that ran in another worker process is never a candidate. Timing separates the tests within one worker, using the worker's own timestamps from the report when it is available.
+- By default a device slot's TestingBot session is reused across tests (fast: you pay device startup once). Sessions that hosted exactly one test are named after that test with its own pass/fail; sessions that hosted several pass only if every test on them passed (e.g. `1 of 3 tests failed. checkout › pays: ...`).
+- Set **`sessionPerTest: true`** for one session, video, and named verdict **per test** — the clearest dashboard, at the cost of device startup on every test. The session is named after the test as soon as it starts (`describe › title`, plus `(retry N)` on retries), and its verdict is reported the moment the test ends, while the session is still alive.
+- Each test in Playwright's HTML report gets a **`TestingBot`** annotation linking to the session (and its video) that test ran on.
+- Tests are matched to sessions **exactly**: `connect()`/`disconnect()` run inside the test, so the driver reads Playwright's `test.info()` there and records which test attempt ran on which session, with its outcome. The heuristic below is only the fallback when `@playwright/test` cannot be resolved from the project.
+- Fallback: tests are matched to sessions by **worker identity first**: the driver stamps Playwright's worker index on each session as it records it, and the run report reports the same index per test, so a test that ran in another worker process is never a candidate. Timing separates the tests within one worker, using the worker's own timestamps from the report when it is available.
 - A session is only ever given a verdict the driver can stand behind: its own test's, or the run summary when it genuinely hosted several tests (or was the run's only session). When a session cannot be tied to a test — an ambiguous overlap under heavy parallelism, or a worker that died before recording its span — it is reported with build, extra and tags but **no** pass/fail, rather than inheriting a failure from a test that ran somewhere else. `DEBUG=testingbot:observer` names the session and the reason.
 - Git metadata is reported automatically when mobilewright captures it: the commit hash, branch, author and subject land in the session's **extra** field (alongside your own `extra`, never replacing it), and the branch is added as a **tag** so the dashboard can filter by it. Enable it with `captureGitInfo: { commit: true }` in `mobilewright.config.ts` — Playwright turns it on by itself in CI.
 - Failure messages are reported to the session's status message; `build` groups sessions on the dashboard and **defaults automatically from CI environments** (GitHub Actions, GitLab, CircleCI, Buildkite, Bitrise, Travis, Azure DevOps, Jenkins, TeamCity → e.g. `owner/repo #123`), or from a `TESTINGBOT_BUILD` variable.
@@ -115,6 +117,14 @@ new TestingBotDriver({
   build: 'ci-1234',           // default: auto-detected from CI env / TESTINGBOT_BUILD
   testResults: 'on',          // 'off' disables pass/fail reporting
 
+  snapshotTuning: {},         // Appium settings applied once per session; default turns off
+                              // the wait-for-idle before each hierarchy read (much faster
+                              // assertions while the UI animates). false = server defaults
+  visibility: 'native',       // 'bounds' = any element with a non-empty frame is visible
+                              // (mobilecli-like; helps iOS toBeVisible() on overlapped views)
+  allocationRetryDelay: 5_000,// first backoff (ms) when no device is free and the run holds
+                              // no session yet; doubles up to 30s until the pool gives up
+
   allocationTimeout: 395_000, // ms to wait for a device (TestingBot queues busy devices)
   idleTimeout: 230,           // seconds before TestingBot reaps an idle session
   maxDuration: 1800,          // max session length in seconds
@@ -246,6 +256,8 @@ jobs:
 | `cannot install "..." mid-session` | TestingBot has no mid-session installs — every app in `installApps` must also be listed in the driver's `apps` option (first entry = app under test, the rest install as helper apps). |
 | Modifier chords fail on iOS | XCUITest cannot hold modifier keys; chords are Android-only (`clearText()` handles iOS differently). |
 | Sessions show the run summary instead of a test name | The session hosted several tests; `sessionPerTest: true` gives each test its own session. |
+| An iOS project never gets a device in a mixed Android + iOS run | mobilewright's pool keeps idle slots of the other platform. Run each platform in its own `mobilewright test --project ...` invocation, or raise `workers`. |
+| `toBeVisible()` fails on iOS for an element that is on screen | XCUITest reports elements drawn under a sibling as invisible. Set `visibility: 'bounds'`. |
 | A session shows no pass/fail at all | The driver could not tell which test ran in it and declined to guess. Run with `DEBUG=testingbot:observer` — it logs the session id and why. |
 | `DEBUG=testingbot:*` | Prints every allocation, hub command, upload, and report the driver performs. |
 
@@ -265,11 +277,11 @@ jobs:
 
 ## Current limitations
 
-- One TestingBot session may host several mobilewright tests unless `sessionPerTest: true`; multi-test sessions report the run-level verdict.
-- The worker process that owns a session is never told which test it is running, so the session-to-test join is reconstructed after the run from Playwright's worker index plus timing. Without the run report (`jsonReport()`) it degrades to timing alone. Either way it is deliberately conservative and leaves a session unjudged rather than risk naming it after the wrong test.
+- One TestingBot session may host several mobilewright tests unless `sessionPerTest: true`; a multi-test session keeps one name and fails if any test on it failed.
+- **Run Android and iOS projects in separate invocations** (`--project android`, then `--project ios`) unless `workers` exceeds the number of projects. mobilewright's device pool never evicts an idle slot of one platform to make room for the other, so with every slot holding an Android session an iOS test waits until it times out.
 - Modifier key chords (`pressKeys(['ctrl+a'])`) work on Android only — XCUITest cannot hold modifier keys.
-- `pressButton` on iOS supports `HOME`, `VOLUME_UP`, `VOLUME_DOWN`; `listApps()` reports the foreground app only.
-- Screenshots are always PNG, and `screenshot({ clip })` is not honoured yet — the full screen comes back uncropped. `applyDeviceSettings` turns Android animations off best-effort via `mobile: shell` (a no-op on iOS).
+- `pressButton` on iOS supports `HOME`, `VOLUME_UP`, `VOLUME_DOWN`, and `BACK` (performed as the system left-edge swipe, so `screen.goBack()` works in navigation stacks); `listApps()` reports the foreground app only.
+- Screenshots are always PNG. `locator.screenshot()` is cropped to the element and `screenshot({ scale })` downscales. `applyDeviceSettings` turns Android animations off best-effort via `mobile: shell` (a no-op on iOS).
 - `setGeolocation` needs the platform driver's location extension to be available: emulators and simulators always are, real devices depend on the OS version TestingBot's Appium build supports (iOS 17+ for XCUITest).
 - `setFoldState` (protocol 0.0.62) throws: Appium has no hinge control for TestingBot's foldables.
 - Real iOS devices need a test-signed `.ipa`; simulator builds are rejected on real devices with a clear error.
@@ -285,6 +297,14 @@ npm run build
 
 Live e2e tests against a real TestingBot account live in `e2e/` (see `e2e/mobilewright.config.ts`).
 
+`e2e/live.config.ts` runs feature checks (hierarchy speed, fill, element screenshots, iOS back navigation, per-test reporting) against TestingBot's public sample app, so it needs no local builds:
+
+```bash
+cd e2e && npm install --no-save mobilewright@latest @mobilewright/test@latest
+TESTINGBOT_KEY=... TESTINGBOT_SECRET=... npx mobilewright test -c live.config.ts --project android-emulator
+# E2E_SESSION_PER_TEST=1, E2E_FORCE_FAIL=1, E2E_RETRIES=1, E2E_VISIBILITY=bounds, E2E_NO_TUNING=1 toggle scenarios
+```
+
 ### Releasing
 
 Update `CHANGELOG.md` first — it ships inside the published tarball.

package/dist/actions.d.ts

@@ -18,6 +18,12 @@ export declare function tapActions(x: number, y: number): PointerSource[];
 export declare function doubleTapActions(x: number, y: number): PointerSource[];
 export declare function longPressActions(x: number, y: number, duration?: number): PointerSource[];
 export declare function swipeActions(direction: SwipeDirection, screen: ScreenSize, opts?: SwipeOptions): PointerSource[];
+/**
+ * iOS system back gesture: a quick swipe from the left screen edge to past the
+ * middle, at mid-height. UINavigationController's interactive pop recognizer
+ * needs the touch to start within a few points of the edge.
+ */
+export declare function edgeSwipeBackActions(screen: ScreenSize): PointerSource[];
 /** Multi-finger gesture: each pointer path becomes one W3C input source,
  *  with `time` offsets converted to per-segment move durations. */
 export declare function gestureActions(gestures: GestureSequence): PointerSource[];

package/dist/actions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAExG;;;;;GAKG;AAEH,KAAK,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEzC,UAAU,aAAa;IACrB,IAAI,EAAE,SAAS,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE;QAAE,WAAW,EAAE,OAAO,CAAA;KAAE,CAAC;IACrC,OAAO,EAAE,SAAS,EAAE,CAAC;CACtB;AAYD,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,aAAa,EAAE,CAEhE;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,aAAa,EAAE,CAMtE;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,QAAQ,SAAM,GAAG,aAAa,EAAE,CAEtF;AAED,wBAAgB,YAAY,CAC1B,SAAS,EAAE,cAAc,EACzB,MAAM,EAAE,UAAU,EAClB,IAAI,GAAE,YAAiB,GACtB,aAAa,EAAE,CA2BjB;AAED;mEACmE;AACnE,wBAAgB,cAAc,CAAC,QAAQ,EAAE,eAAe,GAAG,aAAa,EAAE,CAgBzE"}
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAExG;;;;;GAKG;AAEH,KAAK,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEzC,UAAU,aAAa;IACrB,IAAI,EAAE,SAAS,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE;QAAE,WAAW,EAAE,OAAO,CAAA;KAAE,CAAC;IACrC,OAAO,EAAE,SAAS,EAAE,CAAC;CACtB;AAYD,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,aAAa,EAAE,CAEhE;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,aAAa,EAAE,CAMtE;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,QAAQ,SAAM,GAAG,aAAa,EAAE,CAEtF;AAED,wBAAgB,YAAY,CAC1B,SAAS,EAAE,cAAc,EACzB,MAAM,EAAE,UAAU,EAClB,IAAI,GAAE,YAAiB,GACtB,aAAa,EAAE,CA2BjB;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,UAAU,GAAG,aAAa,EAAE,CAQxE;AAED;mEACmE;AACnE,wBAAgB,cAAc,CAAC,QAAQ,EAAE,eAAe,GAAG,aAAa,EAAE,CAgBzE"}

package/dist/actions.js

@@ -52,6 +52,20 @@ export function swipeActions(direction, screen, opts = {}) {
             up(),
         ])];
 }
+/**
+ * iOS system back gesture: a quick swipe from the left screen edge to past the
+ * middle, at mid-height. UINavigationController's interactive pop recognizer
+ * needs the touch to start within a few points of the edge.
+ */
+export function edgeSwipeBackActions(screen) {
+    const y = screen.height / 2;
+    return [pointerSource('finger1', [
+            move(2, y),
+            down(),
+            move(screen.width * 0.6, y, 250),
+            up(),
+        ])];
+}
 /** Multi-finger gesture: each pointer path becomes one W3C input source,
  *  with `time` offsets converted to per-segment move durations. */
 export function gestureActions(gestures) {

package/dist/actions.js.map

@@ -1 +1 @@
-{"version":3,"file":"actions.js","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"actions.js","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAkBA,SAAS,aAAa,CAAC,EAAU,EAAE,OAAoB;IACrD,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,UAAU,EAAE,EAAE,WAAW,EAAE,OAAO,EAAE,EAAE,OAAO,EAAE,CAAC;AAChF,CAAC;AAED,MAAM,IAAI,GAAG,CAAC,CAAS,EAAE,CAAS,EAAE,QAAQ,GAAG,CAAC,EAAa,EAAE,CAC7D,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,QAAQ,EAAE,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC;AAC9F,MAAM,IAAI,GAAG,GAAc,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC;AACnE,MAAM,EAAE,GAAG,GAAc,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC;AAC/D,MAAM,KAAK,GAAG,CAAC,QAAgB,EAAa,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,CAAC;AAE7E,MAAM,UAAU,UAAU,CAAC,CAAS,EAAE,CAAS;IAC7C,OAAO,CAAC,aAAa,CAAC,SAAS,EAAE,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;AAC3E,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,CAAS,EAAE,CAAS;IACnD,OAAO,CAAC,aAAa,CAAC,SAAS,EAAE;YAC/B,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE;YACnC,KAAK,CAAC,EAAE,CAAC;YACT,IAAI,EAAE,EAAE,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE;SACxB,CAAC,CAAC,CAAC;AACN,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,CAAS,EAAE,CAAS,EAAE,QAAQ,GAAG,GAAG;IACnE,OAAO,CAAC,aAAa,CAAC,SAAS,EAAE,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,KAAK,CAAC,QAAQ,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;AACjF,CAAC;AAED,MAAM,UAAU,YAAY,CAC1B,SAAyB,EACzB,MAAkB,EAClB,OAAqB,EAAE;IAEvB,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,KAAK,GAAG,CAAC,CAAC;IAC/C,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;IAChD,MAAM,eAAe,GAAG,CAAC,SAAS,KAAK,IAAI,IAAI,SAAS,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC;IAC1G,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,eAAe,CAAC;IAClD,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,GAAG,CAAC;IAEtC,IAAI,IAAI,GAAG,MAAM,CAAC;IAClB,IAAI,IAAI,GAAG,MAAM,CAAC;IAClB,QAAQ,SAAS,EAAE,CAAC;QAClB,KAAK,IAAI;YAAE,IAAI,GAAG,MAAM,GAAG,QAAQ,CAAC;YAAC,MAAM;QAC3C,KAAK,MAAM;YAAE,IAAI,GAAG,MAAM,GAAG,QAAQ,CAAC;YAAC,MAAM;QAC7C,KAAK,MAAM;YAAE,IAAI,GAAG,MAAM,GAAG,QAAQ,CAAC;YAAC,MAAM;QAC7C,KAAK,OAAO;YAAE,IAAI,GAAG,MAAM,GAAG,QAAQ,CAAC;YAAC,MAAM;IAChD,CAAC;IACD,MAAM,KAAK,GAAG,CAAC,CAAS,EAAE,GAAW,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC;IAC5E,IAAI,GAAG,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC;IACjC,IAAI,GAAG,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IAElC,OAAO,CAAC,aAAa,CAAC,SAAS,EAAE;YAC/B,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC;YACpB,IAAI,EAAE;YACN,KAAK,CAAC,EAAE,CAAC;YACT,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,CAAC;YAC1B,KAAK,CAAC,EAAE,CAAC;YACT,EAAE,EAAE;SACL,CAAC,CAAC,CAAC;AACN,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAkB;IACrD,MAAM,CAAC,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;IAC5B,OAAO,CAAC,aAAa,CAAC,SAAS,EAAE;YAC/B,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC;YACV,IAAI,EAAE;YACN,IAAI,CAAC,MAAM,CAAC,KAAK,GAAG,GAAG,EAAE,CAAC,EAAE,GAAG,CAAC;YAChC,EAAE,EAAE;SACL,CAAC,CAAC,CAAC;AACN,CAAC;AAED;mEACmE;AACnE,MAAM,UAAU,cAAc,CAAC,QAAyB;IACtD,OAAO,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE;QACvC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,aAAa,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;QAClE,MAAM,SAAS,GAAG,IAAI,CAAC,CAAC,CAAE,CAAC,IAAI,IAAI,CAAC,CAAC;QACrC,MAAM,OAAO,GAAgB,EAAE,CAAC;QAChC,IAAI,SAAS,GAAG,CAAC;YAAE,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,yBAAyB;QAC5E,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAE,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;QACnD,IAAI,QAAQ,GAAG,SAAS,CAAC;QACzB,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;YAClC,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,IAAI,QAAQ,CAAC;YACpC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,IAAI,GAAG,QAAQ,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;YACnE,QAAQ,GAAG,IAAI,CAAC;QAClB,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;QACnB,OAAO,aAAa,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;IAClD,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/driver.d.ts

@@ -1,4 +1,4 @@
-import { type AllocatedDevice, type AllocationCriteria, type AppInfo, type ConnectionConfig, type DeviceInfo, type DeviceSettings, type GestureSequence, type HardwareButton, type LaunchOptions, type ListDevicesOptions, type MobilewrightDriver, type Orientation, type RecordingOptions, type RecordingResult, type ScreenSize, type ScreenshotOptions, type Session, type SwipeDirection, type SwipeOptions, type TestObserver, type ViewNode } from '@mobilewright/protocol';
+import { type AllocatedDevice, type Bounds, type AllocationCriteria, type AppInfo, type ConnectionConfig, type DeviceInfo, type DeviceSettings, type GestureSequence, type HardwareButton, type LaunchOptions, type ListDevicesOptions, type MobilewrightDriver, type Orientation, type RecordingOptions, type RecordingResult, type ScreenSize, type ScreenshotOptions, type Session, type SwipeDirection, type SwipeOptions, type TestObserver, type ViewNode } from '@mobilewright/protocol';
 import { type TestingBotDriverOptions } from './options.js';
 import { type ThrottlePreset, type ThrottleProfile } from './session-commands.js';
 import { AppiumWebViewBridge } from './webview.js';
@@ -60,13 +60,35 @@ export declare class TestingBotDriver implements MobilewrightDriver {
     private warnedAboutParallelism;
     constructor(options?: TestingBotDriverOptions);
     prepare(): Promise<void>;
-    allocate(criteria: AllocationCriteria, _takenDeviceIds: ReadonlySet<string>, signal?: AbortSignal): Promise<AllocatedDevice>;
+    /**
+     * mobilewright's pool re-queues a NoDeviceAvailableError and only retries
+     * when one of its own slots is released. With no session held by this run,
+     * nothing is ever released, so the test would idle until its allocation
+     * timeout even if a device frees up seconds later. Retry here instead, with
+     * backoff, until the pool's signal aborts (or allocationTimeout without one).
+     */
+    allocate(criteria: AllocationCriteria, takenDeviceIds: ReadonlySet<string>, signal?: AbortSignal): Promise<AllocatedDevice>;
+    private allocateOnce;
     release(deviceId: string): Promise<void>;
     dispose(): Promise<void>;
     connect(config: ConnectionConfig): Promise<Session>;
     disconnect(): Promise<void>;
     /** Create a new hub session for this slot from the connect() config. */
     private startFreshSession;
+    /**
+     * Link the running test to its TestingBot session in Playwright's report.
+     * A rotated per-test session can land on a different device than the pool
+     * slot's first one, so the fixture's device annotations are corrected too.
+     */
+    private annotateTest;
+    /** sessionPerTest: name the session after its test as soon as it starts. */
+    private nameSessionAfterTest;
+    /**
+     * Turn off the backend's wait-for-idle before each page-source read (see the
+     * `snapshotTuning` option). Once per session, best-effort: a server that
+     * rejects a setting still leaves a working session.
+     */
+    private applySnapshotTuning;
     /** Run any Appium/TestingBot execute-script command on the live session. */
     executeScript<T = unknown>(script: string, ...args: unknown[]): Promise<T>;
     /** WebDriver session id of the device this instance is connected to. */
@@ -86,16 +108,20 @@ export declare class TestingBotDriver implements MobilewrightDriver {
     typeText(text: string): Promise<void>;
     pressKeys(keys: string[]): Promise<void>;
     clearText(): Promise<void>;
+    /** WebDriver id of the focused element (GET /element/active), if any. */
+    private activeElementId;
     /**
-     * Neither Appium driver can replace a field's value without an element
-     * reference, and the protocol only hands us the focused field — so clear it
-     * the same way `clearText()` does, then type the new value.
+     * The protocol only hands us the focused field, so clear it the same way
+     * `clearText()` does, then type the new value.
      */
     fill(text: string): Promise<void>;
     swipe(direction: SwipeDirection, opts?: SwipeOptions): Promise<void>;
     gesture(gestures: GestureSequence): Promise<void>;
     pressButton(button: HardwareButton): Promise<void>;
-    screenshot(opts?: ScreenshotOptions): Promise<Buffer>;
+    screenshot(opts?: ScreenshotOptions & {
+        clip?: Bounds;
+        scale?: number;
+    }): Promise<Buffer>;
     getScreenSize(): Promise<ScreenSize>;
     getOrientation(): Promise<Orientation>;
     setOrientation(orientation: Orientation): Promise<void>;

package/dist/driver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../src/driver.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../src/driver.ts"],"names":[],"mappings":"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"}

package/dist/driver.js

@@ -1,7 +1,7 @@
 import { writeFile } from 'node:fs/promises';
 import createDebug from 'debug';
 import { NoDeviceAvailableError, } from '@mobilewright/protocol';
-import { doubleTapActions, gestureActions, longPressActions, swipeActions, tapActions, } from './actions.js';
+import { doubleTapActions, edgeSwipeBackActions, gestureActions, longPressActions, swipeActions, tapActions, } from './actions.js';
 import { AppStorage } from './app-storage.js';
 import { appsForCriteria, buildCapabilities } from './capabilities.js';
 import { DeviceCatalog } from './device-catalog.js';
@@ -11,7 +11,10 @@ import { parseChord, toAndroidKeyPress, toW3CKeyActions, typeTextActions } from
 import { TestingBotTestObserver } from './observer.js';
 import { requireCredentials, resolveOptions } from './options.js';
 import { RestApiClient } from './rest-api.js';
+import { transformPng } from './png.js';
 import { RunLog } from './run-log.js';
+import { attemptName, attemptOutcome, currentTestInfo } from './test-info.js';
+import { exactVerdict } from './observer.js';
 import { setActiveDriver } from './session-commands.js';
 import { TunnelManager } from './tunnel.js';
 import { AppiumWebViewBridge } from './webview.js';
@@ -32,6 +35,11 @@ const ANDROID_BUTTON_KEYCODES = {
     APP_SWITCH: 187,
     LOCK: 26, // same as POWER — locks the screen
 };
+/** Default snapshot tuning per platform (see the `snapshotTuning` option). */
+const SNAPSHOT_TUNING = {
+    android: { waitForIdleTimeout: 0 },
+    ios: { waitForIdleTimeout: 0, animationCoolOffTimeout: 0 },
+};
 // XCUITest's mobile: pressButton supports exactly these names on iOS.
 const IOS_BUTTON_NAMES = {
     HOME: 'home',
@@ -111,7 +119,36 @@ export class TestingBotDriver {
         debug('credentials verified against %s (plan %s, parallel %s vm / %s device)', this.options.apiUrl, this.userInfo.plan, this.userInfo.max_concurrent, this.userInfo.max_concurrent_mobile);
         await this.tunnel.start(this.options);
     }
-    async allocate(criteria, _takenDeviceIds, signal) {
+    /**
+     * mobilewright's pool re-queues a NoDeviceAvailableError and only retries
+     * when one of its own slots is released. With no session held by this run,
+     * nothing is ever released, so the test would idle until its allocation
+     * timeout even if a device frees up seconds later. Retry here instead, with
+     * backoff, until the pool's signal aborts (or allocationTimeout without one).
+     */
+    async allocate(criteria, takenDeviceIds, signal) {
+        const deadline = signal ? Infinity : Date.now() + this.options.allocationTimeout;
+        for (let attempt = 1;; attempt++) {
+            try {
+                return await this.allocateOnce(criteria, takenDeviceIds, signal);
+            }
+            catch (err) {
+                if (!(err instanceof NoDeviceAvailableError) || signal?.aborted)
+                    throw err;
+                if (this.allocated.size > 0) {
+                    debug('no device available; this run holds %d session(s), handing back to the pool', this.allocated.size);
+                    throw err;
+                }
+                const delay = Math.min(this.options.allocationRetryDelay * 2 ** (attempt - 1), 30_000);
+                if (Date.now() + delay > deadline)
+                    throw err;
+                debug('no device available (%s); retry %d in %dms', err.message, attempt, delay);
+                if (!(await sleep(delay, signal)))
+                    throw err;
+            }
+        }
+    }
+    async allocateOnce(criteria, _takenDeviceIds, signal) {
         requireCredentials(this.options);
         // takenDeviceIds is unused: every allocate() creates a fresh, exclusive
         // WebDriver session; physical-device contention is handled server-side.
@@ -197,6 +234,7 @@ export class TestingBotDriver {
             this.inFlightAllocations -= 1;
         }
         const platform = criteria.platform ?? (String(caps['platformName']).toLowerCase() === 'ios' ? 'ios' : 'android');
+        await this.applySnapshotTuning(sessionId, platform);
         const session = {
             sessionId,
             platform,
@@ -206,6 +244,17 @@ export class TestingBotDriver {
         };
         this.allocated.set(sessionId, session);
         this.everAllocated.set(sessionId, session);
+        if (this.options.sessionPerTest) {
+            // Workers rotating sessions on this slot need its device filter, which
+            // mobilewright's connect() does not forward.
+            this.runLog.append({
+                type: 'slot',
+                deviceId: sessionId,
+                deviceType: criteria.deviceType,
+                osVersion: criteria.osVersion,
+                deviceNamePattern: criteria.deviceNamePattern,
+            });
+        }
         this.keepalive.start(sessionId);
         debug('allocated session %s (%s %s) — https://testingbot.com/members/tests/%s', sessionId, session.deviceName, session.osVersion, sessionId);
         return {
@@ -258,6 +307,7 @@ export class TestingBotDriver {
             await this.hub.get(poolDeviceId, '/orientation', { timeout });
             this.active = { sessionId: poolDeviceId, platform: config.platform, deviceType: config.deviceType, connectedAt: Date.now() };
             setActiveDriver(this);
+            this.annotateTest(poolDeviceId);
             debug('connected to session %s', poolDeviceId);
             return { deviceId: poolDeviceId, platform: config.platform };
         }
@@ -277,9 +327,16 @@ export class TestingBotDriver {
             }
             this.rotatedDeviceIds.add(poolDeviceId);
         }
-        sessionId ??= await this.startFreshSession(config);
+        let rotated;
+        if (!sessionId) {
+            const fresh = await this.startFreshSession(config, poolDeviceId);
+            sessionId = fresh.sessionId;
+            rotated = { model: fresh.model, osVersion: fresh.osVersion };
+        }
         this.active = { sessionId, platform: config.platform, deviceType: config.deviceType, connectedAt: Date.now() };
         setActiveDriver(this);
+        await this.nameSessionAfterTest(sessionId);
+        this.annotateTest(sessionId, rotated);
         debug('connected to session %s (slot %s)', sessionId, poolDeviceId);
         return { deviceId: poolDeviceId, platform: config.platform };
     }
@@ -294,12 +351,15 @@ export class TestingBotDriver {
         // session it cannot attribute gets no verdict at all. Nothing in teardown
         // — a hub round-trip, a hung request, the worker dying — may come between
         // the test ending and this line.
+        const info = currentTestInfo();
+        const outcome = info && attemptOutcome(info);
         this.runLog.append({
             type: 'session',
             sessionId: session.sessionId,
             startedAt: session.connectedAt,
             endedAt: Date.now(),
             workerIndex: workerIndex(),
+            ...(outcome ? { test: outcome } : {}),
         });
         if (session.throttled) {
             // A pooled session outlives the test: reset network conditions so they
@@ -308,6 +368,13 @@ export class TestingBotDriver {
                 debug('could not reset throttling on %s: %s', session.sessionId, err);
             });
         }
+        if (this.options.sessionPerTest && outcome && this.options.testResults !== 'off') {
+            // This session hosted exactly this attempt: report its verdict now, while
+            // the session is alive, instead of relying on the run-end observer alone.
+            await this.api.updateTest(session.sessionId, exactVerdict([outcome])).catch((err) => {
+                debug('could not report verdict for %s: %s', session.sessionId, err);
+            });
+        }
         if (!this.options.sessionPerTest) {
             // Soft detach only: the pool re-grants this slot to the next test and
             // ends the session via release(). A pooled session that hosted exactly
@@ -322,12 +389,17 @@ export class TestingBotDriver {
         debug('ended per-test session %s', session.sessionId);
     }
     /** Create a new hub session for this slot from the connect() config. */
-    async startFreshSession(config) {
+    async startFreshSession(config, poolDeviceId) {
+        // mobilewright's connect() passes only platform/deviceId/deviceType, so
+        // the slot's deviceName/osVersion filter comes from the coordinator's
+        // allocate() record. Values on the config win when a caller provides them.
+        const slot = this.runLog.slotFor(poolDeviceId);
+        const configName = config.deviceName instanceof RegExp ? config.deviceName.source : config.deviceName;
         const criteria = {
             platform: config.platform,
-            deviceType: config.deviceType,
-            osVersion: config.osVersion,
-            deviceNamePattern: config.deviceName instanceof RegExp ? config.deviceName.source : config.deviceName,
+            deviceType: config.deviceType ?? slot?.deviceType,
+            osVersion: config.osVersion ?? slot?.osVersion,
+            deviceNamePattern: configName ?? slot?.deviceNamePattern,
         };
         let pinned;
         if (criteria.deviceType === 'real') {
@@ -347,10 +419,60 @@ export class TestingBotDriver {
             }
         }
         const capabilities = buildCapabilities(criteria, this.options, pinned, appUrls);
-        const { sessionId } = await this.hub.newSession(capabilities, { timeout: this.options.allocationTimeout });
+        const { sessionId, capabilities: caps } = await this.hub.newSession(capabilities, { timeout: this.options.allocationTimeout });
         this.runLog.append({ type: 'session', sessionId });
+        await this.applySnapshotTuning(sessionId, config.platform);
         debug('started per-test session %s — https://testingbot.com/members/tests/%s', sessionId, sessionId);
-        return sessionId;
+        return {
+            sessionId,
+            model: pinned?.deviceName ?? str(caps['appium:deviceName'] ?? caps['deviceName']),
+            osVersion: pinned?.platformVersion ?? str(caps['appium:platformVersion'] ?? caps['platformVersion']),
+        };
+    }
+    /**
+     * Link the running test to its TestingBot session in Playwright's report.
+     * A rotated per-test session can land on a different device than the pool
+     * slot's first one, so the fixture's device annotations are corrected too.
+     */
+    annotateTest(sessionId, device) {
+        const info = currentTestInfo();
+        if (!info)
+            return;
+        info.annotations.push({ type: 'TestingBot', description: `https://testingbot.com/members/tests/${sessionId}` });
+        for (const annotation of info.annotations) {
+            if (annotation.type === 'device.model' && device?.model)
+                annotation.description = device.model;
+            if (annotation.type === 'device.osVersion' && device?.osVersion)
+                annotation.description = device.osVersion;
+        }
+    }
+    /** sessionPerTest: name the session after its test as soon as it starts. */
+    async nameSessionAfterTest(sessionId) {
+        if (this.options.testResults === 'off')
+            return;
+        const info = currentTestInfo();
+        if (!info)
+            return;
+        await this.api.updateTest(sessionId, { name: attemptName(info) }).catch((err) => {
+            debug('could not name session %s: %s', sessionId, err);
+        });
+    }
+    /**
+     * Turn off the backend's wait-for-idle before each page-source read (see the
+     * `snapshotTuning` option). Once per session, best-effort: a server that
+     * rejects a setting still leaves a working session.
+     */
+    async applySnapshotTuning(sessionId, platform) {
+        if (this.options.snapshotTuning === false)
+            return;
+        const settings = { ...SNAPSHOT_TUNING[platform], ...this.options.snapshotTuning };
+        try {
+            await this.hub.post(sessionId, '/appium/settings', { settings });
+            debug('snapshot tuning applied to %s: %o', sessionId, settings);
+        }
+        catch (err) {
+            debug('snapshot tuning rejected on %s (%s), keeping server defaults', sessionId, err);
+        }
     }
     // ─── TestingBot-specific session commands ─────────────────────
     /** Run any Appium/TestingBot execute-script command on the live session. */
@@ -399,7 +521,7 @@ export class TestingBotDriver {
         const { sessionId, platform } = this.session();
         const xml = await this.hub.source(sessionId);
         const { parseHierarchy } = await import('./hierarchy.js');
-        return parseHierarchy(xml, platform);
+        return parseHierarchy(xml, platform, this.options.visibility);
     }
     // ─── MobilewrightSession: input ────────────────────────────────
     async tap(x, y) {
@@ -446,8 +568,21 @@ export class TestingBotDriver {
             await this.pressKeys(['ctrl+a', 'backspace']);
             return;
         }
-        // iOS has no working select-all chord; delete the focused field's value
-        // one backspace per character (hierarchy tells us how many).
+        // iOS: clear the focused field through its element reference. Backspaces
+        // only delete what is left of the caret, and tapping a field (React Native
+        // in particular) can put the caret at the start, so key-based deletion
+        // leaves the value untouched.
+        const active = await this.activeElementId(sessionId);
+        if (active) {
+            try {
+                await this.hub.post(sessionId, `/element/${active}/clear`, {});
+                return;
+            }
+            catch (err) {
+                debug('clearText: element clear failed (%s), falling back to backspaces', err);
+            }
+        }
+        // Fallback: one backspace per character of the focused field's value.
         const { parseHierarchy } = await import('./hierarchy.js');
         const nodes = parseHierarchy(await this.hub.source(sessionId), 'ios');
         const focused = findFocused(nodes);
@@ -456,10 +591,20 @@ export class TestingBotDriver {
             await this.hub.performActions(sessionId, toW3CKeyActions(Array.from({ length }, () => ({ modifiers: [], key: 'backspace' }))));
         }
     }
+    /** WebDriver id of the focused element (GET /element/active), if any. */
+    async activeElementId(sessionId) {
+        try {
+            const ref = await this.hub.get(sessionId, '/element/active');
+            return ref?.['element-6066-11e4-a52e-4f304ffac5c0'] ?? ref?.['ELEMENT'];
+        }
+        catch (err) {
+            debug('no active element (%s)', err);
+            return undefined;
+        }
+    }
     /**
-     * Neither Appium driver can replace a field's value without an element
-     * reference, and the protocol only hands us the focused field — so clear it
-     * the same way `clearText()` does, then type the new value.
+     * The protocol only hands us the focused field, so clear it the same way
+     * `clearText()` does, then type the new value.
      */
     async fill(text) {
         await this.clearText();
@@ -480,6 +625,13 @@ export class TestingBotDriver {
             await this.hub.execute(sessionId, 'mobile: pressKey', [{ keycode: ANDROID_BUTTON_KEYCODES[button] }]);
             return;
         }
+        if (button === 'BACK') {
+            // iOS has no back button; screen.goBack() lands here. Use the system
+            // edge-swipe-back gesture that UINavigationController responds to.
+            const screen = await this.getScreenSize();
+            await this.hub.performActions(sessionId, edgeSwipeBackActions(screen));
+            return;
+        }
         const name = IOS_BUTTON_NAMES[button];
         if (!name) {
             throw new Error(`TestingBotDriver: hardware button "${button}" is not supported on iOS`);
@@ -490,8 +642,24 @@ export class TestingBotDriver {
     async screenshot(opts) {
         const { sessionId } = this.session();
         // TestingBot/Appium produce PNG; a jpeg format request falls back to PNG.
-        const base64 = await this.hub.screenshot(sessionId);
-        const buffer = Buffer.from(base64, 'base64');
+        let buffer = Buffer.from(await this.hub.screenshot(sessionId), 'base64');
+        const factor = opts?.scale !== undefined && opts.scale > 0 && opts.scale < 1 ? opts.scale : 1;
+        if (opts?.clip || factor < 1) {
+            // `clip` is in screen points (locator.screenshot() passes element
+            // bounds); the PNG is in physical pixels.
+            const ratio = opts?.clip ? (await this.getScreenSize()).scale : 1;
+            const rect = opts?.clip && {
+                x: opts.clip.x * ratio,
+                y: opts.clip.y * ratio,
+                width: opts.clip.width * ratio,
+                height: opts.clip.height * ratio,
+            };
+            const transformed = transformPng(buffer, rect, factor);
+            if (transformed)
+                buffer = transformed;
+            else
+                debug('screenshot: could not crop/scale this PNG, returning the full screen');
+        }
         if (opts?.path)
             await writeFile(opts.path, buffer);
         return buffer;
@@ -779,6 +947,16 @@ function describeAllocation(criteria) {
     return parts.length ? parts.join(', ') : 'the requested device';
 }
 /** Values usable directly as appium:app without an upload. */
+/** Resolves true after `ms`, or false as soon as `signal` aborts. */
+function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal?.aborted)
+            return resolve(false);
+        const onAbort = () => { clearTimeout(timer); resolve(false); };
+        const timer = setTimeout(() => { signal?.removeEventListener('abort', onAbort); resolve(true); }, ms);
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
 function isRemoteApp(value) {
     return /^(tb|https?):\/\//i.test(value);
 }