diff --git a/.changeset/which-device-boots.md b/.changeset/which-device-boots.md new file mode 100644 index 0000000000..b6e1219445 --- /dev/null +++ b/.changeset/which-device-boots.md @@ -0,0 +1,5 @@ +--- +"@e2e-dev/mobile": patch +--- + +The `device` option's documentation now says a paired iPhone or iPad that is reachable counts as booted, and that a shut-down device boots in tiers: on iOS an iPhone, then an iPad, then an Apple TV; on Android a phone or tablet, then a TV. diff --git a/docs/mobile.mdx b/docs/mobile.mdx index 42ebe6e28d..427348338e 100644 --- a/docs/mobile.mdx +++ b/docs/mobile.mdx @@ -465,8 +465,10 @@ mobile({ platform: 'ios', device: ['iPhone 17', 'iPhone 17 Pro'] }) ``` Without `device`, the engine uses booted devices, up to the worker limit. -If none are booted, it boots a shut-down one: newest OS first, then name -order. Two workers never drive the same device. +A paired iPhone or iPad that is reachable (USB or network) counts as booted. +If none are booted, it boots a shut-down one: on iOS an iPhone before an iPad +before an Apple TV, on Android a phone or tablet before a TV, then the newest +OS, then name order. Two workers never drive the same device. ## Agent tools @@ -527,8 +529,8 @@ mobile({ platform: 'ios', device: 'QA iPhone' }) Use the name, not the id. The engine reads a `device` string as an id only for a simulator UDID or an `emulator-` serial. The first device with a matching name wins, so give each phone a unique name. Without `device`, a -connected phone counts as booted and joins the pool beside booted -simulators. +paired iPhone or iPad that is reachable (USB or network), or a connected +Android phone, counts as booted and joins the pool beside booted simulators. Set the phone up one time: diff --git a/docs/reference/mobile.mdx b/docs/reference/mobile.mdx index ee021e7edd..ddfff62792 100644 --- a/docs/reference/mobile.mdx +++ b/docs/reference/mobile.mdx @@ -122,10 +122,12 @@ mobile({ platform: 'android' }); * drives the `n`th, so `workers` at or above the pool size runs the target's * files across every device at once. Omitted, the pool is every booted device * of the platform at `prepare` that no other agent-device session holds, as - * many as the run has slots; with none booted, agent-device boots a shut-down - * one: a phone or tablet over a TV, then the newest OS, then name order (a - * stopped Android emulator reports no OS version, so the name decides). With - * every booted one held, `prepare` fails. A `DeviceProvider` leases hosted devices + * many as the run has slots. A paired iPhone or iPad that is reachable (USB or network) counts as booted and + * joins the pool. With none booted, agent-device boots a shut-down one: on + * iOS an iPhone over an iPad over an Apple TV, on Android a phone or tablet + * over a TV, then the newest OS, then name order (a stopped Android emulator + * reports no OS version, so the name decides). With every booted one held, + * `prepare` fails. A `DeviceProvider` leases hosted devices * instead: one per worker slot at `prepare`, each driven through the daemon * and client configuration the lease names. A replacement worker resumes a * healthy agent-device session on the same lease. Forced worker shutdown diff --git a/packages/mobile/README.md b/packages/mobile/README.md index baca8918c4..ddc3cb12d5 100644 --- a/packages/mobile/README.md +++ b/packages/mobile/README.md @@ -69,7 +69,7 @@ the other old app options are `INVALID_CONFIG` naming their key under `app`. | Option | Meaning | | --- | --- | | `platform` | `'ios'` or `'android'`. | -| `device` | Simulator or emulator name or UDID, or a connected phone's name. A list is a pool: one worker per entry, worker slot `n` driving the `n`th. Omitted, every booted device of the platform is the pool, as many as the run has slots. | +| `device` | Simulator or emulator name or UDID, or a paired iPhone or iPad's name or a connected Android phone's name. A list is a pool: one worker per entry, worker slot `n` driving the `n`th. Omitted, every booted device of the platform is the pool, as many as the run has slots, a reachable paired iPhone or iPad included; with none booted, agent-device boots one (on iOS an iPhone over an iPad over an Apple TV, on Android a phone or tablet over a TV, then the newest OS, then name order). | | `session` | agent-device session name, before the worker slot: slot `n` drives its device under `-`, `e2e--` by default. One run per session at a time. | | `snapshot` | `'full'` (default, includes static text) or `'interactive'` (actionable nodes only). | | `settle` | Milliseconds the UI must hold still after an agent action before the agent observes again, default `150`; `false` skips the wait. A test's steps do not settle, except `device.back()`; `expect` verifies their outcome. | diff --git a/packages/mobile/src/options.ts b/packages/mobile/src/options.ts index 26442afe4b..4b497e8a7a 100644 --- a/packages/mobile/src/options.ts +++ b/packages/mobile/src/options.ts @@ -60,10 +60,12 @@ export interface MobileOptions { * drives the `n`th, so `workers` at or above the pool size runs the target's * files across every device at once. Omitted, the pool is every booted device * of the platform at `prepare` that no other agent-device session holds, as - * many as the run has slots; with none booted, agent-device boots a shut-down - * one: a phone or tablet over a TV, then the newest OS, then name order (a - * stopped Android emulator reports no OS version, so the name decides). With - * every booted one held, `prepare` fails. A `DeviceProvider` leases hosted devices + * many as the run has slots. A paired iPhone or iPad that is reachable (USB or network) counts as booted and + * joins the pool. With none booted, agent-device boots a shut-down one: on + * iOS an iPhone over an iPad over an Apple TV, on Android a phone or tablet + * over a TV, then the newest OS, then name order (a stopped Android emulator + * reports no OS version, so the name decides). With every booted one held, + * `prepare` fails. A `DeviceProvider` leases hosted devices * instead: one per worker slot at `prepare`, each driven through the daemon * and client configuration the lease names. A replacement worker resumes a * healthy agent-device session on the same lease. Forced worker shutdown diff --git a/packages/mobile/src/pool.ts b/packages/mobile/src/pool.ts index 64b7271282..55c31a936e 100644 --- a/packages/mobile/src/pool.ts +++ b/packages/mobile/src/pool.ts @@ -148,7 +148,7 @@ class BootedDevices implements DeviceSource { ); } if (chosen.length === 0) { - info.log(`no booted ${this.platform} device; agent-device boots a shut-down one (newest OS, then name)`); + info.log(`no booted ${this.platform} device; agent-device boots a shut-down one (iPhone over iPad over Apple TV on iOS, phone or tablet over TV on Android, then newest OS, then name)`); return [{}]; } const skipped = held.length === 0 ? '' : `, skipping ${held.length} held by another agent-device session (${heldBy})`; diff --git a/plugins/e2e/skills/e2e/references/setup.md b/plugins/e2e/skills/e2e/references/setup.md index 419fde3964..0afc20fb9a 100644 --- a/plugins/e2e/skills/e2e/references/setup.md +++ b/plugins/e2e/skills/e2e/references/setup.md @@ -366,9 +366,9 @@ export default { `locale` on `browserstack()` or `testmu()`, on a local one set the device's language. - One worker per device. No `device`: every booted simulator or emulator of - the platform, and every connected phone, is the pool, up to `workers`, + the platform, and every reachable paired iPhone or iPad or connected Android phone, is the pool, up to `workers`, minus devices another agent-device session holds (none booted: agent-device boots - a shut-down one, newest OS first, then name order; all held: `prepare` fails); one `device`: one worker whatever `workers` says; a list (`device: + a shut-down one, on iOS an iPhone over an iPad over an Apple TV, on Android a phone or tablet over a TV, then the newest OS, then name order; all held: `prepare` fails); one `device`: one worker whatever `workers` says; a list (`device: ['iPhone 17', 'iPhone 17 Pro']`): an explicit pool. Devices boot in `prepare`, before the run's clock. Two sessions on one device fight over it: for parallel MCP sessions or bug-bash explorers, declare one target per diff --git a/skills/e2e/references/setup.md b/skills/e2e/references/setup.md index 419fde3964..0afc20fb9a 100644 --- a/skills/e2e/references/setup.md +++ b/skills/e2e/references/setup.md @@ -366,9 +366,9 @@ export default { `locale` on `browserstack()` or `testmu()`, on a local one set the device's language. - One worker per device. No `device`: every booted simulator or emulator of - the platform, and every connected phone, is the pool, up to `workers`, + the platform, and every reachable paired iPhone or iPad or connected Android phone, is the pool, up to `workers`, minus devices another agent-device session holds (none booted: agent-device boots - a shut-down one, newest OS first, then name order; all held: `prepare` fails); one `device`: one worker whatever `workers` says; a list (`device: + a shut-down one, on iOS an iPhone over an iPad over an Apple TV, on Android a phone or tablet over a TV, then the newest OS, then name order; all held: `prepare` fails); one `device`: one worker whatever `workers` says; a list (`device: ['iPhone 17', 'iPhone 17 Pro']`): an explicit pool. Devices boot in `prepare`, before the run's clock. Two sessions on one device fight over it: for parallel MCP sessions or bug-bash explorers, declare one target per