Detox Command Line Tools
Detox Command Line Tools (detox-cli)
detox-cli lets you operate Detox from command line.
Installation
Install detox-cli globally via npm:
- npm
- Yarn
- pnpm
npm install detox-cli --global
yarn global add detox-cli
pnpm add detox-cli --global
Usage
detox <command> [options]
Commands
| Command | Description |
|---|---|
| init | Create initial E2E tests folder for jest or mocha |
| build | Convenience method. Run the command defined in 'build' property of the specified configuration. |
| test | Initiating your test suite |
| run-server | Starts a standalone detox server |
| build-framework-cache | MacOS only. Builds Detox.framework to ~/Library/Detox. The framework cache is specific for each combination of Xcode and Detox versions |
| clean-framework-cache | MacOS only. Deletes all compiled framework binaries from ~/Library/Detox, they will be rebuilt on 'npm install' or when running 'build-framework-cache' |
| rebuild-framework-cache | MacOS only. Rebuilds the Detox cache |
| recorder | Starts a Detox Recorder recording |
Options
| Options | Description |
|---|---|
| --version | Show version number |
| --help | Show help |
init
Scaffolds initial E2E test folder structure for a specific test runner
detox init -r <test-runner-name>
| Option | Description |
|---|---|
-r, --runner <test-runner-name> | test runner name (supported values: mocha, jest) |
| --help | Show help |
build
Run the command defined in build property of the specified configuration.
detox build [options]
| Option | Description |
|---|---|
-c, --configuration <device config> | Select a device configuration from your defined configurations, if not supplied, and there’s only one configuration, detox will default to it |
-C, --config-path <configPath> | Specify Detox config file path. If not supplied, detox searches for .detoxrc[.js] or "detox" section in package.json |
| -i, --if-missing | Execute the build command only if the app binary is missing. |
| -s, --silent | Do not fail with error if an app config has no build command. |
| --help | Show help |
test
Initiating your test suite1.
detox test [options] <...testFilePaths>
| Option | Description |
|---|---|
-C, --config-path <configPath> | Specify Detox config file path. If not supplied, detox searches for .detoxrc[.js] or "detox" section in package.json |
-c, --configuration <device config> | Select a device configuration from your defined configurations, if not supplied, and there’s only one configuration, detox will default to it |
-o, --runner-config <config> | Test runner config file, defaults to 'e2e/mocha.opts' for mocha and 'e2e/config.json' for jest. |
| -n, --device-name [name] | Override the device name specified in a configuration. Useful for running a single build configuration on multiple devices. |
| -l, --loglevel [value] | Log level: fatal, error, warn, info, verbose, trace |
-d, --debug-synchronization <value> | Customize how long an action/expectation can take to complete before Detox starts querying the app why it is busy. By default, the app status will be printed if the action takes more than 10s to complete. |
-a, --artifacts-location <path> | Artifacts (logs, screenshots, etc) root directory.2 |
| --record-logs [failing/all/none] | Save logs during each test to artifacts directory. Pass "failing" to save logs of failing tests only. The default value is none. |
| --take-screenshots [manual/failing/all/none] | Save screenshots before and after each test to artifacts directory. Pass "failing" to save screenshots of failing tests only. The default value is manual. |
| --record-videos [failing/all/none] | Save screen recordings of each test to artifacts directory. Pass "failing" to save recordings of failing tests only. The default value is none. |
| --record-performance [all/none] | [iOS Only] Save Detox Instruments performance recordings of each test to artifacts directory. The default value is none. |
| --record-timeline [all/none] | [Jest Only] Record tests and events timeline, for visual display on the chrome://tracing tool. The default value is none. |
| --capture-view-hierarchy [enabled/disabled] | [iOS Only] Capture *.uihierarchy snapshots on view action errors and device.captureViewHierarchy() calls. The default value is disabled. |
| -R, --retries | [Jest Circus Only] Re-spawn the test runner for individual failing suite files until they pass, or <N> times at most. |
| -r, --reuse | Reuse existing installed app (do not delete + reinstall) for a faster run. |
| -u, --cleanup | Shutdown simulator when test is over, useful for CI scripts, to make sure detox exists cleanly with no residue |
| -w, --workers | Specifies number of workers the test runner should spawn, requires a test runner with parallel execution support (Detox CLI currently supports Jest). Note: For workers > 1, Jest’s spec-level reporting is disabled, by default (can be overridden using --jest-report-specs). |
| --jest-report-specs | [Jest Only] Whether to output logs per each running spec, in real-time. By default, disabled with multiple workers. |
| -H, --headless | [Android Only] Launch emulator in headless mode. Useful when running on CI. Only applicable for Google emulators. |
| --gpu | [Android Only] Launch emulator with the specific -gpu gpu mode parameter. Only applicable for Google emulators. |
| --device-launch-args | A list of passthrough-arguments to use when (if) devices (Android emulator / iOS simulator) are launched by Detox. Note: the value must be specified after an equal sign ( =) and inside quotes. Usage example:--device-launch-args="-http-proxy http://1.1.1.1:8000 -no-snapshot-load" |
| --app-launch-args | Custom arguments to pass (through) onto the app every time it is launched. The same note applies here, as for --device-launch-args. See launch arguments guide for complete info. |
| --no-color | Disable colors in log output |
| --use-custom-logger | Use Detox' custom console-logging implementation, for logging Detox (non-device) logs. Disabling will fallback to node.js / test-runner’s implementation (e.g. Jest / Mocha). Default: true |
| --force-adb-install | Due to problems with the adb install command on Android, Detox resorts to a different scheme for installing APKs. Setting true will disable that and force usage of adb install, instead.This flag is temporary until the Detox way proves stable. Default: false |
| --inspect-brk | Uses node’s --inspect-brk flag to let users debug the jest/mocha test runner Default: false |
| --help | Show help |
DETOX_ARGV_OVERRIDE
If you happen to be troubleshooting Detox tests inside a complex script, or a failing CI build
(e.g., on TeamCity or Jenkins), there is an escape-hatch feature for running Detox with
some extra CLI args just by setting the DETOX_ARGV_OVERRIDE environment variable before
rerunning it again.
> export DETOX_ARGV_OVERRIDE="--forceExit -w 1 --testNamePattern='that hanging test' e2e/sanity/login.test.js"
> bash scripts/ci.e2e.sh
# ... some output ...
> detox test -c ios.sim.release -l verbose --workers 3
# ...
configuration=ios.sim.release ... jest --maxWorkers 1 --forceExit --testNamePattern='that hanging test' e2e/sanity/login.test.js
Consider the example above, where DETOX_ARGV_OVERRIDE forces Detox to run Jest in a single worker
mode with a forceful exit (after 1 second) only for a selected test in a specific file.
As you might see, the idea of DETOX_ARGV_OVERRIDE is quite similar to NODE_OPTIONS
except for the fact you use it not for regular flows, but for forced ad-hoc patching of a failing Detox configuration to
save your time.
Please avoid using it in your regular flows – instead, use Detox configuration files (.detoxrc.js)
as your primary choice.
run-server
Start a standalone Detox server
detox run-server [options]
| Option | Description |
|---|---|
| -p, --port [port] | Port number (default: 8099) |
| -l, --loglevel [value] | Log level: fatal, error, warn, info, verbose, trace |
| --no-color | Disable colorful logs |
| --help | Show help |
recorder
If you have installed Detox Recorder in your project, you can use this command to start a new recording.
Cache
Detox stores a cached version of its framework in ~/Library/Detox. A different cache folder is used for different Xcode and Detox versions. Use the various cache commands to clean or build this cache.
- It should be noted that
detox testis a convenience method to trigger an execution of a supported test runner, so for the most part it reads configuration from CLI args andpackage.jsonand remaps it to command-line arguments or environment variables that are supported by (or not conflict with) the test runner. Hence, extra arguments todetox testwill be forwarded to your test runner, e.g:\ 1. You rundetox test --bail, and since--bailis an unknown option, it will be forwarded to the test runner as-is.\ 2. If there is a name conflict for some option (between the test runner anddetox test), you can pass it explicitly\ after the reserved--sequence. For instance,detox test -- --help, will pass--helpto the test runner CLI itself.↩ - If
--artifacts-locationpath does not end with a slash (/) or a backslash, then detox CLI will append to the path a subdirectory with configuration name and timestamp (e.g.artifacts/android.emu.release.2018-06-12 05:52:43Z). In other words, the path with a slash at the end assumes you do not want a subdirectory inside. For more details, please check the Enabling artifacts. The default value is artifacts (plus a subdirectory).↩