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

package/internals.d.ts

@@ -3,99 +3,268 @@
 
 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>;
       /**
-       * Powers the "--retries <N>" of Detox CLI under the hood.
+       * Reports about an error in the midst of `beforeAll`, `beforeEach`, `afterEach`, `afterAll` or any other hook.
        */
-      reportFailedTests(testFilePaths: string[]): Promise<void>;
-      // endregion
+      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 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 testResults - reports about test files
+       */
+      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;
+      };
 
-      readonly worker: unknown;
+      /**
+       * Not documented on purpose.
+       * Provides direct access to the object which holds the device driver, websocket client, matchers, expectations, etc.
+       */
+      readonly worker: Worker;
     }
 
-    type DetoxGlobalSetupOptions = {
+    interface Worker extends Detox.DetoxExportWrapper {
+      readonly id: string;
+    }
+
+    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 SessionState = Readonly<PrimarySessionState | SecondarySessionState>;
-
-    type SecondarySessionState = {
-      workersCount: number;
+    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 PrimarySessionState = PrimarySessionState & {
-      failedTestFiles: string[];
-    };
+    type SessionState = Readonly<{
+      /**
+       * 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;
+    }>;
 
     type RuntimeConfig = Readonly<{
       configurationName: string;
 
-      appsConfig: Record<string, Readonly<Detox.DetoxAppConfig>>;
-      artifactsConfig: Detox.DetoxArtifactsConfig;
-      behaviorConfig: Detox.DetoxBehaviorConfig;
-      cliConfig: DetoxCLIConfig;
-      deviceConfig: Detox.DetoxDeviceConfig;
-      loggerConfig: Detox.DetoxLoggerConfig;
-      runnerConfig: Detox.DetoxTestRunnerConfig;
-      sessionConfig: Detox.DetoxSessionConfig;
+      /**
+       * Dictionary of app configurations,
+       * where the keys are defined by {@link Detox.DetoxAppConfig#name}
+       * or equal to "default" if the name is not configured.
+       */
+      apps: Record<string, Readonly<Detox.DetoxAppConfig>>;
+      artifacts: Readonly<RuntimeArtifactsConfig>;
+      behavior: Readonly<Detox.DetoxBehaviorConfig>;
+      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

@@ -37,7 +37,7 @@ module.exports.builder = {
 };
 
 module.exports.handler = async function build(argv) {
-  const { appsConfig, errorComposer } = await detox.resolveConfig({ argv });
+  const { apps: appsConfig, errorComposer } = await detox.resolveConfig({ argv });
   const apps = _.entries(appsConfig);
 
   for (const [appName, app] of apps) {
@@ -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/build.test.js

@@ -14,12 +14,12 @@ describe('build', () => {
       const DetoxConfigErrorComposer = require('../src/errors/DetoxConfigErrorComposer');
 
       const config = {
-        appsConfig: {},
-        artifactsConfig: {},
-        behaviorConfig: {},
+        apps: {},
+        artifacts: {},
+        behavior: {},
         errorComposer: new DetoxConfigErrorComposer(),
-        deviceConfig: {},
-        sessionConfig: {}
+        device: {},
+        session: {}
       };
 
       return ({
@@ -44,14 +44,14 @@ describe('build', () => {
   });
 
   it('runs the build script from the composed device config', async () => {
-    detox.config.appsConfig.default = { build: 'yet another command' };
+    detox.config.apps.default = { build: 'yet another command' };
 
     await callCli('./build', 'build');
     expect(execSync).toHaveBeenCalledWith('yet another command', expect.anything());
   });
 
   it('skips building the app if the binary exists and --if-missing flag is set', async () => {
-    detox.config.appsConfig.default = { build: 'yet another command', binaryPath: __filename };
+    detox.config.apps.default = { build: 'yet another command', binaryPath: __filename };
 
     await callCli('./build', 'build -i');
     expect(execSync).not.toHaveBeenCalled();
@@ -63,32 +63,32 @@ describe('build', () => {
   });
 
   it('fails with an error if a build script has not been found', async () => {
-    detox.config.appsConfig.default = {};
+    detox.config.apps.default = {};
     await expect(callCli('./build', 'build')).rejects.toThrowError(/Failed to build/);
   });
 
   it('should ignore missing build command with -s, --silent flag', async () => {
-    detox.config.appsConfig.default = {};
+    detox.config.apps.default = {};
     await expect(callCli('./build', 'build -s')).resolves.not.toThrowError();
     expect(detox.log.warn).not.toHaveBeenCalled();
   });
 
   it('should print a warning upon user build script failure', async () => {
-    detox.config.appsConfig.default = { build: 'a command' };
+    detox.config.apps.default = { build: 'a command' };
     execSync.mockImplementation(() => { throw new Error('Build failure'); });
     await expect(callCli('./build', 'build')).rejects.toThrowError(/Build failure/);
     expect(detox.log.warn).toHaveBeenCalledWith(expect.stringContaining('You are responsible'));
   });
 
   it('should print a warning if app is not found at binary path', async () => {
-    detox.config.appsConfig.default = { binaryPath: tempfile() };
+    detox.config.apps.default = { binaryPath: tempfile() };
     await expect(callCli('./build', 'build -s')).resolves.not.toThrowError();
     expect(detox.log.warn).toHaveBeenCalledWith(expect.stringContaining('could not find your app at the given binary path'));
   });
 
   it('should print extra message with the app name before building (in a multi-app configuration)', async () => {
-    detox.config.appsConfig.app1 = { binaryPath: tempfile(), build: ':' };
-    detox.config.appsConfig.app2 = { binaryPath: tempfile(), build: ':' };
+    detox.config.apps.app1 = { binaryPath: tempfile(), build: ':' };
+    detox.config.apps.app2 = { binaryPath: tempfile(), build: ':' };
 
     await expect(callCli('./build', 'build -s')).resolves.not.toThrowError();
     expect(detox.log.info).toHaveBeenCalledWith(expect.stringContaining('app1'));
@@ -96,7 +96,7 @@ describe('build', () => {
   });
 
   it('should not print that extra message when the app is single', async () => {
-    detox.config.appsConfig.default = { binaryPath: tempfile(), build: ':' };
+    detox.config.apps.default = { binaryPath: tempfile(), build: ':' };
 
     await expect(callCli('./build', 'build -s')).resolves.not.toThrowError();
     expect(detox.log.info).not.toHaveBeenCalledWith(expect.stringContaining('default'));

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,11 @@ 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);
-      }
+      logger.error(DetoxError.format(err));
       // eslint-disable-next-line no-console
-      console.error('');
+      process.stderr.write('\n');
+      // @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;