detox 20.0.4-breaking.new-global-lifecycle.0 → 20.0.7-prerelease.0

package/internals.d.ts

@@ -3,33 +3,40 @@
 
 declare global {
   namespace DetoxInternals {
+    type DetoxStatus = 'inactive' | 'init' | 'active' | 'cleanup';
+
     type Facade = {
       // 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>;
+
+      /**
+       *
+       */
+      getStatus(): DetoxStatus;
 
       /**
        * This is the phase where Detox reads its configuration, starts a server.
        */
-      globalSetup(options?: Partial<DetoxGlobalSetupOptions>): Promise<void>;
+      init(options?: Partial<DetoxInitOptions>): Promise<void>;
 
       /**
-       * This is the phase where Detox loads its expection library and starts a device.
+       * This is the phase where Detox loads its expectation library and starts a device.
        */
-      setup(options?: Partial<DetoxConfigurationSetupOptions>): Promise<void>;
+      installWorker(options?: Partial<DetoxInstallWorkerOptions>): Promise<void>;
 
       /**
-       * The teardown phase deallocates the device.
+       * Deallocates the device.
        */
-      teardown(): Promise<void>;
+      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.
        */
-      globalTeardown(): Promise<void>;
+      cleanup(): Promise<void>;
       // endregion
 
       // region Lifecycle
@@ -59,28 +66,69 @@ declare global {
 
       readonly config: RuntimeConfig;
       readonly log: Detox.Logger;
-      readonly trace: Detox.Tracer;
       readonly session: SessionState;
 
-      readonly worker: unknown;
+      readonly worker: Worker;
+    }
+
+    interface Worker extends Detox.DetoxExportWrapper {
+      readonly id: string;
     }
 
-    type DetoxGlobalSetupOptions = {
+    type DetoxInitOptions = {
       cwd: string;
       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 = {
+    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;
-      workerId: number;
+      /**
+       * Worker ID. Used to distinguish allocated workers in parallel test execution environment.
+       *
+       * @default 'worker'
+       */
+      workerId: string;
     };
 
     type SessionState = Readonly<{
+      /**
+       * Randomly generated ID for the entire Detox test session, including retries.
+       */
+      id: string;
+      /**
+       * Permanently failed test file paths.
+       */
       failedTestFiles: string[];
+      /**
+       * Failed test file paths suggested to retry via Detox CLI mechanism.
+       */
       testFilesToRetry: string[];
+      /**
+       * Retry index of the test session: 0..retriesCount.
+       */
       testSessionIndex: number;
+      /**
+       * TODO
+       */
       workersCount: number;
     }>;
 
@@ -95,14 +143,14 @@ declare global {
       apps: Record<string, Readonly<Detox.DetoxAppConfig>>;
       artifacts: Readonly<Detox.DetoxArtifactsConfig>;
       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 CLIConfig = Readonly<Partial<{
       appLaunchArgs: string;
       artifactsLocation: string;
       captureViewHierarchy: string;

package/local-cli/cli.js

@@ -2,7 +2,7 @@
 const yargs = require('yargs');
 
 const DetoxError = require('../src/errors/DetoxError');
-const logger = require('../src/utils/logger').child({ __filename });
+const logger = require('../src/utils/logger').child({ cat: 'cli' });
 
 yargs
   .scriptName('detox')

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/test.js

@@ -9,9 +9,10 @@ module.exports.middlewares = require('./testCommand/middlewares').default;
 
 module.exports.handler = async function test({ detoxArgs, runnerArgs }) {
   try {
-    await detox.globalSetup({
+    await detox.init({
       argv: detoxArgs,
       testRunnerArgv: runnerArgs,
+      workerId: null,
     });
 
     const runnerCommand = new TestRunnerCommand()
@@ -21,6 +22,6 @@ module.exports.handler = async function test({ detoxArgs, runnerArgs }) {
 
     await runnerCommand.execute();
   } finally {
-    await detox.globalTeardown();
+    await detox.cleanup();
   }
 };

package/local-cli/test.test.js

@@ -504,7 +504,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,6 +5,7 @@ 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');
@@ -45,7 +46,7 @@ class TestRunnerCommand {
   }
 
   /**
-   * @param {Partial<Readonly<DetoxInternals.DetoxCLIConfig>>} cliConfig
+   * @param {Partial<Readonly<DetoxInternals.CLIConfig>>} cliConfig
    * @returns {this}
    */
   replicateCLIConfig(cliConfig) {
@@ -88,7 +89,7 @@ class TestRunnerCommand {
       try {
         if (launchError) {
           const list = this._argv._.map((file, index) => `  ${index + 1}. ${file}`).join('\n');
-          detox.log.error({ event: 'RETRY_RUN' },
+          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'
           );
@@ -104,11 +105,13 @@ class TestRunnerCommand {
           throw e;
         }
 
-        this._argv._ = testFilesToRetry.splice(0, Infinity);
-        // @ts-ignore
-        detox.session.testSessionIndex++; // it is always a primary context, so we can update it
+        if (--runsLeft > 0) {
+          this._argv._ = testFilesToRetry.splice(0, Infinity);
+          // @ts-ignore
+          detox.session.testSessionIndex++; // it is always a primary context, so we can update it
+        }
       }
-    } while (launchError && --runsLeft > 0);
+    } while (launchError && runsLeft > 0);
 
     if (launchError) {
       throw launchError;
@@ -119,7 +122,7 @@ class TestRunnerCommand {
     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), {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "detox",
   "description": "E2E tests and automation for mobile",
-  "version": "20.0.4-breaking.new-global-lifecycle.0",
+  "version": "20.0.7-prerelease.0",
   "bin": {
     "detox": "local-cli/cli.js"
   },
@@ -57,13 +57,14 @@
   "dependencies": {
     "ajv": "^8.6.3",
     "bunyan": "^1.8.12",
-    "bunyan-debug-stream": "^3.0.2",
+    "bunyan-debug-stream": "^3.1.0",
     "chalk": "^2.4.2",
     "child-process-promise": "^2.2.0",
     "duplexify": "^4.1.2",
     "find-up": "^4.1.0",
     "fs-extra": "^4.0.2",
     "funpermaproxy": "^1.0.1",
+    "glob": "^8.0.3",
     "ini": "^1.3.4",
     "json-cycle": "^1.3.0",
     "lodash": "^4.17.5",
@@ -83,7 +84,7 @@
     "tail": "^2.0.0",
     "telnet-client": "1.2.8",
     "tempfile": "^2.0.0",
-    "trace-event-lib": "^1.1.0",
+    "trace-event-lib": "^1.3.1",
     "which": "^1.3.1",
     "ws": "^7.0.0",
     "yargs": "^16.0.3",
@@ -183,5 +184,5 @@
       }
     }
   },
-  "gitHead": "5a4d2fa00b359b139d9bda7f5128b9d75cfa838b"
+  "gitHead": "4b75f39310b93707f01e2bb38a4fba4d385e8acd"
 }

package/runners/jest/globalSetup.js

@@ -1 +1 @@
-module.exports = async () => require('../../internals').globalSetup();
+module.exports = async () => require('../../internals').init({ workerId: null });

package/runners/jest/globalTeardown.js

@@ -1 +1 @@
-module.exports = async () => require('../../internals').globalTeardown();
+module.exports = async () => require('../../internals').cleanup();

package/runners/jest/testEnvironment/index.js

@@ -1,9 +1,9 @@
-// @ts-nocheck
-const maybeNodeEnvironment = require('jest-environment-node'); // eslint-disable-line node/no-extraneous-require
+const resolveFrom = require('resolve-from');
+const maybeNodeEnvironment = require(resolveFrom(process.cwd(), 'jest-environment-node'));
+// @ts-ignore
 const NodeEnvironment = maybeNodeEnvironment.default || maybeNodeEnvironment;
 
 const detox = require('../../../internals');
-const { DetoxError } = require('../../../src/errors');
 const Timer = require('../../../src/utils/Timer');
 
 const {
@@ -24,6 +24,8 @@ const SYNC_CIRCUS_EVENTS = new Set([
   'error',
 ]);
 
+const log = detox.log.child({ cat: 'lifecycle,jest-environment' });
+
 /**
  * @see https://www.npmjs.com/package/jest-circus#overview
  */
@@ -41,18 +43,31 @@ class DetoxCircusEnvironment extends NodeEnvironment {
       SpecReporter,
       WorkerAssignReporter,
     };
-    /** @protected */
+    /** @private */
+    this._shouldManageDetox = detox.getStatus() === 'inactive';
+    /** @internal */
     this.testPath = context.testPath;
     /** @protected */
     this.testEventListeners = [];
     /** @protected */
     this.initTimeout = detox.config.testRunner.jest.initTimeout;
+    /** @internal */
+    log.trace.begin(this.testPath);
+
+    this.setup = log.trace.complete.bind(null, 'set up environment', this.setup.bind(this));
+    const _teardown = this.teardown.bind(this);
+    this.teardown = async () => {
+      try {
+        await log.trace.complete('tear down environment', _teardown);
+      } finally {
+        await log.trace.end();
+      }
+    };
   }
 
   /** @override */
   async setup() {
     await super.setup();
-
     await Timer.run({
       description: `setting up Detox environment`,
       timeout: this.initTimeout,
@@ -85,7 +100,7 @@ class DetoxCircusEnvironment extends NodeEnvironment {
         try {
           await this._timer.run(() => listener[name](event, state));
         } catch (listenerError) {
-          this._logError(listenerError);
+          log.error(listenerError);
           break;
         }
       }
@@ -100,9 +115,7 @@ class DetoxCircusEnvironment extends NodeEnvironment {
     await Timer.run({
       description: `tearing down Detox environment`,
       timeout: this.initTimeout,
-      fn: async () => {
-        await this.cleanupDetox();
-      },
+      fn: async () => await this.cleanupDetox(),
     });
   }
 
@@ -115,15 +128,25 @@ class DetoxCircusEnvironment extends NodeEnvironment {
    * @protected
    */
   async initDetox() {
-    await detox.setup({
+    const opts = {
       global: this.global,
-      workerId: +process.env.JEST_WORKER_ID,
-    });
+      workerId: `w${process.env.JEST_WORKER_ID}`,
+    };
+
+    if (this._shouldManageDetox) {
+      await detox.init(opts);
+    } else {
+      await detox.installWorker(opts);
+    }
   }
 
   /** @protected */
   async cleanupDetox() {
-    await detox.teardown();
+    if (this._shouldManageDetox) {
+      await detox.cleanup();
+    } else {
+      await detox.uninstallWorker();
+    }
   }
 
   /** @private */
@@ -145,11 +168,6 @@ class DetoxCircusEnvironment extends NodeEnvironment {
       }));
     }
   }
-
-  /** @private */
-  _logError(e) {
-    detox.log.error(DetoxError.format(e));
-  }
 }
 
 module.exports = DetoxCircusEnvironment;

package/runners/jest/testEnvironment/listeners/DetoxCoreListener.js

@@ -7,6 +7,8 @@ const { getFullTestName, hasTimedOut } = require('../utils');
 
 const RETRY_TIMES = Symbol.for('RETRY_TIMES');
 
+const log = detoxInternals.log.child({ cat: 'lifecycle,jest-environment' });
+
 class DetoxCoreListener {
   constructor({ env }) {
     this._startedTests = new WeakSet();
@@ -15,11 +17,6 @@ class DetoxCoreListener {
     this._testRunTimes = 1;
   }
 
-  _getTestInvocations(test) {
-    const { testSessionIndex } = detoxInternals.session;
-    return testSessionIndex * this._testRunTimes + test.invocations;
-  }
-
   async setup() {
     // Workaround to override Jest's expect
     if (detoxInternals.config.behavior.init.exposeGlobals) {
@@ -27,15 +24,19 @@ class DetoxCoreListener {
     }
   }
 
-  async run_describe_start({ describeBlock: { name, children } }) {
-    if (children.length) {
-      await detoxInternals.onRunDescribeStart({ name });
+  async run_describe_start({ describeBlock }) {
+    if (describeBlock.children.length) {
+      log.trace.begin(describeBlock.parent ? describeBlock.name : 'run the tests');
+      await detoxInternals.onRunDescribeStart({
+        name: describeBlock.name,
+      });
     }
   }
 
-  async run_describe_finish({ describeBlock: { name, children } }) {
-    if (children.length) {
-      await detoxInternals.onRunDescribeFinish({ name });
+  async run_describe_finish({ describeBlock }) {
+    if (describeBlock.children.length) {
+      await detoxInternals.onRunDescribeFinish({ name: describeBlock.name });
+      log.trace.end();
     }
   }
 
@@ -48,61 +49,87 @@ class DetoxCoreListener {
     this._testRunTimes = isNaN(circusRetryTimes) ? 1 : 1 + circusRetryTimes;
   }
 
-  async hook_start(_event, state) {
+  async hook_start(event, state) {
     await this._onBeforeActualTestStart(state.currentlyRunningTest);
+    log.trace.begin({ functionCode: event.hook.fn.toString() }, event.hook.type);
+  }
+
+  async hook_success() {
+    log.trace.end({ success: true });
   }
 
-  async hook_failure({ error, hook }) {
-    await detoxInternals.onHookFailure({
-      error,
-      hook: hook.type,
-    });
+  async hook_failure({ error }) {
+    log.trace.end({ success: false, error });
   }
 
   async test_fn_start({ test }) {
     await this._onBeforeActualTestStart(test);
+    log.trace.begin({ functionCode: test.fn.toString() }, 'test_fn');
   }
 
-  async test_fn_failure({ error }) {
-    await detoxInternals.onTestFnFailure({ error });
+  async test_fn_success() {
+    log.trace.end({ success: true });
   }
 
-  async _onBeforeActualTestStart(test) {
-    if (!test || test.status === 'skip' || this._startedTests.has(test) || this._testsFailedBeforeStart.has(test)) {
-      return;
-    }
-
-    this._startedTests.add(test);
-
-    await detoxInternals.onTestStart({
-      title: test.name,
-      fullName: getFullTestName(test),
-      status: 'running',
-      invocations: this._getTestInvocations(test),
-    });
+  async test_fn_failure({ error }) {
+    await detoxInternals.onTestFnFailure({ error });
+    log.trace.end({ success: false, error });
   }
 
   async test_done({ test }) {
     if (this._startedTests.has(test)) {
-      await detoxInternals.onTestDone({
-        title: test.name,
-        fullName: getFullTestName(test),
-        status: test.errors.length ? 'failed' : 'passed',
-        invocations: this._getTestInvocations(test),
-        timedOut: hasTimedOut(test)
-      });
-
+      const failed = test.errors.length > 0;
+      const metadata = {
+        ...this._getTestMetadata(test),
+        status: failed ? 'failed' : 'passed',
+        timedOut: failed ? hasTimedOut(test) : undefined,
+      };
+
+      await detoxInternals.onTestDone(metadata);
       this._startedTests.delete(test);
+      log.trace.end({
+        status: metadata.status,
+        timedOut: metadata.timedOut,
+      });
     }
   }
 
   async run_finish(_event, state) {
-    if (this._hasFailedTests(state.rootDescribeBlock)) {
+    const hasFailedTests = this._hasFailedTests(state.rootDescribeBlock);
+    if (hasFailedTests) {
       const handledByJestCircus = this._testRunTimes > 1 && !detoxInternals.config.testRunner.jest.retryAfterCircusRetries;
       await detoxInternals.reportFailedTests([this._env.testPath], handledByJestCircus);
     }
   }
 
+  async _onBeforeActualTestStart(test) {
+    if (!test || test.status === 'skip' || this._startedTests.has(test) || this._testsFailedBeforeStart.has(test)) {
+      return false;
+    }
+
+    const metadata = {
+      ...this._getTestMetadata(test),
+      status: 'running',
+    };
+
+    this._startedTests.add(test);
+
+    log.trace.begin({
+      context: 'test',
+      status: metadata.status,
+      fullName: metadata.fullName,
+      invocations: metadata.invocations,
+    }, metadata.title);
+
+    await detoxInternals.onTestStart(metadata);
+    return true;
+  }
+
+  _getTestInvocations(test) {
+    const { testSessionIndex } = detoxInternals.session;
+    return testSessionIndex * this._testRunTimes + test.invocations;
+  }
+
   _hasFailedTests(block) {
     if (block.children) {
       for (const child of block.children) {
@@ -114,6 +141,14 @@ class DetoxCoreListener {
 
     return block.errors ? block.errors.length > 0 : false;
   }
+
+  _getTestMetadata(test) {
+    return {
+      title: test.name,
+      fullName: getFullTestName(test),
+      invocations: this._getTestInvocations(test),
+    };
+  }
 }
 
 module.exports = DetoxCoreListener;

package/runners/jest/testEnvironment/listeners/SpecReporter.js

@@ -118,7 +118,7 @@ class SpecReporter {
     const retriesDescription = (invocations > 1) ? chalk.gray(` [Retry #${invocations - 1}]`) : '';
     const status = chalk.gray(_status ? ` [${_status}]` : '');
     const desc = this._suitesDesc + testDescription + retriesDescription + status;
-    log.info({ event: 'SPEC_STATE_CHANGE' }, desc);
+    log.info({ cat: 'lifecycle' }, desc);
   }
 }
 

package/runners/jest/testEnvironment/listeners/WorkerAssignReporter.js

@@ -13,7 +13,7 @@ class WorkerAssignReporter {
 
   run_start() {
     if (config.testRunner.jest.reportWorkerAssign) {
-      log.info({ event: 'WORKER_ASSIGN' }, `${this._formatTestName()} is assigned to ${this._formatDeviceName()}`);
+      log.info({ cat: 'lifecycle' }, `${this._formatTestName()} is assigned to ${this._formatDeviceName()}`);
     }
   }
 

package/src/DetoxWorker.js

@@ -32,6 +32,8 @@ class DetoxWorker {
       onError: this._onEmitError.bind(this),
     });
 
+    /** @type {string} */
+    this.id = 'worker';
     /** @type {Detox.Device} */
     this.device = null;
     /** @type {Detox.ElementFacade} */
@@ -63,14 +65,15 @@ class DetoxWorker {
       device: deviceConfig,
       session: sessionConfig
     } = this._config;
+
     this._appsConfig = appsConfig;
     this._artifactsConfig = artifactsConfig;
     this._behaviorConfig = behaviorConfig;
     this._deviceConfig = deviceConfig;
     this._sessionConfig = sessionConfig;
+    this._sessionConfig.sessionId = sessionConfig.sessionId || uuid.UUID();
     this._runtimeErrorComposer.appsConfig = this._appsConfig;
 
-    sessionConfig.sessionId = sessionConfig.sessionId || uuid.UUID();
     this._client = new Client(sessionConfig);
     this._client.terminateApp = async () => {
       // @ts-ignore
@@ -192,7 +195,6 @@ class DetoxWorker {
   onTestStart = async (testSummary) => {
     if (this._isCleaningUp) return;
     this._validateTestSummary('beforeEach', testSummary);
-    this._logTestRunCheckpoint('DETOX_BEFORE_EACH', testSummary);
 
     if (this._isCleaningUp) return;
     await this._dumpUnhandledErrorsIfAny({
@@ -212,7 +214,6 @@ class DetoxWorker {
   onTestDone = async (testSummary) => {
     if (this._isCleaningUp) return;
     this._validateTestSummary('afterEach', testSummary);
-    this._logTestRunCheckpoint('DETOX_AFTER_EACH', testSummary);
 
     if (this._isCleaningUp) return;
     await this._artifactsManager.onTestDone(testSummary);
@@ -248,10 +249,6 @@ class DetoxWorker {
     }
   }
 
-  _logTestRunCheckpoint(event, { status, fullName }) {
-    this.log.trace({ event, status }, `${status} test: ${JSON.stringify(fullName)}`);
-  }
-
   _validateTestSummary(methodName, testSummary) {
     if (!_.isPlainObject(testSummary)) {
       throw this._runtimeErrorComposer.invalidTestSummary(methodName, testSummary);