Skip to main content
Version: 20.x


The format of Detox config allows you to define inside it multiple device configs in a key-value manner, i.e.:


You can define the device config in two ways: aliased and inlined (per a configuration):

/** @type {Detox.DetoxConfig} */
module.exports = {
devices: {
deviceKey: {
/* … device config … */
/* … */
configurations: {
'example.aliased': {
/* … */
device: 'deviceKey', // (1)
'example.inlined': {
/* … */
device: { // (2)
/* … device config … */


"type": "ios.simulator",
"device": {
// one of these or a combination of them
"id": "D53474CF-7DD1-4673-8517-E75DAD6C34D6",
"type": "iPhone 11 Pro",
"name": "MySim",
"os": "iOS 13.0"


A device config can have the following params:

Configuration ParamsDetails
typeRequired. String Literal. Mandatory property to discern device types: ios.simulator, android.emulator, android.attached, android.genycloud etc.
deviceRequired. Object. Device query, e.g. { "byType": "iPhone 11 Pro" } for iOS simulator, { "avdName": "Pixel_2_API_29" } for Android emulator or { "adbName": "<pattern>" } for attached Android device with name matching the regex.
bootArgsOptional. String. Supported by ios.simulator and android.emulator only.
Supply an extra String of arguments to xcrun simctl boot ... or emulator -verbose ... @AVD_Name.
forceAdbInstallOptional. Boolean. Supported for Android devices only.
A Boolean value, false by default. When set to true, it tells device.installApp() to use adb install. Otherwise, it would use the combination of adb push <app.apk> and adb shell pm install.
utilBinaryPathsOptional. Array of strings. Supported for Android devices only.
An array of relative paths of utility app (APK) binary-files to preinstall on the tested devices - once before the test execution begins.
Note: these are not affected by various install-lifecycle events, such as launching an app with device.launchApp({delete: true}), which reinstalls the app. A good example of why this might come in handy is Test Butler.
gpuModeOptional. String Literal (auto | host | swiftshader_indirect | angle_indirect | guest). Supported by android.emulator only.
A fixed string , which tells in which GPU mode the emulator should be booted.
headlessOptional. Boolean. false by default. When set to true, it tells Detox to boot an Android emulator with -no-window option, or to not open the iOS Simulator app when running with Android or iOS respectively.
readonlyOptional. Boolean. Supported by android.emulator only.
false by default. When set to true, it forces Detox to boot even a single emulator with -read-only option.
Note: when used with multiple workers, this setting has no effect — emulators will be booted always with -read-only.