@testingbot/mobilewright-driver 0.1.0 → 0.2.0

package/README.md

@@ -41,6 +41,8 @@ export default defineConfig({
     // TestingBot sessions start with the app pre-installed — declare it here.
     // Local paths (.apk / .ipa / simulator .zip) upload automatically.
     apps: {
+      // A single path, or an array whose first entry is the app under test
+      // and the rest install alongside it (e.g. a mock server or test harness).
       android: './build/app.apk',
       'ios-simulator': './build/app-sim.zip',
       'ios-real': './build/app.ipa', // must be test-signed for real devices
@@ -90,6 +92,7 @@ Regexes and version ranges work on both real and virtual devices: real devices r
 
 - 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.
+- 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.
 
 ## All options
@@ -97,7 +100,9 @@ Regexes and version ranges work on both real and virtual devices: real devices r
 ```ts
 new TestingBotDriver({
   apps: { android: './build/app.apk' }, // app under test, most specific key wins
-                                        // ('ios-real' beats 'ios'); tb:// URLs allowed
+                                        // ('ios-real' beats 'ios'); tb:// URLs allowed.
+                                        // Array = app under test first, helper apps after:
+                                        //   android: ['./app.apk', './mock-server.apk']
   key: '...',                 // default: TESTINGBOT_KEY env
   secret: '...',              // default: TESTINGBOT_SECRET env
   sessionPerTest: false,      // true = fresh session (and video) per test
@@ -113,6 +118,8 @@ new TestingBotDriver({
   timeZone: 'Europe/Brussels',   // device timezone (tz database name)
   geoCountryCode: 'DE',          // route device traffic via a proxy in this country
   throttleNetwork: '3G',         // or { downloadSpeed, uploadSpeed, latency, loss }
+  autoGrantPermissions: true,    // Android: auto-grant app permission dialogs
+  autoAcceptAlerts: true,        // iOS: auto-accept system permission alerts
   screenshots: true,             // screenshot at every step (default false)
   video: true,                   // session video (default true)
   recordLogs: 'strip-parameters',// command logs: true | false | 'strip-parameters'
@@ -126,6 +133,67 @@ new TestingBotDriver({
 });
 ```
 
+## TestingBot commands inside tests
+
+Some TestingBot features are runtime commands rather than session
+capabilities. Import the `testingbot` helper and call them from a test body —
+it targets the device session mobilewright connected for that test:
+
+```ts
+import { test, expect } from '@mobilewright/test';
+import { testingbot } from '@testingbot/mobilewright-driver';
+
+test('checkout survives a slow network', async ({ device, screen, bundleId }) => {
+  await device.launchApp(bundleId);
+
+  await testingbot.annotate('starting checkout');   // shows in the session timeline
+  await testingbot.throttle('3G');
+  await expect(screen.getByText('Order placed')).toBeVisible();
+
+  console.log(testingbot.dashboardUrl());
+});
+```
+
+### Available commands
+
+| Command | TestingBot command | What it does |
+| --- | --- | --- |
+| `throttle(conditions)` | `tb:throttle` | Network conditions mid-test: `'Edge'`, `'3G'`, `'4G'`, `'airplane'`, `'disable'`, or `{ downloadSpeed, uploadSpeed, latency, loss }` (kb/s, ms). Reset automatically at the end of the test. |
+| `annotate(text)` | `tb:test-context` | Logs a step into the session's command list, so the timeline shows what the test was doing. |
+| `setName(name)` | `tb:test-name` | Names the session on the dashboard. |
+| `setBuild(build)` | `tb:test-build` | Groups the session under a build. |
+| `setTags([...])` | `tb:test-tags` | Tags the session. |
+| `setResult(passed)` | `tb:test-result` | Overrides the pass/fail verdict (the driver reports it automatically — use this only for outcomes mobilewright cannot see). |
+| `updateInfo({...})` | `tb:test-info` | Bulk update: `name`, `build`, `public`, `statusMessage`, `extra`. |
+| `breakpoint()` | `tb:break` | Pauses the session for manual inspection with a live view. Debugging only — never leave it in CI. |
+| `shell(command, args)` | `mobile: shell` | ADB shell on Android (whitelisted subset on physical devices). |
+| `execute(script, ...args)` | any | Escape hatch for any Appium or TestingBot execute-script command. |
+| `sessionId()` / `dashboardUrl()` | — | This test's TestingBot session id and dashboard link. |
+
+Notes:
+
+- **Throttling is reset automatically** when the test's device session is
+  released, so slow-network conditions never leak into the next test that
+  reuses the device.
+- Calling a command outside a test body raises an explanatory error rather
+  than a null-reference.
+- `tb:intercept` and `tb:network` (request mocking and network logs) are
+  Chrome/Edge-only on TestingBot and are therefore not exposed here.
+
+### Recipe: name every session after its test
+
+```ts
+test.beforeEach(async ({ device }, testInfo) => {
+  await testingbot.setName(testInfo.title);
+  await testingbot.setTags([testInfo.project.name]);
+});
+```
+
+Requesting the `device` fixture is what makes the session exist before the
+hook runs. With `sessionPerTest: true` each session gets exactly one name;
+in pooled mode the last test to run on a session wins (the driver still
+reports per-test verdicts afterwards — see above).
+
 ## Testing localhost / staging servers (TestingBot Tunnel)
 
 Either run a [TestingBot Tunnel](https://testingbot.com/support/tunnel) yourself and pass its identifier:
@@ -169,8 +237,10 @@ jobs:
 | `TestingBot sessions must start with an app` | Declare the app in the driver's `apps` option (per platform / device type). |
 | `No TestingBot real device matches ...` / `No TestingBot simulator matches ...` | The criteria matched nothing in the catalog — check [available devices](https://testingbot.com/support/devices), loosen `osVersion`/`deviceName`. |
 | Allocation waits for minutes | The matching device is busy; TestingBot queues the session until it frees up (bounded by `allocationTimeout`). |
+| `Test timeout ... while setting up "device"` | More `workers` than your plan's parallel limit: TestingBot queues up to 2× the limit server-side and the driver waits out the rest, all inside the test-scoped device fixture. The driver warns with your plan's number — set `workers` to at most that, or raise the mobilewright `timeout`. |
 | `... is a simulator-only build and cannot be installed on a real device` | Build a test-signed `.ipa` for `deviceType: 'real'` projects. |
-| `cannot install "..." mid-session` | TestingBot has no mid-session installs — point `installApps` and the driver's `apps` at the same build. |
+| `"..." is not installed on this device` | The config's `bundleId` is not the package id of the build in `apps` (check with `aapt2 dump packagename app.apk`), or a stale `bundleId`/env override is in play. |
+| `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; use `sessionPerTest: true` for guaranteed per-test naming. |
 | `DEBUG=testingbot:*` | Prints every allocation, hub command, upload, and report the driver performs. |
@@ -180,11 +250,12 @@ jobs:
 | mobilewright concept | TestingBot implementation |
 | --- | --- |
 | device allocation | Appium session on `hub.testingbot.com` (the session UUID is the device id); busy devices queue server-side |
-| app install | uploaded to TestingBot storage at allocation time and passed as `appium:app` — no mid-session installs |
+| app install | uploaded to TestingBot storage at allocation time and passed as `appium:app`, helper apps as `appium:otherApps` (re-signed automatically for real iOS) — no mid-session installs |
 | taps/swipes/gestures | W3C pointer actions |
 | view hierarchy | Appium page source, mapped to mobilewright's `ViewNode` tree |
 | webviews | Appium contexts (`webViewBridge`) |
 | pass/fail reporting | `PUT /v1/tests/:session` via the `TestObserver` hooks |
+| git metadata | commit/branch/author/subject from the run report → session `extra` + branch tag |
 | video | recorded by TestingBot; `startRecording({ output })` downloads the MP4 locally at run end |
 
 ## Current limitations
@@ -206,6 +277,19 @@ npm run build
 
 Live e2e tests against a real TestingBot account live in `e2e/` (see `e2e/mobilewright.config.ts`).
 
+### Releasing
+
+The version bump, tag and GitHub release are made locally — the TestingBot
+org's IP allow list blocks GitHub-hosted runners from pushing here — and the
+Release workflow then publishes to npm via trusted publishing (OIDC), so no
+npm token exists anywhere:
+
+```bash
+npm version minor -m "Release v%s"      # patch | minor | major
+git push --follow-tags
+gh release create "v$(node -p "require('./package.json').version")" --generate-notes
+```
+
 ## License
 
 Apache-2.0

package/dist/capabilities.d.ts

@@ -16,12 +16,13 @@ export interface PinnedDevice {
  * ('ios-real' beats 'ios'). Returns the raw configured value: a local path
  * or a tb:// / https URL (the caller uploads local paths).
  */
-export declare function appForCriteria(criteria: Pick<AllocationCriteria, 'platform' | 'deviceType'>, apps: Partial<Record<AppSlot, string>>): string | undefined;
+export declare function appsForCriteria(criteria: Pick<AllocationCriteria, 'platform' | 'deviceType'>, apps: Partial<Record<AppSlot, string | string[]>>): string[];
 /**
  * Build the W3C new-session payload for a set of allocation criteria.
  * Pure — catalog lookups and app uploads happen in the caller; a pinned
  * device (real-device allocations) overrides name/version wildcards, and
- * `appUrl` is the already-uploaded app under test (tb:// or https).
+ * `appUrls` are the already-uploaded apps (tb:// or https): the first is the
+ * app under test, any others ride along as `appium:otherApps`.
  */
-export declare function buildCapabilities(criteria: AllocationCriteria, options: ResolvedOptions, pinned?: PinnedDevice, appUrl?: string): W3CCapabilities;
+export declare function buildCapabilities(criteria: AllocationCriteria, options: ResolvedOptions, pinned?: PinnedDevice, appUrls?: string[]): W3CCapabilities;
 //# sourceMappingURL=capabilities.d.ts.map

package/dist/capabilities.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,KAAK,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE7D,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;CACvC;AAED,sDAAsD;AACtD,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,+DAA+D;IAC/D,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAKD;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,IAAI,CAAC,kBAAkB,EAAE,UAAU,GAAG,YAAY,CAAC,EAC7D,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,GACrC,MAAM,GAAG,SAAS,CAQpB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,EAAE,eAAe,EACxB,MAAM,CAAC,EAAE,YAAY,EACrB,MAAM,CAAC,EAAE,MAAM,GACd,eAAe,CA6FjB"}
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,KAAK,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAE7D,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;CACvC;AAED,sDAAsD;AACtD,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,+DAA+D;IAC/D,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAKD;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,IAAI,CAAC,kBAAkB,EAAE,UAAU,GAAG,YAAY,CAAC,EAC7D,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC,GAChD,MAAM,EAAE,CAOV;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,kBAAkB,EAC5B,OAAO,EAAE,eAAe,EACxB,MAAM,CAAC,EAAE,YAAY,EACrB,OAAO,GAAE,MAAM,EAAO,GACrB,eAAe,CAwGjB"}

package/dist/capabilities.js

@@ -5,24 +5,24 @@ const REGEX_METACHARS = /[.*+?^${}()|[\]\\]/;
  * ('ios-real' beats 'ios'). Returns the raw configured value: a local path
  * or a tb:// / https URL (the caller uploads local paths).
  */
-export function appForCriteria(criteria, apps) {
+export function appsForCriteria(criteria, apps) {
     const platform = criteria.platform;
     if (!platform)
-        return undefined;
-    if (criteria.deviceType) {
-        const specific = apps[`${platform}-${criteria.deviceType}`];
-        if (specific)
-            return specific;
-    }
-    return apps[platform];
+        return [];
+    const specific = criteria.deviceType ? apps[`${platform}-${criteria.deviceType}`] : undefined;
+    const configured = specific ?? apps[platform];
+    if (!configured)
+        return [];
+    return Array.isArray(configured) ? configured.filter(Boolean) : [configured];
 }
 /**
  * Build the W3C new-session payload for a set of allocation criteria.
  * Pure — catalog lookups and app uploads happen in the caller; a pinned
  * device (real-device allocations) overrides name/version wildcards, and
- * `appUrl` is the already-uploaded app under test (tb:// or https).
+ * `appUrls` are the already-uploaded apps (tb:// or https): the first is the
+ * app under test, any others ride along as `appium:otherApps`.
  */
-export function buildCapabilities(criteria, options, pinned, appUrl) {
+export function buildCapabilities(criteria, options, pinned, appUrls = []) {
     const platform = criteria.platform;
     if (!platform) {
         throw new Error('TestingBotDriver.allocate requires a platform ("ios" or "android"). ' +
@@ -35,8 +35,13 @@ export function buildCapabilities(criteria, options, pinned, appUrl) {
         platformName: platform === 'ios' ? 'iOS' : 'Android',
         'appium:automationName': platform === 'ios' ? 'XCUITest' : 'UiAutomator2',
     };
+    const [appUrl, ...otherApps] = appUrls;
     if (appUrl)
         caps['appium:app'] = appUrl;
+    // TestingBot installs these alongside the app under test (and re-signs them
+    // for real iOS devices).
+    if (otherApps.length)
+        caps['appium:otherApps'] = otherApps;
     // TestingBot has no app-less sessions: every session must start with an
     // app or a browser. Fail here with guidance instead of a cryptic hub error.
     const escape = options.capabilities;
@@ -76,6 +81,12 @@ export function buildCapabilities(criteria, options, pinned, appUrl) {
             caps['appium:platformVersion'] = criteria.osVersion;
         }
     }
+    if (platform === 'android' && options.autoGrantPermissions !== undefined) {
+        caps['appium:autoGrantPermissions'] = options.autoGrantPermissions;
+    }
+    if (platform === 'ios' && options.autoAcceptAlerts !== undefined) {
+        caps['appium:autoAcceptAlerts'] = options.autoAcceptAlerts;
+    }
     const tbOptions = {
         key: options.key,
         secret: options.secret,

package/dist/capabilities.js.map

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

package/dist/driver.d.ts

@@ -1,5 +1,6 @@
 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 TestingBotDriverOptions } from './options.js';
+import { type ThrottlePreset, type ThrottleProfile } from './session-commands.js';
 import { AppiumWebViewBridge } from './webview.js';
 /**
  * Mobilewright driver for TestingBot's device cloud.
@@ -35,6 +36,11 @@ export declare class TestingBotDriver implements MobilewrightDriver {
     private active;
     /** sessionPerTest: pool slots whose original session this instance has already probed/used. */
     private readonly rotatedDeviceIds;
+    /** Plan limits from GET /v1/user, for the over-parallelism warning. */
+    private userInfo;
+    /** Allocations currently waiting on POST /session. */
+    private inFlightAllocations;
+    private warnedAboutParallelism;
     constructor(options?: TestingBotDriverOptions);
     prepare(): Promise<void>;
     allocate(criteria: AllocationCriteria, _takenDeviceIds: ReadonlySet<string>, signal?: AbortSignal): Promise<AllocatedDevice>;
@@ -44,6 +50,12 @@ export declare class TestingBotDriver implements MobilewrightDriver {
     disconnect(): Promise<void>;
     /** Create a new hub session for this slot from the connect() config. */
     private startFreshSession;
+    /** 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. */
+    currentSessionId(): string;
+    /** `tb:throttle` — change network conditions mid-test. */
+    throttle(conditions: ThrottlePreset | ThrottleProfile): Promise<void>;
     /**
      * Best-effort, fire-and-forget per the protocol: Android animation scales
      * via `mobile: shell` (may be unavailable depending on TestingBot's Appium
@@ -65,6 +77,15 @@ export declare class TestingBotDriver implements MobilewrightDriver {
     getOrientation(): Promise<Orientation>;
     setOrientation(orientation: Orientation): Promise<void>;
     launchApp(bundleId: string, opts?: LaunchOptions): Promise<void>;
+    /**
+     * Appium reports a missing package and a missing launcher activity with the
+     * same "Unable to resolve the launchable activity" text. Ask the device
+     * which case it is: a bundleId that is simply not installed (the usual
+     * cause — the config's `bundleId` does not match the package id of the
+     * build in `apps`) deserves a completely different fix than a real
+     * launcher-activity problem.
+     */
+    private explainLaunchFailure;
     terminateApp(bundleId: string): Promise<void>;
     listApps(): Promise<AppInfo[]>;
     getForegroundApp(): Promise<AppInfo>;
@@ -75,6 +96,14 @@ export declare class TestingBotDriver implements MobilewrightDriver {
     startRecording(opts: RecordingOptions): Promise<void>;
     stopRecording(): Promise<RecordingResult>;
     private session;
+    /**
+     * Requesting more parallel sessions than the plan allows is not fatal —
+     * TestingBot queues the extras — but the wait happens inside mobilewright's
+     * test-scoped device fixture, so queued tests can hit the Playwright test
+     * timeout with a confusing "timed out setting up device" failure. Warn once
+     * with the actual numbers instead.
+     */
+    private warnIfOverParallel;
     private unpin;
 }
 //# sourceMappingURL=driver.d.ts.map

package/dist/driver.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../src/driver.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,kBAAkB,EACvB,KAAK,OAAO,EACZ,KAAK,gBAAgB,EACrB,KAAK,UAAU,EACf,KAAK,cAAc,EAEnB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,WAAW,EAEhB,KAAK,gBAAgB,EACrB,KAAK,eAAe,EACpB,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,OAAO,EACZ,KAAK,cAAc,EACnB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,QAAQ,EACd,MAAM,wBAAwB,CAAC;AAehC,OAAO,EAA4D,KAAK,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAItH,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AA8CnD;;;;;;;;GAQG;AACH,qBAAa,gBAAiB,YAAW,kBAAkB;IACzD,QAAQ,CAAC,QAAQ,EAAE,YAAY,GAAG,SAAS,CAAC;IAC5C,6EAA6E;IAC7E,QAAQ,CAAC,aAAa,EAAE,mBAAmB,CAAC;IAE5C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkB;IAC1C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAkB;IACtC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAgB;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;IACxC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAa;IACrC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuB;IAE9C,4EAA4E;IAC5E,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAuC;IACjE;;;wBAGoB;IACpB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAuC;IACrE,0EAA0E;IAC1E,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA6B;IACvD,kEAAkE;IAClE,OAAO,CAAC,MAAM,CAA4B;IAC1C,+FAA+F;IAC/F,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAqB;gBAE1C,OAAO,GAAE,uBAA4B;IA6B3C,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAQxB,QAAQ,CACZ,QAAQ,EAAE,kBAAkB,EAC5B,eAAe,EAAE,WAAW,CAAC,MAAM,CAAC,EACpC,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,eAAe,CAAC;IAwGrB,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAcxC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAgBxB,OAAO,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC;IAuCnD,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAgCjC,wEAAwE;YAC1D,iBAAiB;IAgC/B;;;;OAIG;IACG,mBAAmB,CAAC,QAAQ,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAoB5D,gBAAgB,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IASvC,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxC,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI9C,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIjE,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUrC,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAqBxC,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAoB1B,KAAK,CAAC,SAAS,EAAE,cAAc,EAAE,IAAI,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAMpE,OAAO,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAIjD,WAAW,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IAelD,UAAU,CAAC,IAAI,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC;IASrD,aAAa,IAAI,OAAO,CAAC,UAAU,CAAC;IAoBpC,cAAc,IAAI,OAAO,CAAC,WAAW,CAAC;IAKtC,cAAc,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAQvD,SAAS,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC;IAWhE,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAK7C,QAAQ,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;IAU9B,gBAAgB,IAAI,OAAO,CAAC,OAAO,CAAC;IAgBpC,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAuBvC,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAO7C,WAAW,CAAC,IAAI,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAM7D,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBnC,cAAc,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAUrD,aAAa,IAAI,OAAO,CAAC,eAAe,CAAC;IAmB/C,OAAO,CAAC,OAAO;IAKf,OAAO,CAAC,KAAK;CAKd"}
+{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../src/driver.ts"],"names":[],"mappings":"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"}

package/dist/driver.js

@@ -3,7 +3,7 @@ import createDebug from 'debug';
 import { NoDeviceAvailableError, } from '@mobilewright/protocol';
 import { doubleTapActions, gestureActions, longPressActions, swipeActions, tapActions, } from './actions.js';
 import { AppStorage } from './app-storage.js';
-import { appForCriteria, buildCapabilities } from './capabilities.js';
+import { appsForCriteria, buildCapabilities } from './capabilities.js';
 import { DeviceCatalog } from './device-catalog.js';
 import { SessionNotActiveError, toAllocationError, withAllocationContext } from './errors.js';
 import { Keepalive } from './keepalive.js';
@@ -12,6 +12,7 @@ import { TestingBotTestObserver } from './observer.js';
 import { requireCredentials, resolveOptions } from './options.js';
 import { RestApiClient } from './rest-api.js';
 import { RunLog } from './run-log.js';
+import { setActiveDriver } from './session-commands.js';
 import { TunnelManager } from './tunnel.js';
 import { AppiumWebViewBridge } from './webview.js';
 import { WebDriverClient } from './webdriver-client.js';
@@ -71,6 +72,11 @@ export class TestingBotDriver {
     active;
     /** sessionPerTest: pool slots whose original session this instance has already probed/used. */
     rotatedDeviceIds = new Set();
+    /** Plan limits from GET /v1/user, for the over-parallelism warning. */
+    userInfo;
+    /** Allocations currently waiting on POST /session. */
+    inFlightAllocations = 0;
+    warnedAboutParallelism = false;
     constructor(options = {}) {
         this.options = resolveOptions(options);
         this.hub = new WebDriverClient(this.options.hubUrl, this.options.commandTimeout);
@@ -93,6 +99,7 @@ export class TestingBotDriver {
                     return [...byId.values()];
                 },
                 build: this.options.build,
+                extra: this.options.extra,
                 recordings: () => this.runLog.recordings(),
             });
     }
@@ -100,14 +107,15 @@ export class TestingBotDriver {
     async prepare() {
         requireCredentials(this.options);
         this.runLog.truncate(); // drop session/app records from any previous run
-        await this.api.getUser();
-        debug('credentials verified against %s', this.options.apiUrl);
+        this.userInfo = await this.api.getUser();
+        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) {
         requireCredentials(this.options);
         // takenDeviceIds is unused: every allocate() creates a fresh, exclusive
         // WebDriver session; physical-device contention is handled server-side.
+        this.warnIfOverParallel(criteria);
         let pinned;
         let reservedName;
         if (criteria.deviceId) {
@@ -128,19 +136,19 @@ export class TestingBotDriver {
         }
         // TestingBot sessions must start with an app — resolve and upload the
         // configured one now so it can ride along in the allocation caps.
-        let appUrl;
-        const configuredApp = appForCriteria(criteria, this.options.apps);
-        if (configuredApp) {
-            appUrl = isRemoteApp(configuredApp)
-                ? configuredApp
-                : (await this.storage.ensureUploaded(configuredApp, criteria.deviceType)).app_url;
-            if (this.options.sessionPerTest && criteria.platform) {
-                // Workers rotating sessions per test reuse this upload instead of
-                // re-uploading the binary once per worker process.
-                this.runLog.append({ type: 'app', platform: criteria.platform, deviceType: criteria.deviceType, url: appUrl });
-            }
-        }
-        const capabilities = buildCapabilities(criteria, this.options, pinned, appUrl);
+        const configuredApps = appsForCriteria(criteria, this.options.apps);
+        const appUrls = [];
+        for (const app of configuredApps) {
+            appUrls.push(isRemoteApp(app)
+                ? app
+                : (await this.storage.ensureUploaded(app, criteria.deviceType)).app_url);
+        }
+        if (appUrls.length && this.options.sessionPerTest && criteria.platform) {
+            // Workers rotating sessions per test reuse these uploads instead of
+            // re-uploading the binaries once per worker process.
+            this.runLog.append({ type: 'app', platform: criteria.platform, deviceType: criteria.deviceType, urls: appUrls });
+        }
+        const capabilities = buildCapabilities(criteria, this.options, pinned, appUrls);
         debug('allocating: %o', { ...capabilities.alwaysMatch, 'tb:options': '[redacted]' });
         if (signal?.aborted) {
             throw new NoDeviceAvailableError('allocation aborted before it started');
@@ -152,6 +160,7 @@ export class TestingBotDriver {
         // pool aborts — is handled by deleting the session that slipped through.
         let sessionId;
         let caps;
+        this.inFlightAllocations += 1;
         try {
             const controller = new AbortController();
             const onAbort = () => controller.abort();
@@ -184,6 +193,9 @@ export class TestingBotDriver {
                 this.unpin(reservedName);
             throw err;
         }
+        finally {
+            this.inFlightAllocations -= 1;
+        }
         const platform = criteria.platform ?? (String(caps['platformName']).toLowerCase() === 'ios' ? 'ios' : 'android');
         const session = {
             sessionId,
@@ -245,6 +257,7 @@ export class TestingBotDriver {
             // Liveness probe — also validates the id belongs to a live TB session.
             await this.hub.get(poolDeviceId, '/orientation', { timeout });
             this.active = { sessionId: poolDeviceId, platform: config.platform, deviceType: config.deviceType, connectedAt: Date.now() };
+            setActiveDriver(this);
             debug('connected to session %s', poolDeviceId);
             return { deviceId: poolDeviceId, platform: config.platform };
         }
@@ -266,14 +279,23 @@ export class TestingBotDriver {
         }
         sessionId ??= await this.startFreshSession(config);
         this.active = { sessionId, platform: config.platform, deviceType: config.deviceType, connectedAt: Date.now() };
+        setActiveDriver(this);
         debug('connected to session %s (slot %s)', sessionId, poolDeviceId);
         return { deviceId: poolDeviceId, platform: config.platform };
     }
     async disconnect() {
         const session = this.active;
         this.active = undefined;
+        setActiveDriver(undefined);
         if (!session)
             return;
+        if (session.throttled) {
+            // A pooled session outlives the test: reset network conditions so they
+            // cannot leak into whichever test gets this slot next.
+            await this.hub.execute(session.sessionId, 'tb:throttle', ['disable']).catch((err) => {
+                debug('could not reset throttling on %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(). Still record this test's interval —
@@ -317,21 +339,38 @@ export class TestingBotDriver {
             pinned = await this.catalog.pickVirtualDevice(criteria);
         }
         // Prefer the app the coordinator already uploaded for this platform.
-        let appUrl = criteria.platform ? this.runLog.appUrlFor(criteria.platform, criteria.deviceType) : undefined;
-        if (!appUrl) {
-            const configuredApp = appForCriteria(criteria, this.options.apps);
-            if (configuredApp) {
-                appUrl = isRemoteApp(configuredApp)
-                    ? configuredApp
-                    : (await this.storage.ensureUploaded(configuredApp, criteria.deviceType)).app_url;
+        let appUrls = criteria.platform ? this.runLog.appUrlsFor(criteria.platform, criteria.deviceType) : undefined;
+        if (!appUrls?.length) {
+            appUrls = [];
+            for (const app of appsForCriteria(criteria, this.options.apps)) {
+                appUrls.push(isRemoteApp(app)
+                    ? app
+                    : (await this.storage.ensureUploaded(app, criteria.deviceType)).app_url);
             }
         }
-        const capabilities = buildCapabilities(criteria, this.options, pinned, appUrl);
+        const capabilities = buildCapabilities(criteria, this.options, pinned, appUrls);
         const { sessionId } = await this.hub.newSession(capabilities, { timeout: this.options.allocationTimeout });
         this.runLog.append({ type: 'session', sessionId });
         debug('started per-test session %s — https://testingbot.com/members/tests/%s', sessionId, sessionId);
         return sessionId;
     }
+    // ─── TestingBot-specific session commands ─────────────────────
+    /** Run any Appium/TestingBot execute-script command on the live session. */
+    async executeScript(script, ...args) {
+        return await this.hub.execute(this.session().sessionId, script, args);
+    }
+    /** WebDriver session id of the device this instance is connected to. */
+    currentSessionId() {
+        return this.session().sessionId;
+    }
+    /** `tb:throttle` — change network conditions mid-test. */
+    async throttle(conditions) {
+        const session = this.session();
+        await this.hub.execute(session.sessionId, 'tb:throttle', [conditions]);
+        const off = conditions === 'disable' || (typeof conditions === 'object' && conditions.disable === true);
+        session.throttled = !off;
+        debug('throttle %o applied to %s', conditions, session.sessionId);
+    }
     // ─── MobilewrightSession: device settings ──────────────────────
     /**
      * Best-effort, fire-and-forget per the protocol: Android animation scales
@@ -488,7 +527,48 @@ export class TestingBotDriver {
                 }]);
             return;
         }
-        await this.hub.execute(sessionId, 'mobile: activateApp', [{ appId: bundleId, bundleId }]);
+        try {
+            await this.hub.execute(sessionId, 'mobile: activateApp', [{ appId: bundleId, bundleId }]);
+        }
+        catch (err) {
+            if (err instanceof Error && /launchable activity|No activity found|not installed/i.test(err.message)) {
+                throw await this.explainLaunchFailure(bundleId, err);
+            }
+            throw err;
+        }
+    }
+    /**
+     * Appium reports a missing package and a missing launcher activity with the
+     * same "Unable to resolve the launchable activity" text. Ask the device
+     * which case it is: a bundleId that is simply not installed (the usual
+     * cause — the config's `bundleId` does not match the package id of the
+     * build in `apps`) deserves a completely different fix than a real
+     * launcher-activity problem.
+     */
+    async explainLaunchFailure(bundleId, err) {
+        const session = this.session();
+        let installed;
+        try {
+            installed = await this.hub.execute(session.sessionId, 'mobile: isAppInstalled', [
+                { appId: bundleId, bundleId },
+            ]);
+        }
+        catch {
+            // Fall through with an unknown install state.
+        }
+        if (installed === false) {
+            const configured = appsForCriteria({ platform: session.platform, deviceType: session.deviceType }, this.options.apps).map((a) => `"${a}"`).join(', ');
+            return new Error(`TestingBotDriver: "${bundleId}" is not installed on this device, so it cannot be launched. ` +
+                `The session was started with ${configured || 'the app from the driver\'s `apps` option'}` +
+                ` — make sure \`bundleId\` in your mobilewright config is that build's package id` +
+                (session.platform === 'android'
+                    ? ' (check it with: aapt2 dump packagename app.apk).'
+                    : ' (check it with: unzip -p app.ipa "Payload/*.app/Info.plist" | plutil -extract CFBundleIdentifier raw -).') +
+                `\n${err.message}`);
+        }
+        return new Error(`TestingBotDriver could not launch "${bundleId}": the app is installed but has no resolvable ` +
+            "launcher activity. Pass one explicitly — device.launchApp(bundleId, { activity: '.MainActivity' }) — " +
+            'or build the app with a MAIN/LAUNCHER intent filter.\n' + err.message);
     }
     async terminateApp(bundleId) {
         const { sessionId } = this.session();
@@ -525,15 +605,18 @@ export class TestingBotDriver {
         // at allocation time via appium:app (declared in the driver's `apps`
         // option). This call only verifies the request matches that app.
         const session = this.session();
-        const declared = appForCriteria({ platform: session.platform, deviceType: session.deviceType }, this.options.apps);
-        if (declared && (isRemoteApp(declared) || await sameFileContents(declared, path))) {
-            debug('installApp(%s): already installed at allocation via appium:app, skipping', path);
-            return;
+        const declared = appsForCriteria({ platform: session.platform, deviceType: session.deviceType }, this.options.apps);
+        for (const app of declared) {
+            if (isRemoteApp(app) || await sameFileContents(app, path)) {
+                debug('installApp(%s): already installed at allocation via appium:app/otherApps, skipping', path);
+                return;
+            }
         }
         throw new Error(`TestingBotDriver cannot install "${path}" mid-session: TestingBot sessions start with the ` +
-            "app declared in the driver's `apps` option and support no later installs. " +
-            (declared
-                ? `The session was started with "${declared}" instead — point installApps and apps at the same build.`
+            "apps declared in the driver's `apps` option and support no later installs. " +
+            (declared.length
+                ? `The session was started with ${declared.map((a) => `"${a}"`).join(', ')} instead — list every app ` +
+                    'you install in both `installApps` and the driver\'s `apps` option (first entry = app under test).'
                 : "Declare it when constructing the driver: new TestingBotDriver({ apps: { " +
                     `'${session.platform}${session.deviceType ? `-${session.deviceType}` : ''}': '${path}' } }).`));
     }
@@ -595,6 +678,29 @@ export class TestingBotDriver {
             throw new SessionNotActiveError();
         return this.active;
     }
+    /**
+     * Requesting more parallel sessions than the plan allows is not fatal —
+     * TestingBot queues the extras — but the wait happens inside mobilewright's
+     * test-scoped device fixture, so queued tests can hit the Playwright test
+     * timeout with a confusing "timed out setting up device" failure. Warn once
+     * with the actual numbers instead.
+     */
+    warnIfOverParallel(criteria) {
+        if (this.warnedAboutParallelism || !this.userInfo)
+            return;
+        const isReal = criteria.deviceType === 'real';
+        const limit = isReal ? this.userInfo.max_concurrent_mobile : this.userInfo.max_concurrent;
+        if (typeof limit !== 'number' || limit <= 0)
+            return;
+        const wanted = this.allocated.size + this.inFlightAllocations + 1;
+        if (wanted > limit) {
+            this.warnedAboutParallelism = true;
+            console.warn(`TestingBotDriver: this run wants ${wanted}+ parallel ${isReal ? 'device' : 'VM'} sessions but the ` +
+                `plan allows ${limit} (TestingBot queues up to ${limit * 2} more server-side; the rest wait for a ` +
+                `freed slot). The wait counts against mobilewright's test timeout — set workers: ${limit} (or fewer) ` +
+                'in mobilewright.config.ts, or raise the test timeout to cover the expected queue time.');
+        }
+    }
     unpin(name) {
         const count = this.pinCounts.get(name) ?? 0;
         if (count <= 1)