detox 20.1.0-next-is-hittable-check.0 → 20.1.0

package/index.d.ts

@@ -32,7 +32,7 @@ declare global {
     }
 
     namespace Detox {
-        // region DetoxConfig
+        //#region DetoxConfig
 
         interface DetoxConfig extends DetoxConfigurationCommon {
             /**
@@ -82,15 +82,19 @@ declare global {
                  */
                 exposeGlobals?: boolean;
                 /**
-                 * By default, Detox will uninstall and install the app upon the initialization.
+                 * By default, Detox will uninstall and install the app upon initialization.
                  * If you wish to reuse the existing app for a faster run, set the property to
                  * `false`.
                  */
                 reinstallApp?: boolean;
                 /**
-                 * If you wish to run multiple "detox test" commands in parallel,
-                 * make sure they don't delete the shared lock file – only the
-                 * first command should reset the lock file.
+                 * When false, `detox test` command always deletes the shared lock file on start,
+                 * assuming it had been left from the previous, already finished test session.
+                 * The lock file contains information about busy and free devices and ensures
+                 * no device can be used simultaneously by multiple test workers.
+                 *
+                 * Setting it to **true** might be useful when if you need to run multiple
+                 * `detox test` commands in parallel, e.g. test a few configurations at once.
                  *
                  * @default false
                  */
@@ -102,13 +106,43 @@ declare global {
             };
         }
 
+        type _DetoxLoggerOptions = Omit<BunyanDebugStreamOptions, 'out'>;
+
         interface DetoxLoggerConfig {
+            /**
+             * Log level filters the messages printed to your terminal,
+             * and it does not affect the logs written to the artifacts.
+             *
+             * Use `info` by default.
+             * Use `error` or warn when you want to make the output as silent as possible.
+             * Use `debug` to control what generally is happening under the hood.
+             * Use `trace` when troubleshooting specific issues.
+             *
+             * @default 'info'
+             */
             level?: DetoxLogLevel;
             /**
+             * When enabled, hijacks all the console methods (console.log, console.warn, etc)
+             * so that the messages printed via them are formatted and saved as Detox logs.
+             *
              * @default true
              */
             overrideConsole?: boolean;
-            options?: BunyanDebugStreamOptions | ((config: Partial<DetoxLoggerConfig>) => BunyanDebugStreamOptions);
+            /**
+             * Since Detox is using
+             * {@link https://www.npmjs.com/package/bunyan-debug-stream bunyan-debug-stream}
+             * for printing logs, all its options are exposed for sake of simplicity
+             * of customization.
+             *
+             * The only exception is {@link BunyanDebugStreamOptions#out} option,
+             * which is always set to `process.stdout`.
+             *
+             * You can also pass a callback function to override the logger config
+             * programmatically, e.g. depending on the selected log level.
+             *
+             * @see {@link BunyanDebugStreamOptions}
+             */
+            options?: _DetoxLoggerOptions | ((config: Partial<DetoxLoggerConfig>) => _DetoxLoggerOptions);
         }
 
         interface DetoxSessionConfig {
@@ -133,25 +167,78 @@ declare global {
                  */
                 [prop: string]: unknown;
             };
+
             /**
-             * Configuration of custom integration features
-             * between Detox and Jest
+             * This is an add-on section used by our Jest integration code (but not Detox core itself).
+             * In other words, if you’re implementing (or using) a custom integration with some other test runner, feel free to define a section for yourself (e.g. `testRunner.mocha`)
              */
             jest?: {
                 /**
                  * Environment setup timeout
+                 *
+                 * As a part of the environment setup, Detox boots the device and installs the apps.
+                 * If that takes longer than the specified value, the entire test suite will be considered as failed, e.g.:
+                 * ```plain text
+                 * FAIL  e2e/starter.test.js
+                 * ● Test suite failed to run
+                 *
+                 * Exceeded timeout of 300000ms while setting up Detox environment
+                 * ```
+                 *
+                 * The default value is 5 minutes.
+                 *
+                 * @default 300000
+                 * @see {@link https://jestjs.io/docs/configuration/#testenvironment-string}
                  */
                 setupTimeout?: number | undefined;
                 /**
-                 * Environment teardown timeout
+                 * Environemnt teardown timeout
+                 *
+                 * If the environment teardown takes longer than the specified value, Detox will throw a timeout error.
+                 * The default value is half a minute.
+                 *
+                 * @default 30000 (30 seconds)
+                 * @see {@link https://jestjs.io/docs/configuration/#testenvironment-string}
                  */
                 teardownTimeout?: number | undefined;
                 /**
-                 * Insist on CLI-based retry mechanism even when the failed tests have been handled
-                 * by jest.retryTimes(n) mechanism from Jest Circus.
+                 * Jest provides an API to re-run individual failed tests: `jest.retryTimes(count)`.
+                 * When Detox detects the use of this API, it suppresses its own CLI retry mechanism controlled via `detox test … --retries <N>` or {@link DetoxTestRunnerConfig#retries}.
+                 * The motivation is simple – activating the both mechanisms is apt to increase your test duration dramatically, if your tests are flaky.
+                 * If you wish nevertheless to use both the mechanisms simultaneously, set it to `true`.
+                 *
+                 * @default false
+                 * @see {@link https://jestjs.io/docs/29.0/jest-object#jestretrytimesnumretries-options}
                  */
                 retryAfterCircusRetries?: boolean;
+                /**
+                 * By default, Jest prints the test names and their status (_passed_ or _failed_) at the very end of the test session.
+                 * When enabled, it makes Detox to print messages like these each time the new test starts and ends:
+                 * ```plain text
+                 * 18:03:36.258 detox[40125] i Sanity: should have welcome screen
+                 * 18:03:37.495 detox[40125] i Sanity: should have welcome screen [OK]
+                 * 18:03:37.496 detox[40125] i Sanity: should show hello screen after tap
+                 * 18:03:38.928 detox[40125] i Sanity: should show hello screen after tap [OK]
+                 * 18:03:38.929 detox[40125] i Sanity: should show world screen after tap
+                 * 18:03:40.351 detox[40125] i Sanity: should show world screen after tap [OK]
+                 * ```
+                 * By default, it is enabled automatically in test sessions with a single worker.
+                 * And vice versa, if multiple tests are executed concurrently, Detox turns it off to avoid confusion in the log.
+                 * Use boolean values, `true` or `false`, to turn off the automatic choice.
+                 *
+                 * @default undefined
+                 */
                 reportSpecs?: boolean | undefined;
+                /**
+                 * In the environment setup phase, Detox boots the device and installs the apps.
+                 * This flag tells Detox to print messages like these every time the device gets assigned to a specific suite:
+                 *
+                 * ```plain text
+                 * 18:03:29.869 detox[40125] i starter.test.js is assigned to 4EC84833-C7EA-4CA3-A6E9-5C30A29EA596 (iPhone 12 Pro Max)
+                 * ```
+                 *
+                 * @default true
+                 */
                 reportWorkerAssign?: boolean | undefined;
             };
             /**
@@ -321,8 +408,6 @@ declare global {
             os: string;
         }
 
-        type DetoxKnownDeviceType = DetoxBuiltInDeviceConfig['type'];
-
         type DetoxConfiguration = DetoxConfigurationCommon & (
             | DetoxConfigurationSingleApp
             | DetoxConfigurationMultiApps
@@ -342,7 +427,7 @@ declare global {
 
         type DetoxAliasedApp = string | DetoxAppConfig;
 
-        // endregion DetoxConfig
+        //#endregion
 
         interface DetoxExportWrapper {
             readonly device: Device;
@@ -387,8 +472,6 @@ declare global {
                 readonly startSection: (name: string) => void;
                 /** @deprecated */
                 readonly endSection: (name: string) => void;
-                /** @private */
-                readonly invocationCall: (...args: unknown[]) => unknown;
             };
 
             /**
@@ -399,7 +482,7 @@ declare global {
              * @param promiseOrFunction Promise or a function that provides a promise.
              * @param args Optional arguments to pass to the trace.
              * @returns The returned value of the traced call.
-             * @see https://wix.github.io/Detox/docs/next/api/detox-object-api/#detoxtracecall.
+             * @see https://wix.github.io/Detox/docs/19.x/api/detox-object-api/#detoxtracecall
              */
             readonly traceCall: <T>(event: string, action: () => Promise<T>, args?: Record<string, unknown>) => Promise<T>;
         }
