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

package/internals.d.ts

@@ -3,84 +3,233 @@
 
 declare global {
   namespace DetoxInternals {
+    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#globalSetup}
+       * Use with a caution, when you still have no config, yet need to avoid {@link Facade#init}
        */
-      resolveConfig(options?: Partial<DetoxGlobalSetupOptions>): Promise<RuntimeConfig>;
+      resolveConfig(options?: Partial<DetoxInitOptions>): Promise<RuntimeConfig>;
 
       /**
-       * This is the phase where Detox reads its configuration, starts a server.
+       * 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.
        */
-      globalSetup(options?: Partial<DetoxGlobalSetupOptions>): Promise<void>;
+      getStatus(): DetoxStatus;
 
       /**
-       * This is the phase where Detox loads its expection library and starts a device.
+       * Starts a new Detox test session with the provided configuration.
+       * See {@link https://wix.github.io/Detox/docs/api/internals} for more details.
        */
-      setup(options?: Partial<DetoxConfigurationSetupOptions>): Promise<void>;
+      init(options?: Partial<DetoxInitOptions>): Promise<void>;
 
       /**
-       * The teardown phase deallocates the 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.
        */
-      teardown(): Promise<void>;
+      installWorker(options?: Partial<DetoxInstallWorkerOptions>): Promise<void>;
 
       /**
-       * The global cleanup phase should happen after all the tests have finished.
-       * This is the phase where the Detox server shuts down.
+       * Deallocates the device.
+       * Most Client API (device, by, element, expect) will stop working, except for the logger.
        */
-      globalTeardown(): Promise<void>;
-      // endregion
+      uninstallWorker(): Promise<void>;
 
-      // region Lifecycle
-      onRunStart(event: unknown): Promise<void>;
-      onRunDescribeStart(event: unknown): Promise<void>;
-      onTestStart(event: unknown): Promise<void>;
-      onHookStart(event: unknown): Promise<void>;
-      onHookFailure(event: unknown): Promise<void>;
-      onHookSuccess(event: unknown): Promise<void>;
-      onTestFnStart(event: unknown): Promise<void>;
-      onTestFnFailure(event: unknown): Promise<void>;
-      onTestFnSuccess(event: unknown): Promise<void>;
-      onTestDone(event: unknown): Promise<void>;
-      onRunDescribeFinish(event: unknown): Promise<void>;
-      onRunFinish(event: unknown): Promise<void>;
+      /**
+       * 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
 
+      //#region Lifecycle
+      /**
+       * Reports that the test runner started executing a test suite, e.g. a `beforeAll` hook or a first test.
+       */
+      onRunDescribeStart(event: {
+        /** Test suite name */
+        name: string;
+      }): Promise<void>;
+      /**
+       * Reports that the test runner started executing a specific test.
+       */
+      onTestStart(event: {
+        /** Test name */
+        title: string;
+        /** Test name including the ancestor suite titles */
+        fullName: string;
+        /**
+         * N-th time this test is running, if there is a retry mechanism.
+         *
+         * @default 1
+         */
+        invocations?: number;
+        status: 'running';
+      }): Promise<void>;
+      /**
+       * Reports about an error in the midst of `beforeAll`, `beforeEach`, `afterEach`, `afterAll` or any other hook.
+       */
+      onHookFailure(event: {
+        error: Error | string;
+        /**
+         * @example 'beforeAll'
+         * @example 'afterEach'
+         */
+        hook: string;
+      }): Promise<void>;
+      /**
+       * Reports about an error in the midst of a test function, `test` or `it`.
+       */
+      onTestFnFailure(event: {
+        error: Error | string;
+      }): Promise<void>;
+      /**
+       * Reports the final status of the test, `passed` or `failed`.
+       */
+      onTestDone(event: {
+        /** Test name */
+        title: string;
+        /** Test name including the ancestor suite titles */
+        fullName: string;
+        /**
+         * N-th time this test is running, if there is a retry mechanism.
+         *
+         * @default 1
+         */
+        invocations?: number;
+        status: 'passed' | 'failed';
+        /** Whether a timeout was the reason for why the test failed. */
+        timedOut?: boolean;
+      }): Promise<void>;
       /**
-       * Reports to Detox CLI about failed tests that could have been re-run if
+       * Reports that the test runner has finished executing a test suite, e.g. all the `afterAll` hooks have been executed or the last test has finished running.
+       */
+      onRunDescribeFinish(event: {
+        /** Test suite name */
+        name: string;
+      }): Promise<void>;
+
+      /**
+       * Reports to Detox CLI about passed and failed test files.
+       * The failed test files might be re-run again if
        * {@link Detox.DetoxTestRunnerConfig#retries} is set to a non-zero.
        *
-       * @param testFilePaths array of failed test files' paths
-       * @param permanent whether the failure is permanent, and the tests
-       * should not be re-run.
+       * @param testResults - reports about test files
        */
-      reportFailedTests(testFilePaths: string[], permanent?: boolean): Promise<void>;
-      // endregion
+      reportTestResults(testResults: DetoxTestFileReport[]): Promise<void>;
+      //#endregion
 
       readonly config: RuntimeConfig;
       readonly log: Detox.Logger;
-      readonly trace: Detox.Tracer;
       readonly session: SessionState;
+      readonly tracing: {
+        /**
+         * Creates a readable stream of the currently recorded events in Chrome Trace Event format.
+         *
+         * @see {@link https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQtYMH4h6I0nSsKchNAySU}
+         * @see {import('trace-event-lib').DurationBeginEvent}
+         * @see {import('trace-event-lib').DurationEndEvent}
+         * @see {import('trace-event-lib').InstantEvent}
+         */
+        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;
+    }
 
-      readonly worker: unknown;
+    interface Worker extends Detox.DetoxExportWrapper {
+      readonly id: string;
     }
 
-    type DetoxGlobalSetupOptions = {
+    type DetoxInitOptions = {
       cwd: string;
+      /**
+       * @internal
+       */
       argv: Record<string, unknown>;
       testRunnerArgv: Record<string, unknown>;
       override: Partial<Detox.DetoxConfig>;
+      /** @inheritDoc */
+      global: NodeJS.Global | {};
+      /**
+       * Worker ID. Used to distinguish allocated workers in parallel test execution environment.
+       *
+       * If explicitly set to null, tells {@link Facade#init} to skip {@link Facade#installWorker} call.
+       * Useful for complex test runner integrations, where you have to install the worker via a separate call,
+       * when the environment is ready for that.
+       *
+       * @default 'worker'
+       */
+      workerId: string | null;
     };
 
-    type DetoxConfigurationSetupOptions = {
-      global: NodeJS.Global;
-      workerId: number;
+    type DetoxInstallWorkerOptions = {
+      /**
+       * Used for integration with sandboxed test environments.
+       * {@link DetoxInternals.Facade#setup} might override {@link Console} methods
+       * to integrate it with Detox loggeing subsystem.
+       */
+      global: NodeJS.Global | {};
+      /**
+       * Worker ID. Used to distinguish allocated workers in parallel test execution environment.
+       *
+       * @default 'worker'
+       */
+      workerId: string;
+    };
+
+    type DetoxTestFileReport = {
+      /**
+       * Global or relative path to the failed test file.
+       */
+      testFilePath: string;
+      /**
+       * Whether the test passed or not.
+       */
+      success: boolean;
+      /**
+       * Top-level error if the entire test file failed.
+       */
+      testExecError?: { name?: string; message: string; stack?: string; };
+      /**
+       * If the test failed, it should tell whether the failure is permanent.
+       * Permanent failure means that the test file should not be re-run.
+       *
+       * @default false
+       * @see {Detox.DetoxTestRunnerConfig#retries}
+       */
+      isPermanentFailure?: boolean;
     };
 
     type SessionState = Readonly<{
-      failedTestFiles: string[];
-      testFilesToRetry: string[];
+      /**
+       * Randomly generated ID for the entire Detox test session, including retries.
+       */
+      id: string;
+      /**
+       * Results of test file executions. Primarily used for Detox CLI retry mechanism.
+       */
+      testResults: DetoxTestFileReport[];
+      /**
+       * Retry index of the test session: 0..retriesCount.
+       */
       testSessionIndex: number;
+      /**
+       * Count of Detox contexts with a worker installed.
+       * Oversimplified, it reflects the count of allocated devices in the current test session.
+       *
+       * @see {Facade#init}
+       * @see {Facade#installWorker}
+       */
       workersCount: number;
     }>;
 
@@ -93,16 +242,29 @@ 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<DetoxCLIConfig>;
+      cli: Readonly<CLIConfig>;
       device: Readonly<Detox.DetoxDeviceConfig>;
       logger: Readonly<Detox.DetoxLoggerConfig>;
       testRunner: Readonly<Detox.DetoxTestRunnerConfig>;
       session: Readonly<Detox.DetoxSessionConfig>;
     }>;
 
-    type DetoxCLIConfig = Readonly<Partial<{
+    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;
       captureViewHierarchy: string;

package/local-cli/build.js

@@ -65,7 +65,7 @@ module.exports.handler = async function build(argv) {
     }
 
     if (app.binaryPath && !fs.existsSync(app.binaryPath)) {
-      detox.log.warn('\nImportant: after running the build command, Detox could not find your app at the given binary path:\n\t' + app.binaryPath + "\nMake sure it is correct, otherwise you'll get an error on an attempt to install your app.\n");
+      detox.log.warn('After running the build command, Detox could not find your app at the given binary path:\n\t' + app.binaryPath + "\nMake sure it is correct, otherwise you'll get an error on an attempt to install your app.\n");
     }
   }
 };

package/local-cli/cli.js

@@ -1,8 +1,11 @@
 #!/usr/bin/env node
+const fs = require('fs');
+
+const _ = require('lodash');
 const yargs = require('yargs');
 
+const logger = require('../internals').log.child({ cat: 'cli' });
 const DetoxError = require('../src/errors/DetoxError');
-const logger = require('../src/utils/logger').child({ __filename });
 
 yargs
   .scriptName('detox')
@@ -25,12 +28,14 @@ yargs
   .wrap(yargs.terminalWidth() * 0.9)
   .fail(function(msg, err, program) {
     if (err) {
-      const lines = DetoxError.format(err).split('\n');
-      for (const line of lines) {
-        logger.error(line);
+      const message = DetoxError.format(err);
+      if (message) {
+        logger.error(message);
+        process.stderr.write('\n');
       }
-      // eslint-disable-next-line no-console
-      console.error('');
+
+      // @ts-ignore
+      _.attempt(() => fs.unlinkSync(logger.file));
       // eslint-disable-next-line no-process-exit
       process.exit(1);
     }

package/local-cli/init.js

@@ -1,5 +1,6 @@
 const fs = require('fs');
 const path = require('path');
+const util = require('util');
 
 const detox = require('../internals');
 
@@ -8,10 +9,11 @@ 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() {
+  createDetoxConfig();
   createJestFolderE2E();
   process.exit(exitCode); // eslint-disable-line
 };
@@ -51,44 +53,66 @@ function createFile(filename, content) {
 
 function createJestFolderE2E() {
   createFolder('e2e', {
-    'config.json': jestTemplates.runnerConfig,
+    'jest.config.js': jestTemplates.runnerConfig,
     'starter.test.js': jestTemplates.starter,
   });
+}
 
-  createFile('.detoxrc.json', JSON.stringify({
-    testRunner: {
-      args: {
-        config: 'e2e/config.json'
-      },
-    },
-
-    ...createDefaultConfigurations(),
-  }, null, 2));
+function createDetoxConfig() {
+  createFile('.detoxrc.js',
+    '/** @type {Detox.DetoxConfig} */\n' +
+    'module.exports = ' +
+    util.inspect(createDefaultConfigurations(), { compact: false, depth: Infinity }) +
+    ';\n'
+  );
 }
 
+/** @returns {Detox.DetoxConfig} */
 function createDefaultConfigurations() {
   return {
     testRunner: {
       args: {
         $0: 'jest',
-        config: 'e2e/config.json',
+        config: 'e2e/jest.config.js',
+      },
+      jest: {
+        setupTimeout: 120000,
       },
     },
     apps: {
-      ios: {
+      'ios.debug': {
         type: 'ios.app',
-        binaryPath: 'SPECIFY_PATH_TO_YOUR_APP_BINARY',
+        binaryPath: 'ios/build/Build/Products/Debug-iphonesimulator/YOUR_APP.app',
+        build: 'xcodebuild -workspace ios/YOUR_APP.xcworkspace -scheme YOUR_APP -configuration Debug -sdk iphonesimulator -derivedDataPath ios/build',
+      },
+      'ios.release': {
+        type: 'ios.app',
+        binaryPath: 'ios/build/Build/Products/Release-iphonesimulator/YOUR_APP.app',
+        build: 'xcodebuild -workspace ios/YOUR_APP.xcworkspace -scheme YOUR_APP -configuration Release -sdk iphonesimulator -derivedDataPath ios/build',
+      },
+      'android.debug': {
+        type: 'android.apk',
+        binaryPath: 'android/app/build/outputs/apk/debug/app-debug.apk',
+        build: 'cd android ; ./gradlew assembleDebug assembleAndroidTest -DtestBuildType=debug ; cd -',
+        reversePorts: [8081],
       },
-      android: {
+      'android.release': {
         type: 'android.apk',
-        binaryPath: 'SPECIFY_PATH_TO_YOUR_APP_BINARY',
+        binaryPath: 'android/app/build/outputs/apk/release/app-release.apk',
+        build: 'cd android ; ./gradlew assembleRelease assembleAndroidTest -DtestBuildType=release ; cd -',
       },
     },
     devices: {
       simulator: {
         type: 'ios.simulator',
         device: {
-          type: 'iPhone 11',
+          type: 'iPhone 12',
+        },
+      },
+      attached: {
+        type: 'android.attached',
+        device: {
+          adbName: '.*',
         },
       },
       emulator: {
@@ -99,13 +123,29 @@ function createDefaultConfigurations() {
       },
     },
     configurations: {
-      ios: {
+      'ios.sim.debug': {
+        device: 'simulator',
+        app: 'ios.debug',
+      },
+      'ios.sim.release': {
         device: 'simulator',
-        app: 'ios',
+        app: 'ios.release',
+      },
+      'android.att.debug': {
+        device: 'attached',
+        app: 'android.debug',
+      },
+      'android.att.release': {
+        device: 'attached',
+        app: 'android.release',
+      },
+      'android.emu.debug': {
+        device: 'emulator',
+        app: 'android.debug',
       },
-      android: {
+      'android.emu.release': {
         device: 'emulator',
-        app: 'android',
+        app: 'android.release',
       },
     },
   };

package/local-cli/rebuild-framework-cache.js

@@ -4,7 +4,7 @@ const path = require('path');
 
 const fs = require('fs-extra');
 
-const log = require('../src/utils/logger').child({ __filename });
+const log = require('../src/utils/logger').child({ cat: 'cli' });
 
 module.exports.command = 'rebuild-framework-cache';
 module.exports.desc = 'Rebuilds a cached Detox framework for the current environment in ~/Library/Detox. The cached framework is unique for each combination of Xcode and Detox version. (macOS only)';

package/local-cli/reset-lock-file.js

@@ -0,0 +1,16 @@
+const { log } = require('../internals');
+const DeviceRegistry = require('../src/devices/DeviceRegistry');
+const { getDetoxLibraryRootPath } = require('../src/utils/environment');
+
+
+module.exports.command = 'reset-lock-file';
+module.exports.desc = 'Resets all Detox lock files. Useful when you need to run multiple `detox test` commands in parallel with --keepLockFile.';
+
+module.exports.handler = async function resetLockFile() {
+  await Promise.all([
+    DeviceRegistry.forIOS().reset(),
+    DeviceRegistry.forAndroid().reset(),
+  ]);
+
+  log.info(`Cleaned lock files from: ${getDetoxLibraryRootPath()}`);
+};

package/local-cli/templates/jest.js

@@ -1,15 +1,18 @@
 const firstTestContent = require('./firstTestContent');
 
-const runnerConfig = `{
-  "globalSetup": "detox/runners/jest/globalSetup",
-  "globalTeardown": "detox/runners/jest/globalTeardown",
-  "maxWorkers": 1,
-  "reporters": ["detox/runners/jest/reporter"],
-  "testEnvironment": "detox/runners/jest/testEnvironment",
-  "testMatch": ["<rootDir>/e2e/**/*.test.js"],
-  "testTimeout": 120000,
-  "verbose": true
-}
+const runnerConfig = `\
+/** @type {import('@jest/types').Config.InitialOptions} */
+module.exports = {
+  rootDir: '..',
+  testMatch: ['<rootDir>/e2e/**/*.test.js'],
+  testTimeout: 120000,
+  maxWorkers: 1,
+  globalSetup: 'detox/runners/jest/globalSetup',
+  globalTeardown: 'detox/runners/jest/globalTeardown',
+  reporters: ['detox/runners/jest/reporter'],
+  testEnvironment: 'detox/runners/jest/testEnvironment',
+  verbose: true,
+};
 `;
 
 exports.starter = firstTestContent;

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.testRunner)
-      .setDeviceConfig(detox.config.device)
-      .replicateCLIConfig(detox.config.cli);
+    const runnerCommand = new TestRunnerCommand({
+      config,
+      env: process.env,
+    });
 
     await runnerCommand.execute();
   } finally {
-    await detox.globalTeardown();
+    await detox.cleanup();
   }
 };