detox 20.0.0-breaking.new-global-lifecycle.0 → 20.0.0

package/local-cli/test.js

@@ -3,24 +3,30 @@ 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;
 
 module.exports.handler = async function test({ detoxArgs, runnerArgs }) {
   try {
-    await detox.globalSetup({
+    const opts = {
       argv: detoxArgs,
       testRunnerArgv: runnerArgs,
-    });
+      workerId: null,
+    };
+
+    const config = await detox.resolveConfig(opts);
+    if (!config.cli.inspectBrk) {
+      await detox.init(opts);
+    }
 
-    const runnerCommand = new TestRunnerCommand()
-      .setRunnerConfig(detox.config.runnerConfig)
-      .setDeviceConfig(detox.config.deviceConfig)
-      .replicateCLIConfig(detox.config.cliConfig);
+    const runnerCommand = new TestRunnerCommand({
+      config,
+      env: process.env,
+    });
 
     await runnerCommand.execute();
   } finally {
-    await detox.globalTeardown();
+    await detox.cleanup();
   }
 };

package/local-cli/test.test.js

@@ -8,8 +8,11 @@ jest.mock('../src/devices/DeviceRegistry');
 jest.mock('../src/devices/allocation/drivers/android/genycloud/GenyDeviceRegistryFactory');
 jest.mock('./utils/jestInternals');
 
+const cp = require('child_process');
+const cpSpawn = cp.spawn;
 const os = require('os');
 const path = require('path');
+const util = require('util');
 
 const fs = require('fs-extra');
 const _ = require('lodash');