@@ -596,10 +679,11 @@ declare global {
              * Relaunch the app. Convenience method that calls {@link Device#launchApp}
              * with { newInstance: true } override.
              *
+             * @deprecated
              * @param config
              * @see Device#launchApp
              */
-            relaunchApp(config?: Omit<DeviceLaunchAppConfig, 'newInstance'>): Promise<void>;
+            relaunchApp(config?: DeviceLaunchAppConfig): Promise<void>;
 
             /**
              * Access the user-defined launch-arguments predefined through static scopes such as the Detox configuration file and

package/internals.d.ts

@@ -6,40 +6,48 @@ declare global {
     type DetoxStatus = 'inactive' | 'init' | 'active' | 'cleanup';
 
     type Facade = {
-      // region Initialization
+      //#region Initialization
       /**
        * Use with a caution, when you still have no config, yet need to avoid {@link Facade#init}
        */
       resolveConfig(options?: Partial<DetoxInitOptions>): Promise<RuntimeConfig>;
 
       /**
+       * Returns one of statuses depending on what’s going with the current Detox context:
        *
+       * `inactive` – before `init()` and after `cleanup()` is called.
+       * `init` – while `init()` is executing.
+       * `active` – after `init()` and before `cleanup()` is called.
+       * `cleanup` – while `cleanup()` is executing.
        */
       getStatus(): DetoxStatus;
 
       /**
-       * This is the phase where Detox reads its configuration, starts a server.
+       * Starts a new Detox test session with the provided configuration.
+       * See {@link https://wix.github.io/Detox/docs/api/internals} for more details.
        */
       init(options?: Partial<DetoxInitOptions>): Promise<void>;
 
       /**
-       * This is the phase where Detox loads its expectation library and starts a device.
+       * This is the phase where Detox loads its expectation library and boots a device.
+       * You don't need to call it separately unless you use `init({ workerId: null })` override.
        */
       installWorker(options?: Partial<DetoxInstallWorkerOptions>): Promise<void>;
 
       /**
        * Deallocates the device.
+       * Most Client API (device, by, element, expect) will stop working, except for the logger.
        */
       uninstallWorker(): Promise<void>;
 
       /**
-       * The global cleanup phase should happen after all the tests have finished.
-       * This is the phase where the Detox server shuts down.
+       * This method should be called when the main or child process is about to exit.
+       * See {@link https://wix.github.io/Detox/docs/api/internals} for more details.
        */
       cleanup(): Promise<void>;
-      // endregion
+      //#endregion
 
-      // region Lifecycle
+      //#region Lifecycle
       /**
        * Reports that the test runner started executing a test suite, e.g. a `beforeAll` hook or a first test.
        */
@@ -114,7 +122,7 @@ declare global {
        * @param testResults - reports about test files
        */
       reportTestResults(testResults: DetoxTestFileReport[]): Promise<void>;
-      // endregion
+      //#endregion
 
       readonly config: RuntimeConfig;
       readonly log: Detox.Logger;
@@ -131,6 +139,10 @@ declare global {
         createEventStream(): NodeJS.ReadableStream;
       };
 
+      /**
+       * Not documented on purpose.
+       * Provides direct access to the object which holds the device driver, websocket client, matchers, expectations, etc.
+       */
       readonly worker: Worker;
     }
 
@@ -230,7 +242,7 @@ declare global {
        * or equal to "default" if the name is not configured.
        */
       apps: Record<string, Readonly<Detox.DetoxAppConfig>>;
-      artifacts: Readonly<Detox.DetoxArtifactsConfig>;
+      artifacts: Readonly<RuntimeArtifactsConfig>;
       behavior: Readonly<Detox.DetoxBehaviorConfig>;
       cli: Readonly<CLIConfig>;
       device: Readonly<Detox.DetoxDeviceConfig>;
@@ -239,6 +251,19 @@ declare global {
       session: Readonly<Detox.DetoxSessionConfig>;
     }>;
 
+    type RuntimeArtifactsConfig = {
+      rootDir: string;
+      pathBuilder: string;
+      plugins: Readonly<{
+        log: Readonly<Detox.DetoxLogArtifactsPluginConfig>;
+        screenshot: Readonly<Detox.DetoxScreenshotArtifactsPluginConfig>;
+        video: Readonly<Detox.DetoxVideoArtifactsPluginConfig>;
+        instruments: Readonly<Detox.DetoxInstrumentsArtifactsPluginConfig>;
+        uiHierarchy: Readonly<Detox.DetoxUIHierarchyArtifactsPluginConfig>;
+        [pluginId: string]: unknown;
+      }>;
+    };
+
     type CLIConfig = Readonly<Partial<{
       appLaunchArgs: string;
       artifactsLocation: string;

package/local-cli/cli.js

@@ -28,9 +28,12 @@ yargs
   .wrap(yargs.terminalWidth() * 0.9)
   .fail(function(msg, err, program) {
     if (err) {
-      logger.error(DetoxError.format(err));
-      // eslint-disable-next-line no-console
-      console.error('');
+      const message = DetoxError.format(err);
+      if (message) {
+        logger.error(message);
+        process.stderr.write('\n');
+      }
+
       // @ts-ignore
       _.attempt(() => fs.unlinkSync(logger.file));
       // eslint-disable-next-line no-process-exit

package/local-cli/init.js

@@ -9,7 +9,7 @@ const jestTemplates = require('./templates/jest');
 let exitCode = 0;
 
 module.exports.command = 'init';
-module.exports.desc = 'Scaffold initial E2E test folder structure for Detox';
+module.exports.desc = 'Creates template files to get you started with Detox';
 module.exports.builder = {};
 
 module.exports.handler = async function init() {

package/local-cli/test.js

@@ -3,7 +3,7 @@ const detox = require('../internals');
 const TestRunnerCommand = require('./testCommand/TestRunnerCommand');
 
 module.exports.command = 'test';
-module.exports.desc = 'Run your test suite with the test runner specified in package.json';
+module.exports.desc = 'Run your test suites with the test runner specified in the project\'s Detox config';
 module.exports.builder = require('./testCommand/builder');
 module.exports.middlewares = require('./testCommand/middlewares').default;
 
@@ -16,14 +16,14 @@ module.exports.handler = async function test({ detoxArgs, runnerArgs }) {
     };
 
     const config = await detox.resolveConfig(opts);
-    if (!detoxArgs['inspect-brk']) {
+    if (!config.cli.inspectBrk) {
       await detox.init(opts);
     }
 
-    const runnerCommand = new TestRunnerCommand()
-      .setDeviceConfig(config.device)
-      .replicateCLIConfig(config.cli)
-      .setRunnerConfig(config.testRunner);
+    const runnerCommand = new TestRunnerCommand({
+      config,
+      env: process.env,
+    });
 
     await runnerCommand.execute();
   } finally {

package/local-cli/testCommand/TestRunnerCommand.js

@@ -6,103 +6,40 @@ const unparse = require('yargs-unparser');
 
 const detox = require('../../internals');
 const log = detox.log.child({ cat: ['lifecycle', 'cli'] });
-const { DetoxRuntimeError } = require('../../src/errors');
 const { printEnvironmentVariables, prependNodeModulesBinToPATH } = require('../../src/utils/envUtils');
-const { escapeSpaces } = require('../../src/utils/shellUtils');
+const { toSimplePath } = require('../../src/utils/pathUtils');
+const { escapeSpaces, useForwardSlashes } = require('../../src/utils/shellUtils');
+
+const TestRunnerError = require('./TestRunnerError');
 
 class TestRunnerCommand {
-  constructor() {
-    this._argv = {};
-    this._cli2env = {};
-    this._envHint = {};
+  /*
+    @param {object} opts
+    @param {DetoxInternals.RuntimeConfig} opts.config
+    @param {ProcessEnv} opts.env
+  */
+  constructor(opts) {
+    const cliConfig = opts.config.cli;
+    const deviceConfig = opts.config.device;
+    const runnerConfig = opts.config.testRunner;
+
+    this._argv = runnerConfig.args;
+    this._retries = runnerConfig.retries;
+    this._envHint = this._buildEnvHint(opts.env);
     this._envFwd = {};
-    this._retries = 0;
-    /** @type {Detox.DetoxDeviceConfig} */
-    this._deviceConfig = null;
-  }
-
-  /**
-   * @param {Partial<Readonly<DetoxInternals.CLIConfig>>} cliConfig
-   * @returns {this}
-   */
-  replicateCLIConfig(cliConfig) {
-    this._cli2env = _.omitBy({
-      DETOX_APP_LAUNCH_ARGS: cliConfig.appLaunchArgs,
-      DETOX_ARTIFACTS_LOCATION: cliConfig.artifactsLocation,
-      DETOX_CAPTURE_VIEW_HIERARCHY: cliConfig.captureViewHierarchy,
-      DETOX_CLEANUP: cliConfig.cleanup,
-      DETOX_CONFIGURATION: cliConfig.configuration,
-      DETOX_CONFIG_PATH: cliConfig.configPath,
-      DETOX_DEBUG_SYNCHRONIZATION: cliConfig.debugSynchronization,
-      DETOX_DEVICE_BOOT_ARGS: cliConfig.deviceBootArgs,
-      DETOX_DEVICE_NAME: cliConfig.deviceName,
-      DETOX_FORCE_ADB_INSTALL: this._deviceConfig.type.startsWith('android.')
-        ? cliConfig.forceAdbInstall
-        : undefined,
-      DETOX_GPU: cliConfig.gpu,
-      DETOX_HEADLESS: cliConfig.headless,
-      DETOX_KEEP_LOCKFILE: cliConfig.keepLockFile,
-      DETOX_LOGLEVEL: cliConfig.loglevel,
-      DETOX_READ_ONLY_EMU: cliConfig.readonlyEmu,
-      DETOX_RECORD_LOGS: cliConfig.recordLogs,
-      DETOX_RECORD_PERFORMANCE: cliConfig.recordPerformance,
-      DETOX_RECORD_VIDEOS: cliConfig.recordVideos,
-      DETOX_REPORT_SPECS: cliConfig.jestReportSpecs,
-      DETOX_RETRIES: cliConfig.retries,
-      DETOX_REUSE: cliConfig.reuse,
-      DETOX_TAKE_SCREENSHOTS: cliConfig.takeScreenshots,
-      DETOX_USE_CUSTOM_LOGGER: cliConfig.useCustomLogger,
-    }, _.isUndefined);
-
-    this._envHint = _(process.env)
-      .mapKeys((_value, key) => key.toUpperCase())
-      .pickBy((_value, key) => key.startsWith('DETOX_'))
-      .omit(['DETOX_CONFIG_SNAPSHOT_PATH'])
-      .value();
-
-    return this;
-  }
-
-  /**
-   * @param {Detox.DetoxDeviceConfig} config
-   * @returns {this}
-   */
-  setDeviceConfig(config) {
-    this._deviceConfig = config;
-
-    return this;
-  }
-
-  /**
-   * @param {Detox.DetoxTestRunnerConfig} config
-   * @returns {this}
-   */
-  setRunnerConfig(config) {
-    this._argv = config.args;
-    this._retries = config.inspectBrk ? 0 : config.retries;
-    if (config.forwardEnv) {
-      this._envFwd = this._cli2env;
-      Object.assign(this._envHint, this._cli2env);
+    if (runnerConfig.forwardEnv) {
+      this._envFwd = this._buildEnvOverride(cliConfig, deviceConfig);
+      Object.assign(this._envHint, this._envFwd);
     }
-
-    return this;
   }
 
   async execute() {
     let runsLeft = 1 + this._retries;
-    let launchError;
+    let launchError = null;
 
     do {
       try {
-        if (launchError) {
-          const list = this._argv._.map((file, index) => `  ${index + 1}. ${file}`).join('\n');
-          log.error(
-            `There were failing tests in the following files:\n${list}\n\n` +
-            'Detox CLI is going to restart the test runner with those files...\n'
-          );
-        }
-
-        await this._doExecute();
+        await this._spawnTestRunner();
         launchError = null;
       } catch (e) {
         launchError = e;
@@ -120,9 +57,11 @@ class TestRunnerCommand {
         }
 
         if (--runsLeft > 0) {
-          this._argv._ = testFilesToRetry;
           // @ts-ignore
-          detox.session.testSessionIndex++; // it is always a primary context, so we can update it
+          detox.session.testSessionIndex++; // it is always the primary context, so we can update it
+
+          this._argv._ = testFilesToRetry.map(useForwardSlashes);
+          this._logRelaunchError(testFilesToRetry);
         }
       }
     } while (launchError && runsLeft > 0);
@@ -132,11 +71,53 @@ class TestRunnerCommand {
     }
   }
 
-  async _doExecute() {
+  _buildEnvHint(env) {
+    return _(env)
+      .mapKeys((_value, key) => key.toUpperCase())
+      .pickBy((_value, key) => key.startsWith('DETOX_'))
+      .omit(['DETOX_CONFIG_SNAPSHOT_PATH'])
+      .value();
+  }
+
+  /**
+   * @param {DetoxInternals.CLIConfig} cliConfig
+   * @param {Detox.DetoxDeviceConfig} deviceConfig
+   */
+  _buildEnvOverride(cliConfig, deviceConfig) {
+    return _.omitBy({
+      DETOX_APP_LAUNCH_ARGS: cliConfig.appLaunchArgs,
+      DETOX_ARTIFACTS_LOCATION: cliConfig.artifactsLocation,
+      DETOX_CAPTURE_VIEW_HIERARCHY: cliConfig.captureViewHierarchy,
+      DETOX_CLEANUP: cliConfig.cleanup,
+      DETOX_CONFIGURATION: cliConfig.configuration,
+      DETOX_CONFIG_PATH: cliConfig.configPath,
+      DETOX_DEBUG_SYNCHRONIZATION: cliConfig.debugSynchronization,
+      DETOX_DEVICE_BOOT_ARGS: cliConfig.deviceBootArgs,
+      DETOX_DEVICE_NAME: cliConfig.deviceName,
+      DETOX_FORCE_ADB_INSTALL: deviceConfig.type.startsWith('android.')
+        ? cliConfig.forceAdbInstall
+        : undefined,
+      DETOX_GPU: cliConfig.gpu,
+      DETOX_HEADLESS: cliConfig.headless,
+      DETOX_KEEP_LOCKFILE: cliConfig.keepLockFile,
+      DETOX_LOGLEVEL: cliConfig.loglevel,
+      DETOX_READ_ONLY_EMU: cliConfig.readonlyEmu,
+      DETOX_RECORD_LOGS: cliConfig.recordLogs,
+      DETOX_RECORD_PERFORMANCE: cliConfig.recordPerformance,
+      DETOX_RECORD_VIDEOS: cliConfig.recordVideos,
+      DETOX_REPORT_SPECS: cliConfig.jestReportSpecs,
+      DETOX_RETRIES: cliConfig.retries,
+      DETOX_REUSE: cliConfig.reuse,
+      DETOX_TAKE_SCREENSHOTS: cliConfig.takeScreenshots,
+      DETOX_USE_CUSTOM_LOGGER: cliConfig.useCustomLogger,
+    }, _.isUndefined);
+  }
+
+  async _spawnTestRunner() {
     const fullCommand = this._buildSpawnArguments().map(escapeSpaces);
     const fullCommandWithHint = printEnvironmentVariables(this._envHint) + fullCommand.join(' ');
 
-    log.info({ env: this._envHint }, fullCommandWithHint);
+    log.info.begin({ env: this._envHint }, fullCommandWithHint);
 
     return new Promise((resolve, reject) => {
       cp.spawn(fullCommand[0], fullCommand.slice(1), {
@@ -149,15 +130,26 @@ class TestRunnerCommand {
           .tap(prependNodeModulesBinToPATH)
           .value()
       })
-        .on('error', (err) => reject(err))
-        .on('exit', (code) => code === 0
-          ? resolve()
-          : reject(new DetoxRuntimeError(`Command failed with exit code = ${code}:\n${fullCommandWithHint}`)
-        ));
+        .on('error', /* istanbul ignore next */ (err) => reject(err))
+        .on('exit', (code, signal) => {
+          if (code === 0) {
+            log.trace.end({ success: true });
+            resolve();
+          } else {
+            const error = new TestRunnerError({
+              command: fullCommandWithHint,
+              code,
+              signal,
+            });
+            log.error.end({ success: false, code, signal }, error.message);
+            reject(error);
+          }
+        });
     });
   }
 
   _buildSpawnArguments() {
+    /* istanbul ignore next */
     const { _: specs = [], '--': passthrough = [], $0, ...argv } = this._argv;
     const { _: $0_, ...$0argv } = parser($0);
 
@@ -168,6 +160,17 @@ class TestRunnerCommand {
       ...unparse({ _: [...passthrough, ...specs] }),
     ].map(String);
   }
+
+  _logRelaunchError(filePaths) {
+    const list = filePaths.map((file, index) => {
+      return `  ${index + 1}. ${toSimplePath(file)}`;
+    }).join('\n');
+
+    log.error(
+      `There were failing tests in the following files:\n${list}\n\n` +
+      'Detox CLI is going to restart the test runner with those files...\n'
+    );
+  }
 }
 
 module.exports = TestRunnerCommand;

package/local-cli/testCommand/TestRunnerError.js

@@ -0,0 +1,17 @@
+const { DetoxError } = require('../../src/errors');
+
+class TestRunnerError extends DetoxError {
+  constructor({ command, code, signal }) {
+    super(`Command failed with exit code = ${code}:\n${command}`);
+
+    this.code = code;
+    this.signal = signal;
+    this.name = 'TestRunnerError';
+  }
+
+  format() {
+    return '';
+  }
+}
+
+module.exports = TestRunnerError;

package/local-cli/testCommand/builder.js

@@ -109,7 +109,6 @@ module.exports = {
     describe: 'Override the device name specified in a configuration. Useful for running a single build configuration on multiple devices.',
   },
   'device-boot-args': {
-    alias: 'device-launch-args',
     group: 'Execution:',
     describe: 'Custom arguments to pass (through) onto the device (emulator/simulator) binary when booted.',
   },