Device & App Configs

## Why Detox configuration is a matrix **Detox** is a gray-box end-to-end testing framework for React Native apps: tests written in JavaScript run in Node.js on the host machine and drive a real app on an iOS simulator or an Android emulator or device. Even a small app has several combinations worth testing: an iOS simulator with a debug build, the same simulator with a release build, and the same two builds on Android. Add a tablet or a second OS version and the combinations multiply. Detox handles this with a **static config file** — usually `.detoxrc.js` in the project root — built from three key-value dictionaries. ## The three dictionaries - **`devices`** — named device descriptions. Each has a `type` (`ios.simulator`, `android.emulator`, `android.attached`, `android.genycloud`) and a `device` query, such as `{ type: 'iPhone 15' }` for a simulator or `{ avdName: 'Pixel_7_API_35' }` for an emulator. - **`apps`** — named app descriptions. Each has a `type` (`ios.app` or `android.apk`), a **`binaryPath`** to the built `.app` or `.apk`, and an optional **`build`** shell command that produces it. Android apps may also carry `testBinaryPath` and `reversePorts`. - **`configurations`** — the named entry points. Each pairs one `device` alias with one `app` alias (or an `apps` array for multi-app tests), and may override global sections such as `testRunner`, `artifacts`, `behavior` or `logger` for that pair only. Configuration names are arbitrary strings. `ios.sim.release` and `android.emu.release` are conventions from the file `detox init` generates; the platform actually comes from the device's `type`, not from the name. | Section | Answers the question | Key fields | |---|---|---| | `devices` | Where does the app run? | `type`, `device` query | | `apps` | Which binary, and how is it built? | `type`, `binaryPath`, `build`, `testBinaryPath` | | `configurations` | Which pair is this run? | `device`, `app`, per-config overrides | ## Running one suite on both platforms The reserved scenario for this leaf is the everyday one: the same test files, one iOS simulator run and one Android emulator run. The workflow is: 1. Define one simulator device and one emulator device. 2. Define an `ios.app` and an `android.apk` app, each with its `binaryPath` and `build` command. 3. Define two configurations, for example `ios.sim.release` and `android.emu.release`. 4. Build each binary with `detox build -c <name>`, which simply runs that app's `build` string. 5. Run the suite with `detox test -c <name>` once per configuration, usually as two CI jobs. The test files do not change between the two runs. They use `element(by.id(...))`, `device` and the other Detox globals, which resolve to the platform of whichever configuration was selected. Where behaviour genuinely differs, a test can branch on `device.getPlatform()`, but most suites keep that to a minimum. ## What `detox build` and `detox test` do — and do not do `detox build` is a convenience: it executes the `build` command of the selected configuration's app and nothing else. With `--if-missing` it skips the build when the binary already exists. `detox test` never builds anything. It resolves the configuration, starts a Detox session and spawns the test runner; during the runner's setup Detox allocates a device and installs whatever binary sits at `binaryPath`. A stale binary therefore runs stale native code without any warning, which is a common source of confusion after a native change. ## How Detox picks a configuration The name comes from `-c` / `--configuration`, or from the `DETOX_CONFIGURATION` environment variable when Jest is started directly without the Detox CLI. If none is given, Detox uses `selectedConfiguration` from the config file; failing that, if `configurations` has exactly one entry, it uses that one. Otherwise it stops with a "Cannot determine which configuration to use" error that lists the available names. The config file itself is found by scanning the working directory for `.detoxrc.js`, `.detoxrc.json`, `.detoxrc`, `detox.config.js`, `detox.config.json` and finally a `detox` section in `package.json`, or it is given explicitly with `-C`. ## Useful refinements - **Inline devices and apps.** Aliases are optional; a configuration may embed the device and app objects directly, at the cost of duplication. - **`extends`.** A config can extend a shared preset module; the chain is deep-merged parent to child. - **`--device-name` / `-n`.** Overrides the device query at the command line, so one configuration can be pointed at another simulator model without a new entry. - **Per-configuration overrides.** A configuration may raise the logger level or change `testRunner.args` for that pair only. A candidate who can sketch this file from memory, explain that the device `type` decides the platform, and say that `detox test` installs but never builds, has shown the configuration model interviewers look for.