@@ -28,6 +31,10 @@ describe('CLI', () => {
   let GenyDeviceRegistryFactory;
   let jestInternals;
 
+  afterEach(() => {
+    cp.spawn = cpSpawn;
+  });
+
   beforeEach(() => {
     _cliCallDump = undefined;
     _env = process.env;
@@ -46,6 +53,7 @@ describe('CLI', () => {
           $0: os.platform() === 'win32' ? `node ${executable}` : executable,
           config: 'e2e/config.json'
         },
+        forwardEnv: true,
       },
       configurations: {
         single: {
@@ -100,23 +108,53 @@ describe('CLI', () => {
   ])('given no extra args (%s)', (_platform, deviceType) => {
     beforeEach(async () => {
       singleConfig().device.type = deviceType;
-      await run();
     });
 
-    test('should produce a default command', () => {
-      expect(cliCall().argv).toEqual([expect.stringContaining('executable'), '--config', 'e2e/config.json']);
-    });
+    describe('when testRunner.forwardEnv is true', () => {
+      beforeEach(async () => {
+        singleConfig().testRunner = { forwardEnv: true };
+        await run();
+      });
 
-    test('should not override environment variables', () => {
-      expect(cliCall().env).toEqual({ DETOX_CONFIG_SNAPSHOT_PATH: expect.any(String) });
+      test('should produce a default command', () => {
+        expect(cliCall().argv).toEqual([expect.stringContaining('executable'), '--config', 'e2e/config.json']);
+      });
+
+      test('should override environment variables', () => {
+        expect(cliCall().env).toEqual({
+          DETOX_CONFIG_PATH: expect.any(String),
+          DETOX_CONFIG_SNAPSHOT_PATH: expect.any(String)
+        });
+      });
+
+      test('should hint essential environment variables', () => {
+        expect(cliCall().fullCommand).toMatch(/\bDETOX_CONFIG_PATH=.*\bexecutable\b/);
+      });
     });
 
-    test('should hint essential environment variables', () => {
-      expect(cliCall().fullCommand).toMatch(/^DETOX_CONFIG_PATH=.*\bexecutable/);
+    describe('when testRunner.forwardEnv is false', () => {
+      beforeEach(async () => {
+        singleConfig().testRunner = { forwardEnv: false };
+        await run();
+      });
+
+      test('should produce a default command', () => {
+        expect(cliCall().argv).toEqual([expect.stringContaining('executable'), '--config', 'e2e/config.json']);
+      });
+
+      test('should not override environment variables', () => {
+        expect(cliCall().env).toEqual({
+          DETOX_CONFIG_SNAPSHOT_PATH: expect.any(String)
+        });
+      });
+
+      test('should not hint essential environment variables', () => {
+        expect(cliCall().fullCommand).not.toMatch(/\bDETOX_CONFIG_PATH=.*\bexecutable\b/);
+      });
     });
   });
 
-  test('should use runnerConfig.specs as default specs', async () => {
+  test('should use testRunner.args._ as default specs', async () => {
     detoxConfig.testRunner.args._ = ['e2e/sanity'];
     await run();
     expect(_.last(cliCall().argv)).toEqual('e2e/sanity');
@@ -129,7 +167,7 @@ describe('CLI', () => {
 
   test.each([['-l'], ['--loglevel']])('%s <value> should be passed as environment variable', async (__loglevel) => {
     await run(__loglevel, 'trace');
-    expect(cliCall().env).not.toHaveProperty('DETOX_LOGLEVEL');
+    expect(cliCall().env).toHaveProperty('DETOX_LOGLEVEL');
     expect(cliCall().fullCommand).toMatch(/ DETOX_LOGLEVEL="trace" /);
   });
 
@@ -139,27 +177,67 @@ describe('CLI', () => {
   });
 
   test.each([['-R'], ['--retries']])('%s <value> should execute unsuccessful run N extra times', async (__retries) => {
+    function toTestResult(testFilePath) {
+      return {
+        testFilePath,
+        success: false,
+        isPermanentFailure: false,
+      };
+    }
+
     const context = require('../internals');
-    context.session.failedTestFiles = ['e2e/failing1.test.js', 'e2e/failing2.test.js'];
-    context.session.failedTestFiles.splice = jest.fn(() => {
-      context.session.failedTestFiles = ['e2e/failing2.test.js'];
-    });
+
+    jest.spyOn(cp, 'spawn')
+      .mockImplementationOnce((...args) => {
+        context.session.testResults = ['e2e/failing1.test.js', 'e2e/failing2.test.js'].map(toTestResult);
+        return cpSpawn(...args);
+      })
+      .mockImplementationOnce((...args) => {
+        context.session.testResults = ['e2e/failing2.test.js'].map(toTestResult);
+        return cpSpawn(...args);
+      })
+      .mockImplementationOnce((...args) => {
+        return cpSpawn(...args);
+      });
 
     mockExitCode(1);
 
     await run(__retries, 2).catch(_.noop);
 
-    expect(cliCall(0).env).not.toHaveProperty('DETOX_RERUN_INDEX');
     expect(cliCall(0).argv).toEqual([expect.stringMatching(/executable$/), '--config', 'e2e/config.json']);
-    expect(cliCall(0).fullCommand).not.toMatch(/DETOX_RERUN_INDEX/);
-
-    expect(cliCall(1).env.DETOX_RERUN_INDEX).toBe('1');
     expect(cliCall(1).argv).toEqual([expect.stringMatching(/executable$/), '--config', 'e2e/config.json', 'e2e/failing1.test.js', 'e2e/failing2.test.js']);
-    expect(cliCall(1).fullCommand).not.toMatch(/DETOX_RERUN_INDEX/);
-
     expect(cliCall(2).argv).toEqual([expect.stringMatching(/executable$/), '--config', 'e2e/config.json', 'e2e/failing2.test.js']);
-    expect(cliCall(2).env.DETOX_RERUN_INDEX).toBe('2');
-    expect(cliCall(2).fullCommand).not.toMatch(/DETOX_RERUN_INDEX/);
+  });
+
+  describe('when there are permanently failed tests', () => {
+    beforeEach(() => {
+      const context = require('../internals');
+      context.session.testResults = ['e2e/failing1.test.js', 'e2e/failing2.test.js'].map((testFilePath, index) => ({
+        testFilePath,
+        success: false,
+        isPermanentFailure: index > 0,
+      }));
+
+      mockExitCode(1);
+    });
+
+    test.each([['-R'], ['--retries']])('%s <value> should not bail by default', async (__retries) => {
+      await run(__retries, 2).catch(_.noop);
+
+      expect(cliCall(0).argv).toEqual([expect.stringMatching(/executable$/), '--config', 'e2e/config.json']);
+      expect(cliCall(1).env).not.toHaveProperty('DETOX_RERUN_INDEX');
+      expect(cliCall(1).argv).toEqual([expect.stringMatching(/executable$/), '--config', 'e2e/config.json', 'e2e/failing1.test.js']);
+      // note that it does not take the permanently failed test
+    });
+
+    test.each([['-R'], ['--retries']])('%s <value> should bail if configured', async (__retries) => {
+      detoxConfig.testRunner.bail = true;
+      await run(__retries, 2).catch(_.noop);
+
+      expect(cliCall(0).env).not.toHaveProperty('DETOX_RERUN_INDEX');
+      expect(cliCall(0).argv).toEqual([expect.stringMatching(/executable$/), '--config', 'e2e/config.json']);
+      expect(cliCall(1)).toBe(null);
+    });
   });
 
   test.each([['-R'], ['--retries']])('%s <value> should not restart test runner if there are no failing tests paths', async (__retries) => {
@@ -172,7 +250,11 @@ describe('CLI', () => {
 
   test.each([['-R'], ['--retries']])('%s <value> should retain -- <...explicitPassthroughArgs>', async (__retries) => {
     const context = require('../internals');
-    context.session.failedTestFiles = ['tests/failing.test.js'];
+    context.session.testResults = [{
+      testFilePath: 'tests/failing.test.js',
+      success: false,
+      isPermanentFailure: false,
+    }];
 
     mockExitCode(1);
 
@@ -184,111 +266,104 @@ describe('CLI', () => {
 
   test.each([['-r'], ['--reuse']])('%s <value> should be passed as environment variable', async (__reuse) => {
     await run(__reuse);
-    expect(cliCall().env).not.toHaveProperty('DETOX_REUSE');
+    expect(cliCall().env).toHaveProperty('DETOX_REUSE');
     expect(cliCall().fullCommand).toMatch(/\bDETOX_REUSE=true /);
   });
 
   test.each([['-u'], ['--cleanup']])('%s <value> should be passed as environment variable', async (__cleanup) => {
     await run(__cleanup);
-    expect(cliCall().env).not.toHaveProperty('DETOX_CLEANUP');
+    expect(cliCall().env).toHaveProperty('DETOX_CLEANUP');
     expect(cliCall().fullCommand).toMatch(/\bDETOX_CLEANUP=true /);
   });
 
   test.each([['-d'], ['--debug-synchronization']])('%s <value> should be passed as environment variable', async (__debug_synchronization) => {
     await run(__debug_synchronization, 5000);
-    expect(cliCall().env).not.toHaveProperty('DETOX_DEBUG_SYNCHRONIZATION');
+    expect(cliCall().env).toHaveProperty('DETOX_DEBUG_SYNCHRONIZATION');
     expect(cliCall().fullCommand).toMatch(/\bDETOX_DEBUG_SYNCHRONIZATION=5000 /);
   });
 
   test.each([['-d'], ['--debug-synchronization']])('%s <value> should be passed as 0 when given false', async (__debug_synchronization) => {
     await run(__debug_synchronization, false);
-    expect(cliCall().env).not.toHaveProperty('DETOX_DEBUG_SYNCHRONIZATION');
+    expect(cliCall().env).toHaveProperty('DETOX_DEBUG_SYNCHRONIZATION');
     expect(cliCall().fullCommand).toMatch(/\bDETOX_DEBUG_SYNCHRONIZATION=0 /);
   });
 
   test.each([['-d'], ['--debug-synchronization']])('%s <value> should have default value = 3000', async (__debug_synchronization) => {
     await run(`${__debug_synchronization}`);
-    expect(cliCall().env).not.toHaveProperty('DETOX_DEBUG_SYNCHRONIZATION');
+    expect(cliCall().env).toHaveProperty('DETOX_DEBUG_SYNCHRONIZATION');
     expect(cliCall().fullCommand).toMatch(/\bDETOX_DEBUG_SYNCHRONIZATION=3000 /);
   });
 
   test.each([['-a'], ['--artifacts-location']])('%s <value> should be passed as environment variable', async (__artifacts_location) => {
     await run(__artifacts_location, '/tmp');
-    expect(cliCall().env).not.toHaveProperty('DETOX_ARTIFACTS_LOCATION');
+    expect(cliCall().env).toHaveProperty('DETOX_ARTIFACTS_LOCATION');
     expect(cliCall().fullCommand).toMatch(/\bDETOX_ARTIFACTS_LOCATION="\/tmp" /);
   });
 
   test('--record-logs <value> should be passed as environment variable', async () => {
     await run('--record-logs', 'all');
-    expect(cliCall().env).not.toHaveProperty('DETOX_RECORD_LOGS');
+    expect(cliCall().env).toHaveProperty('DETOX_RECORD_LOGS');
     expect(cliCall().fullCommand).toMatch(/\bDETOX_RECORD_LOGS="all" /);
   });
 
   test('--take-screenshots <value> should be passed as environment variable', async () => {
     await run('--take-screenshots', 'failing');
-    expect(cliCall().env).not.toHaveProperty('DETOX_TAKE_SCREENSHOTS');
+    expect(cliCall().env).toHaveProperty('DETOX_TAKE_SCREENSHOTS');
     expect(cliCall().fullCommand).toMatch(/\bDETOX_TAKE_SCREENSHOTS="failing" /);
   });
 
   test('--record-videos <value> should be passed as environment variable', async () => {
     await run('--record-videos', 'failing');
-    expect(cliCall().env).not.toHaveProperty('DETOX_RECORD_VIDEOS');
+    expect(cliCall().env).toHaveProperty('DETOX_RECORD_VIDEOS');
     expect(cliCall().fullCommand).toMatch(/\bDETOX_RECORD_VIDEOS="failing" /);
   });
 
   test('--record-performance <value> should be passed as environment variable', async () => {
     await run('--record-performance', 'all');
-    expect(cliCall().env).not.toHaveProperty('DETOX_RECORD_PERFORMANCE');
+    expect(cliCall().env).toHaveProperty('DETOX_RECORD_PERFORMANCE');
     expect(cliCall().fullCommand).toMatch(/\DETOX_RECORD_PERFORMANCE="all" /);
   });
 
   test('--capture-view-hierarchy <value> should be passed as environment variable', async () => {
     await run('--capture-view-hierarchy', 'enabled');
-    expect(cliCall().env).not.toHaveProperty('DETOX_CAPTURE_VIEW_HIERARCHY');
+    expect(cliCall().env).toHaveProperty('DETOX_CAPTURE_VIEW_HIERARCHY');
     expect(cliCall().fullCommand).toMatch(/\DETOX_CAPTURE_VIEW_HIERARCHY="enabled" /);
   });
 
   test('--jest-report-specs, set explicitly, should be passed as an environment variable', async () => {
     await run('--jest-report-specs');
-    expect(cliCall().env).not.toHaveProperty('DETOX_REPORT_SPECS');
+    expect(cliCall().env).toHaveProperty('DETOX_REPORT_SPECS');
     expect(cliCall().fullCommand).toMatch(/\bDETOX_REPORT_SPECS=true /);
   });
 
   test.each([['-H'], ['--headless']])('%s <value> should be passed as environment variable', async (__headless) => {
     await run(__headless);
-    expect(cliCall().env).not.toHaveProperty('DETOX_HEADLESS');
+    expect(cliCall().env).toHaveProperty('DETOX_HEADLESS');
     expect(cliCall().fullCommand).toMatch(/\bDETOX_HEADLESS=true /);
   });
 
   test('--gpu <value> should be passed as environment variable', async () => {
     await run('--gpu', 'angle_indirect');
-    expect(cliCall().env).not.toHaveProperty('DETOX_GPU');
+    expect(cliCall().env).toHaveProperty('DETOX_GPU');
     expect(cliCall().fullCommand).toMatch(/\bDETOX_GPU="angle_indirect" /);
   });
 
   test('--device-boot-args should be passed as an environment variable (without deprecation warnings)', async () => {
     await run('--device-boot-args="--verbose"');
-    expect(cliCall().env).not.toHaveProperty('DETOX_DEVICE_BOOT_ARGS');
+    expect(cliCall().env).toHaveProperty('DETOX_DEVICE_BOOT_ARGS');
     expect(cliCall().fullCommand).toMatch(/\bDETOX_DEVICE_BOOT_ARGS="--verbose" /);
     expect(logger().warn).not.toHaveBeenCalledWith(DEVICE_LAUNCH_ARGS_DEPRECATION);
   });
 
-  test('--device-launch-args should serve as a deprecated alias to --device-boot-args', async () => {
-    await run(`--device-launch-args="--verbose"`);
-    expect(cliCall().env).not.toHaveProperty('DETOX_DEVICE_BOOT_ARGS');
-    expect(cliCall().fullCommand).toMatch(/\bDETOX_DEVICE_BOOT_ARGS="--verbose" /);
-    expect(logger().warn).toHaveBeenCalledWith(DEVICE_LAUNCH_ARGS_DEPRECATION);
-  });
-
   test('--app-launch-args should be passed as an environment variable', async () => {
     await run(`--app-launch-args="--debug yes"`);
-    expect(cliCall().env).not.toHaveProperty('DETOX_APP_LAUNCH_ARGS');
+    expect(cliCall().env).toHaveProperty('DETOX_APP_LAUNCH_ARGS');
     expect(cliCall().fullCommand).toMatch(/\bDETOX_APP_LAUNCH_ARGS="--debug yes" /);
   });
 
   test('--use-custom-logger false should be prevent passing environment variable', async () => {
     await run(`--use-custom-logger=false`);
-    expect(cliCall().env).not.toHaveProperty('DETOX_USE_CUSTOM_LOGGER');
+    expect(cliCall().env).toHaveProperty('DETOX_USE_CUSTOM_LOGGER');
     expect(cliCall().fullCommand).toMatch(/\bDETOX_USE_CUSTOM_LOGGER=false /);
   });
 
@@ -302,13 +377,13 @@ describe('CLI', () => {
   test('--force-adb-install should be passed as environment variable', async () => {
     singleConfig().device.type = 'android.emulator';
     await run(`--force-adb-install`);
-    expect(cliCall().env).not.toHaveProperty('DETOX_FORCE_ADB_INSTALL');
+    expect(cliCall().env).toHaveProperty('DETOX_FORCE_ADB_INSTALL');
     expect(cliCall().fullCommand).toMatch(/\bDETOX_FORCE_ADB_INSTALL=true /);
   });
 
   test.each([['-n'], ['--device-name']])('%s <value> should be passed as environment variable', async (__device_name) => {
     await run(__device_name, 'TheDevice');
-    expect(cliCall().env).not.toHaveProperty('DETOX_DEVICE_NAME');
+    expect(cliCall().env).toHaveProperty('DETOX_DEVICE_NAME');
     expect(cliCall().fullCommand).toMatch(/\bDETOX_DEVICE_NAME="TheDevice" /);
   });
 
@@ -320,8 +395,6 @@ describe('CLI', () => {
     expect(cliCall().argv.slice(-2)).toEqual(['e2e/01.sanity.test.js', 'e2e/02.sanity.test.js']);
   });
 
-  test.todo('--inspect-brk should work');
-
   test.each([
     ['-d e2eFolder', / e2eFolder$/, /\bDETOX_DEBUG_SYNCHRONIZATION=3000/],
     ['--debug-synchronization e2eFolder', / e2eFolder$/, /\bDETOX_DEBUG_SYNCHRONIZATION=3000/],
@@ -399,15 +472,14 @@ describe('CLI', () => {
     expect(cliCall().argv).toContain('--deepParameter');
   });
 
-  // TODO: revive this test
-  test.skip('--inspect-brk should prepend "node --inspect-brk" to the command', async () => {
-    await run('--inspect-brk');
+  test('--inspect-brk should activate inspectBrk hook', async () => {
+    detoxConfig.testRunner.inspectBrk = (config) => {
+      config.args.customFlag = true;
+      return config;
+    };
 
-    if (process.platform === 'win32') {
-      expect(cliCall().argv).toMatch(/^node --inspect-brk \.\/node_modules\/jest\/bin\/jest\.js/);
-    } else {
-      expect(cliCall().argv).toMatch(/^node --inspect-brk \.\/node_modules\/\.bin\/jest/);
-    }
+    await run('--inspect-brk');
+    expect(cliCall().argv).toContain('--customFlag');
   });
 
   test('should append $DETOX_ARGV_OVERRIDE to detox test ... command and print a warning', async () => {
@@ -423,6 +495,16 @@ describe('CLI', () => {
     expect(logger().warn).toHaveBeenCalledWith(expect.stringContaining('$DETOX_ARGV_OVERRIDE is detected'));
   });
 
+  test('should append $DETOX_ARGV_OVERRIDE "--" part to test runner command', async () => {
+    process.env.PLATFORM = 'ios';
+    process.env.DETOX_ARGV_OVERRIDE = '-- --help';
+
+    await run();
+
+    expect(cliCall().argv.slice(-1)).toEqual(['--help']);
+    expect(logger().warn).toHaveBeenCalledWith(expect.stringContaining('$DETOX_ARGV_OVERRIDE is detected'));
+  });
+
   // Helpers
 
   function tempfile(extension, content) {
@@ -477,7 +559,12 @@ describe('CLI', () => {
   }
 
   async function run(...args) {
-    detoxConfigPath = tempfile('.json', JSON.stringify(detoxConfig));
+    let contents = `module.exports = ${util.inspect(detoxConfig, { depth: Infinity })};`;
+    if (detoxConfig.testRunner && detoxConfig.testRunner.inspectBrk) {
+      contents = contents.replace(/\[Function.*\]/m, detoxConfig.testRunner.inspectBrk.toString());
+    }
+
+    detoxConfigPath = tempfile('.js', contents);
     const __configPath = Math.random() > 0.5 ? '-C' : '--config-path';
     return runRaw('test', __configPath, detoxConfigPath, ...args);
   }
@@ -498,7 +585,7 @@ describe('CLI', () => {
     return {
       ...mockCall,
       fullCommand: _.chain(logger().log.mock.calls)
-        .filter(([_level, _childMeta, meta]) => meta && meta.event === 'RUN_START')
+        .filter(([_level, _childMeta, meta]) => meta && meta.env)
         .get(index)
         .get(3)
         .value(),

package/local-cli/testCommand/TestRunnerCommand.js

@@ -5,51 +5,83 @@ const parser = require('yargs-parser');
 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');
 
 class TestRunnerCommand {
-  constructor() {
-    this._argv = {};
-    this._env = {};
-    this._envHint = {};
-    this._retries = 0;
-    /** @type {Detox.DetoxDeviceConfig} */
-    this._deviceConfig = null;
+  /*
+    @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 = {};
+    if (runnerConfig.forwardEnv) {
+      this._envFwd = this._buildEnvOverride(cliConfig, deviceConfig);
+      Object.assign(this._envHint, this._envFwd);
+    }
   }
 
-  /**
-   * @param {Detox.DetoxDeviceConfig} config
-   * @returns {this}
-   */
-  setDeviceConfig(config) {
-    this._deviceConfig = config;
+  async execute() {
+    let runsLeft = 1 + this._retries;
+    let launchError = null;
 
-    return this;
-  }
+    do {
+      try {
+        await this._spawnTestRunner();
+        launchError = null;
+      } catch (e) {
+        launchError = e;
 
-  /**
-   * @param {Detox.DetoxTestRunnerConfig} config
-   * @returns {this}
-   */
-  setRunnerConfig(config) {
-    this._argv = config.args;
-    this._retries = config.retries;
+        const failedTestFiles = detox.session.testResults.filter(r => !r.success);
 
-    if (config.inspectBrk === true) {
-      this._env = this._envHint;
+        const { bail } = detox.config.testRunner;
+        if (bail && failedTestFiles.some(r => r.isPermanentFailure)) {
+          throw e;
+        }
+
+        const testFilesToRetry = failedTestFiles.filter(r => !r.isPermanentFailure).map(r => r.testFilePath);
+        if (_.isEmpty(testFilesToRetry)) {
+          throw e;
+        }
+
+        if (--runsLeft > 0) {
+          // @ts-ignore
+          detox.session.testSessionIndex++; // it is always the primary context, so we can update it
+          this._argv._ = testFilesToRetry;
+          this._logRelaunchError();
+        }
+      }
+    } while (launchError && runsLeft > 0);
+
+    if (launchError) {
+      throw launchError;
     }
+  }
 
-    return this;
+  _buildEnvHint(env) {
+    return _(env)
+      .mapKeys((_value, key) => key.toUpperCase())
+      .pickBy((_value, key) => key.startsWith('DETOX_'))
+      .omit(['DETOX_CONFIG_SNAPSHOT_PATH'])
+      .value();
   }
 
   /**
-   * @param {Partial<Readonly<DetoxInternals.DetoxCLIConfig>>} cliConfig
-   * @returns {this}
+   * @param {DetoxInternals.CLIConfig} cliConfig
+   * @param {Detox.DetoxDeviceConfig} deviceConfig
    */
-  replicateCLIConfig(cliConfig) {
-    this._envHint = _.omitBy({
+  _buildEnvOverride(cliConfig, deviceConfig) {
+    return _.omitBy({
       DETOX_APP_LAUNCH_ARGS: cliConfig.appLaunchArgs,
       DETOX_ARTIFACTS_LOCATION: cliConfig.artifactsLocation,
       DETOX_CAPTURE_VIEW_HIERARCHY: cliConfig.captureViewHierarchy,
@@ -59,7 +91,7 @@ class TestRunnerCommand {
       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.')
+      DETOX_FORCE_ADB_INSTALL: deviceConfig.type.startsWith('android.')
         ? cliConfig.forceAdbInstall
         : undefined,
       DETOX_GPU: cliConfig.gpu,
@@ -76,50 +108,13 @@ class TestRunnerCommand {
       DETOX_TAKE_SCREENSHOTS: cliConfig.takeScreenshots,
       DETOX_USE_CUSTOM_LOGGER: cliConfig.useCustomLogger,
     }, _.isUndefined);
-
-    return this;
   }
 
-  async execute() {
-    let runsLeft = 1 + this._retries;
-    let launchError;
-
-    do {
-      try {
-        if (launchError) {
-          const list = this._argv._.map((file, index) => `  ${index + 1}. ${file}`).join('\n');
-          detox.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();
-        launchError = null;
-      } catch (e) {
-        launchError = e;
-
-        const { failedTestFiles } = detox.session;
-        if (_.isEmpty(failedTestFiles)) {
-          throw e;
-        }
-
-        this._argv._ = failedTestFiles.slice();
-        this._env.DETOX_RERUN_INDEX = 1 + (this._env.DETOX_RERUN_INDEX || 0);
-        detox.session.failedTestFiles.splice(0, Infinity);
-      }
-    } while (launchError && --runsLeft > 0);
-
-    if (launchError) {
-      throw launchError;
-    }
-  }
-
-  async _doExecute() {
+  async _spawnTestRunner() {
     const fullCommand = this._buildSpawnArguments().map(escapeSpaces);
     const fullCommandWithHint = printEnvironmentVariables(this._envHint) + fullCommand.join(' ');
 
-    detox.log.info({ event: 'RUN_START', env: this._envHint }, fullCommandWithHint);
+    log.info({ env: this._envHint }, fullCommandWithHint);
 
     return new Promise((resolve, reject) => {
       cp.spawn(fullCommand[0], fullCommand.slice(1), {
@@ -127,12 +122,12 @@ class TestRunnerCommand {
         stdio: 'inherit',
         env: _({})
           .assign(process.env)
-          .assign(this._env)
+          .assign(this._envFwd)
           .omitBy(_.isUndefined)
           .tap(prependNodeModulesBinToPATH)
           .value()
       })
-        .on('error', (err) => reject(err))
+        .on('error', /* istanbul ignore next */ (err) => reject(err))
         .on('exit', (code) => code === 0
           ? resolve()
           : reject(new DetoxRuntimeError(`Command failed with exit code = ${code}:\n${fullCommandWithHint}`)
@@ -141,6 +136,7 @@ class TestRunnerCommand {
   }
 
   _buildSpawnArguments() {
+    /* istanbul ignore next */
     const { _: specs = [], '--': passthrough = [], $0, ...argv } = this._argv;
     const { _: $0_, ...$0argv } = parser($0);
 
@@ -151,6 +147,17 @@ class TestRunnerCommand {
       ...unparse({ _: [...passthrough, ...specs] }),
     ].map(String);
   }
+
+  _logRelaunchError() {
+    const list = this._argv._.map((file, index) => {
+      return `  ${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'
+    );
+  }
 }
 
 module.exports = TestRunnerCommand;

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.',
   },