docs: device matrix via --ios-config/--android-config (#1105) (#97)

* docs: device matrix via --ios-config/--android-config (#1105)

Document running a whole suite across N devices in one upload with repeatable
--ios-config/--android-config, replacing the shell-loop workaround. Covers the
no-cross-product rule, one-platform-per-upload, flow-override precedence, the
cost preview, and the --json device field.

* docs: rename device-matrix flags to --ios-device-matrix/--android-device-matrix (#1105)

Match the CLI rename. The branch is not merged yet, so this lands with the
correct names and no stale --ios-config ever reaches the published docs.

* docs: give the device matrix its own page (#1105)

Move the device-matrix content out of 'Devices & OS Versions' into
configuration/device-matrix.md, alongside Per-flow Devices in the nav — it is a
feature in its own right (flags, cost model, result shape, rules), not a
footnote to the device tables.

- devices-configuration.md keeps the device/OS tables and now links out, instead
  of carrying the old 'submit one upload per device' shell loop, which the matrix
  replaces.
- per-flow-devices.md's tail advised the same obsolete loop; it now points at the
  matrix and explains how the two compose (a flow that names its own device is
  excluded from the fan-out).
- Fixes an 'inits YAML' typo carried over from main.

* Proofread

* Additional proofread

Author: finalerock44

SUMMARY.md

@@ -26,6 +26,7 @@
 * [Environment Variables](configuration/environment-variables.md)
 * [Workspace Configuration](configuration/workspace-config.md)
 * [Per-flow Devices](configuration/per-flow-devices.md)
+* [Device Matrix](configuration/device-matrix.md)
 * [Device Locale](configuration/device-locale.md)
 * [Device Date & Time](configuration/device-datetime.md)
 * [Animations](configuration/disable-animations.md)

configuration/device-matrix.md

@@ -0,0 +1,89 @@
+# Device Matrix
+
+By default every flow in an upload runs on one device, set by the `--ios-device`,
+`--ios-version`, `--android-device` and `--android-api-level` flags on `dcd cloud`.
+
+A **device matrix** runs your whole suite against several devices from a single `dcd cloud`
+invocation. Every flow runs once per device, all under one upload with one console entry.
+
+## Usage
+
+Pass `--ios-device-matrix <device>:<version>` (or `--android-device-matrix <device>:<apiLevel>`) once per device you want. Supported devices and operating systems are listed [here](../getting-started/devices-configuration.md).
+
+### iOS
+
+```bash
+dcd cloud --app-binary-id <id> ./flows \
+  --ios-device-matrix iphone-16-pro:18 \
+  --ios-device-matrix iphone-16-pro:26 \
+  --ios-device-matrix iphone-16-pro-max:26
+# one upload, 3 devices x N flows
+```
+
+### Android
+
+```bash
+dcd cloud --app-binary-id <id> ./flows \
+  --android-device-matrix pixel-7:34 \
+  --android-device-matrix pixel-6:33
+```
+
+Append `:play` to run a cell against a Google Play device:
+
+```bash
+dcd cloud --app-binary-id <id> ./flows \
+  --android-device-matrix pixel-7:34 \
+  --android-device-matrix pixel-7:34:play
+```
+
+Every `--ios-device-matrix` / `--android-device-matrix` names **exactly one device**. There is no
+cross-product: the flags are not combined with each other, or with `--ios-device` / `--ios-version`.
+
+```bash
+# runs exactly these two, and nothing else
+dcd cloud [...] --ios-device-matrix iphone-15:17 --ios-device-matrix iphone-16-plus:26
+```
+
+This is deliberate as not every device supports every OS. Naming each device explicitly means you always get
+exactly what you asked for.
+
+## Cost
+
+A matrix runs one test per (flow x device), so a 4-device matrix over 10 flows is **40 flows**, not 10. Before submitting, the CLI prints the number of flows and what they will cost:
+
+```
+Device matrix
+  cells       4
+  est. cost   $0.32
+  Pixel 7 - API 34   2 flows - $0.16
+  Pixel 6 - API 33   2 flows - $0.16
+```
+
+Rates are per device — iPad and Google Play flows are charged at the advanced rate, as per our [pricing](../billing/test-run-billing.md).
+
+## Results
+
+Each device gets its own result, grouped together in the console so you can compare a flow across devices at a glance.
+
+Under `--json`, every entry in `tests[]` carries a `device` object, so the same flow run on two
+devices is unambiguous:
+
+```json
+{
+  "uploadId": "...",
+  "tests": [
+    { "name": "login.yaml", "status": "PASSED", "device": { "name": "Pixel 7", "osVersion": "34" } },
+    { "name": "login.yaml", "status": "FAILED", "device": { "name": "Pixel 6", "osVersion": "33" } }
+  ]
+}
+```
+
+Without `--async` the run waits for **every** device and exits `0` only if all of them passed. Retrying a single failed result re-runs just that one flow on that one device and not the entire matrix.
+
+## Rules
+
+- Every device and OS must be a supported combination, including Google Play if applicable. An unsupported one is rejected before anything runs so you never get a partial submission.
+
+- One platform per upload. An upload runs one app binary, so `--ios-device-matrix` and `--android-device-matrix` cannot be combined in the same run.
+
+- A flow that names its own device wins. If a flow targets a device in its YAML via [per-flow devices](per-flow-devices.md), it runs once on that device and is excluded from the matrix. Ten flows across four devices with one targeted flow is 37 runs, not 40.

configuration/per-flow-devices.md

@@ -62,17 +62,8 @@ iPhone upload charges that one flow at the advanced rate, and the rest at the st
 
 - Currently not supported on `m1` runners due to device limitations.
 
-## Running a whole suite across several devices
+## Running a suite across several devices
 
 Per-flow targeting picks a device for *one* flow. To run your **entire** suite against several
-devices, submit one upload per device:
-
-```bash
-# iOS
-dcd cloud [...] --ios-device "<device-1>" --ios-version <version-1>
-dcd cloud [...] --ios-device "<device-2>" --ios-version <version-2>
-
-# Android
-dcd cloud [...] --android-device "<device-1>" --android-api-level <version-1>
-dcd cloud [...] --android-device "<device-2>" --android-api-level <version-2>
-```
+devices, use a [device matrix](device-matrix.md) — every flow runs once per device, under a single
+upload.

getting-started/devices-configuration.md

@@ -84,17 +84,8 @@ dcd cloud app.zip test.yaml --ios-device ipad-pro-6th-gen
 
 ### Targeting a single flow
 
-The flags above set the device for the **whole upload**. When only one flow needs a particular device then that flow can name its own device inits YAML instead. See [per-flow-devices.md](../configuration/per-flow-devices.md).
-To run your **entire** suite against more than one device, submit one upload per device:
+The flags above set the device for the whole upload. When only one flow needs a particular device then that flow can name its own device in its YAML instead. See [per-flow-devices.md](../configuration/per-flow-devices.md).
 
-```bash
-for device in iphone-16-pro iphone-16-pro-max; do
-  dcd cloud --app-binary-id <id> ./flows \
-    --ios-device "$device" --ios-version 18 --async
-done
-```
+### Running your suite across several devices
 
-{% hint style="warning" %}
-`--async` matters here. Without it, each `dcd cloud` blocks on its own poll loop waiting for
-results, so the uploads run one after another instead of concurrently.
-{% endhint %}
+To run every flow against several devices from a single `dcd cloud` invocation use a [device matrix](../configuration/device-matrix.md).