detox 19.9.0 → 21.0.0-breaking.new-global-lifecycle.0

package/runners/jest/testEnvironment/utils/assertJestCircus27.js

@@ -0,0 +1,56 @@
+const fs = require('fs');
+const path = require('path');
+
+const semver = require('semver');
+
+const detoxPackageJson = require('../../../../package.json');
+const { DetoxRuntimeError } = require('../../../../src/errors');
+
+function assertJestCircus27(maybeProjectConfig) {
+  const projectConfig = maybeProjectConfig.projectConfig || maybeProjectConfig;
+
+  if (!/jest-circus/.test(projectConfig.testRunner)) {
+    throw new DetoxRuntimeError({
+      message: 'Cannot continue without Jest Circus test runner underneath, exiting.',
+      hint: 'Make sure that in your Jest config you have no "testRunner" property or it is explicitly set to "jest-circus/runner".',
+      debugInfo: `The test runner powering your configuration is:\n${projectConfig.testRunner}`,
+    });
+  }
+
+  const circusPackageJson = path.join(path.dirname(projectConfig.testRunner), 'package.json');
+  if (!fs.existsSync(circusPackageJson)) {
+    throw new DetoxRuntimeError({
+      message: 'Check that you have an installed copy of "jest-circus" npm package, exiting.',
+      debugInfo: `Its package.json file is missing: ${circusPackageJson}`,
+    });
+  }
+
+  const circusVersion = require(circusPackageJson).version;
+  if (!circusVersion) {
+    throw new DetoxRuntimeError({
+      message: 'Check that you have an valid copy of "jest-circus" npm package, exiting.',
+      debugInfo: `Its package.json file has no "version" property. See:\n` + circusPackageJson,
+    });
+  }
+
+  assertSupportedVersion(circusVersion);
+
+  return maybeProjectConfig;
+}
+
+function assertSupportedVersion(actualVersion) {
+  const supportedRange = detoxPackageJson.peerDependencies.jest;
+  const minSupportedVersion = semver.minVersion(supportedRange);
+
+  if (semver.lt(actualVersion, minSupportedVersion)) {
+    throw new DetoxRuntimeError({
+      message: `Detected an unsupported jest@${actualVersion} version.`,
+      hint: `Please upgrade your Jest test runner to the supported range: ${supportedRange}.`
+    });
+  }
+}
+
+module.exports = {
+  assertJestCircus27,
+  assertSupportedVersion,
+};

package/runners/jest/testEnvironment/utils/assertJestCircus27.test.js

@@ -0,0 +1,23 @@
+const { assertSupportedVersion } = require('./assertJestCircus27');
+
+describe('assertSupportedVersion', () => {
+  test.each([
+    ['27.2.5'],
+    ['27.2.6-prerelease.0'],
+    ['27.3.0'],
+    ['28.0.0-alpha.1'],
+    ['28.0.0'],
+    ['28.1.0'],
+    ['29.0.0-next.0'],
+    ['30.0.0'],
+  ])('should pass for %j', (version) => {
+    expect(() => assertSupportedVersion(version)).not.toThrow();
+  });
+
+  test.each([
+    ['26.0.0'],
+    ['27.2.4'],
+  ])('should throw an error for %j', (version) => {
+    expect(() => assertSupportedVersion(version)).toThrowError(/unsupported jest.*version/);
+  });
+});

package/runners/jest-circus/environment/index.js

@@ -0,0 +1,6 @@
+const path = require('path');
+
+module.exports = require('../../migration')(
+  __filename,
+  path.join(__dirname, '../../jest/testEnvironment/index.js')
+);

package/runners/jest-circus/index.js

@@ -1,10 +1 @@
-const SpecReporterCircus = require('../jest/SpecReporterCircus');
-const WorkerAssignReporterCircus = require('../jest/WorkerAssignReporterCircus');
-
-const DetoxCircusEnvironment = require('./environment');
-
-module.exports = {
-  DetoxCircusEnvironment,
-  SpecReporter: SpecReporterCircus,
-  WorkerAssignReporter: WorkerAssignReporterCircus,
-};
+module.exports = require('../migration')(__filename);

package/runners/jest-circus/reporter.js

@@ -0,0 +1 @@
+module.exports = require('../migration')(__filename);

package/runners/migration.js

@@ -0,0 +1,37 @@
+const path = require('path');
+
+const chalk = require('chalk');
+const _ = require('lodash');
+
+const SEARCH_VALUE = ['', 'detox', 'runners', 'jest-circus', ''].join(path.sep);
+const REPLACE_VALUE = ['', 'detox', 'runners', 'jest', ''].join(path.sep);
+
+function jsify(pathToFile) {
+  return 'detox/' + path
+    .relative(
+      path.join(__dirname, '..'),
+      pathToFile
+    )
+    .replace(/\\/g, '/')
+    .replace(/(?:\/index)?\.js$/, '');
+}
+
+const redirectWithWarning = _.memoize((
+  oldPath,
+  newPath = oldPath.replace(SEARCH_VALUE, REPLACE_VALUE)
+) => {
+  redirectWithWarning._log([
+    '[DEPRECATION] Detox detected an attempt to require a module from an outdated location, please change in your project:',
+    `- ${jsify(oldPath)}`,
+    `+ ${jsify(newPath)}`,
+    '',
+  ].join('\n'));
+
+  return require(newPath);
+});
+
+// @ts-ignore
+// istanbul ignore next
+redirectWithWarning._log = msg => process.stderr.write(chalk.yellow(msg) + '\n');
+
+module.exports = redirectWithWarning;

package/runners/mocha/DetoxMochaAdapter.js

@@ -1,35 +1,3 @@
-class DetoxMochaAdapter {
-  constructor(detox) {
-    this.detox = detox;
-  }
-
-  async beforeEach(context) {
-    await this.detox.beforeEach({
-      title: context.currentTest.title,
-      fullName: context.currentTest.fullTitle(),
-      status: this._mapStatus(context, false),
-    });
-  }
-
-  async afterEach(context) {
-    await this.detox.afterEach({
-      title: context.currentTest.title,
-      fullName: context.currentTest.fullTitle(),
-      status: this._mapStatus(context, true),
-      timedOut: context.currentTest.timedOut,
-    });
-  }
-
-  _mapStatus(context, isAfterTest) {
-    switch (context.currentTest.state) {
-      case 'passed':
-        return 'passed';
-      case 'failed':
-        return 'failed';
-      default:
-        return isAfterTest ? 'failed' : 'running';
-    }
-  }
-}
-
-module.exports = DetoxMochaAdapter;
+/** @deprecated */
+/** @type {never} */
+module.exports = require('../deprecation');

package/runners/mocha/adapter.d.ts

@@ -1,9 +1,6 @@
-interface DetoxMochaAdapter {
-    detox: Detox.DetoxExportWrapper;
-    beforeEach: (context: any) => Promise<void>;
-    afterEach: (context: any) => Promise<void>;
-}
-
-declare const adapter: DetoxMochaAdapter;
+/**
+ * @deprecated Mocha integration is no longer supported since Detox v20.0.0
+ */
+declare const adapter: never;
 
 export = adapter;

package/runners/mocha/adapter.js

@@ -1,5 +1,3 @@
-const detox = require('../../src/index');
-
-const DetoxMochaAdapter = require('./DetoxMochaAdapter');
-
-module.exports = new DetoxMochaAdapter(detox);
+/** @deprecated */
+/** @type {never} */
+module.exports = require('../deprecation');

package/src/{Detox.js → DetoxWorker.js}

@@ -1,60 +1,20 @@
-// @ts-nocheck
-const { URL } = require('url');
-const util = require('util');
-
 const _ = require('lodash');
 
-const lifecycleSymbols = require('../runners/integration').lifecycle;
-
 const Client = require('./client/Client');
 const environmentFactory = require('./environmentFactory');
 const { DetoxRuntimeErrorComposer } = require('./errors');
 const { InvocationManager } = require('./invoke');
-const DetoxServer = require('./server/DetoxServer');
+const symbols = require('./symbols');
 const AsyncEmitter = require('./utils/AsyncEmitter');
-const Deferred = require('./utils/Deferred');
-const MissingDetox = require('./utils/MissingDetox');
-const logger = require('./utils/logger');
-const log = logger.child({ __filename });
-
-const _initHandle = Symbol('_initHandle');
-const _assertNoPendingInit = Symbol('_assertNoPendingInit');
-
-class Detox {
-  constructor(config) {
-    log.trace(
-      { event: 'DETOX_CREATE', config },
-      'created a Detox instance with config:\n%s',
-      util.inspect(_.omit(config, ['errorComposer']), {
-        getters: false,
-        depth: Infinity,
-        maxArrayLength: Infinity,
-        maxStringLength: Infinity,
-        breakLength: false,
-        compact: false,
-      })
-    );
-
-    this[_initHandle] = null;
-
-    for (const [key, symbol] of Object.entries(lifecycleSymbols)) {
-      this[symbol] = (...args) => this._artifactsManager[key](...args);
-    }
-
-    this[lifecycleSymbols.onTestStart] = this.beforeEach;
-    this[lifecycleSymbols.onTestDone] = this.afterEach;
-
-    const { appsConfig, artifactsConfig, behaviorConfig, deviceConfig, sessionConfig } = config;
-
-    this._appsConfig = appsConfig;
-    this._artifactsConfig = artifactsConfig;
-    this._behaviorConfig = behaviorConfig;
-    this._deviceConfig = deviceConfig;
-    this._sessionConfig = sessionConfig;
-    this._runtimeErrorComposer = new DetoxRuntimeErrorComposer({ appsConfig });
-
+const uuid = require('./utils/uuid');
+
+class DetoxWorker {
+  constructor(context) {
+    this._context = context;
+    this._isCleaningUp = false;
+    this._config = context[symbols.config];
+    this._runtimeErrorComposer = new DetoxRuntimeErrorComposer(this._config);
     this._client = null;
-    this._server = null;
     this._artifactsManager = null;
     this._eventEmitter = new AsyncEmitter({
       events: [
@@ -72,116 +32,67 @@ class Detox {
       onError: this._onEmitError.bind(this),
     });
 
+    /** @type {Detox.Device} */
     this.device = null;
-    this._deviceAllocator = null;
-    this._deviceCookie = null;
-  }
-
-  init() {
-    if (!this[_initHandle]) {
-      this[_initHandle] = new Deferred();
-
-      const { resolve, reject } = this[_initHandle];
-      this._doInit().then(resolve, reject);
-    }
-
-    return this[_initHandle].promise;
-  }
-
-  async cleanup() {
-    await this[_assertNoPendingInit]().catch(_.noop);
-
-    if (this._artifactsManager) {
-      await this._artifactsManager.onBeforeCleanup();
-      this._artifactsManager = null;
-    }
-
-    if (this._client) {
-      this._client.dumpPendingRequests();
-      await this._client.cleanup();
-      this._client = null;
-    }
-
-    if (this.device) {
-      const shutdown = this._behaviorConfig.cleanup.shutdownDevice;
-      await this.device._cleanup();
-      await this._deviceAllocator.free(this._deviceCookie, { shutdown });
-    }
-
-    if (this._server) {
-      await this._server.close();
-      this._server = null;
-    }
+    /** @type {Detox.ElementFacade} */
+    this.element = null;
+    /** @type {Detox.WaitForFacade} */
+    this.waitFor = null;
+    /** @type {Detox.ExpectFacade} */
+    this.expect = null;
+    /** @type {Detox.ByFacade} */
+    this.by = null;
+    /** @type {Detox.WebFacade} */
+    this.web = null;
 
     this._deviceAllocator = null;
     this._deviceCookie = null;
-    this.device = null;
-  }
-
-  async beforeEach(testSummary) {
-    await this[_assertNoPendingInit]();
 
-    this._validateTestSummary('beforeEach', testSummary);
-    this._logTestRunCheckpoint('DETOX_BEFORE_EACH', testSummary);
-    await this._dumpUnhandledErrorsIfAny({
-      pendingRequests: false,
-      testName: testSummary.fullName,
-    });
-    await this._artifactsManager.onTestStart(testSummary);
-  }
-
-  async afterEach(testSummary) {
-    await this[_assertNoPendingInit]();
-
-    this._validateTestSummary('afterEach', testSummary);
-    this._logTestRunCheckpoint('DETOX_AFTER_EACH', testSummary);
-    await this._artifactsManager.onTestDone(testSummary);
-    await this._dumpUnhandledErrorsIfAny({
-      pendingRequests: testSummary.timedOut,
-      testName: testSummary.fullName,
-    });
+    this.trace = this._context.trace;
+    /** @deprecated */
+    this.traceCall = this._context.traceCall;
   }
 
-  async _doInit() {
-    const behaviorConfig = this._behaviorConfig.init;
-    const sessionConfig = this._sessionConfig;
+  async init() {
+    if (this._isCleaningUp) return;
 
-    if (sessionConfig.autoStart) {
-      this._server = new DetoxServer({
-        port: sessionConfig.server
-          ? new URL(sessionConfig.server).port
-          : 0,
-        standalone: false,
-      });
-
-      await this._server.open();
-
-      if (!sessionConfig.server) {
-        sessionConfig.server = `ws://localhost:${this._server.port}`;
-      }
-    }
+    const { appsConfig, artifactsConfig, behaviorConfig, deviceConfig, sessionConfig } = this._config;
+    this._appsConfig = appsConfig;
+    this._artifactsConfig = artifactsConfig;
+    this._behaviorConfig = behaviorConfig;
+    this._deviceConfig = deviceConfig;
+    this._sessionConfig = sessionConfig;
+    this._runtimeErrorComposer.appsConfig = this._appsConfig;
 
+    sessionConfig.sessionId = sessionConfig.sessionId || uuid.UUID();
     this._client = new Client(sessionConfig);
     this._client.terminateApp = async () => {
+      // @ts-ignore
       if (this.device && this.device._isAppRunning()) {
         await this.device.terminateApp();
       }
     };
 
     await this._client.connect();
+    if (this._isCleaningUp) return;
 
     const invocationManager = new InvocationManager(this._client);
 
     const {
+      // @ts-ignore
       envValidatorFactory,
       deviceAllocatorFactory,
+      // @ts-ignore
       artifactsManagerFactory,
+      // @ts-ignore
       matchersFactory,
+      // @ts-ignore
       runtimeDeviceFactory,
     } = environmentFactory.createFactories(this._deviceConfig);
 
     const envValidator = envValidatorFactory.createValidator();
     await envValidator.validate();
+    if (this._isCleaningUp) return;
 
     const commonDeps = {
       invocationManager,
@@ -191,9 +102,9 @@ class Detox {
     };
 
     this._artifactsManager = artifactsManagerFactory.createArtifactsManager(this._artifactsConfig, commonDeps);
-
     this._deviceAllocator = deviceAllocatorFactory.createDeviceAllocator(commonDeps);
     this._deviceCookie = await this._deviceAllocator.allocate(this._deviceConfig);
+    if (this._isCleaningUp) return;
 
     this.device = runtimeDeviceFactory.createRuntimeDevice(
       this._deviceCookie,
@@ -204,7 +115,7 @@ class Detox {
         deviceConfig: this._deviceConfig,
         sessionConfig,
       });
-    await this.device._prepare();
+    if (this._isCleaningUp) return;
 
     const matchers = matchersFactory.createMatchers({
       invocationManager,
@@ -213,34 +124,102 @@ class Detox {
     });
     Object.assign(this, matchers);
 
-    if (behaviorConfig.exposeGlobals) {
-      Object.assign(Detox.global, {
+    if (behaviorConfig.init.exposeGlobals) {
+      Object.assign(DetoxWorker.global, {
         ...matchers,
         device: this.device,
+        detox: this,
       });
     }
 
+    // @ts-ignore
     await this.device.installUtilBinaries();
-    if (behaviorConfig.reinstallApp) {
+    if (this._isCleaningUp) return;
+
+    if (behaviorConfig.init.reinstallApp) {
       await this._reinstallAppsOnDevice();
+      if (this._isCleaningUp) return;
+    }
+
+    const appAliases = Object.keys(this._appsConfig);
+    if (appAliases.length === 1) {
+      await this.device.selectApp(appAliases[0]);
+    } else {
+      await this.device.selectApp(null);
     }
 
     return this;
   }
 
-  [_assertNoPendingInit]() {
-    const handle = this[_initHandle];
-    if (!handle) {
-      return Promise.resolve();
+  async cleanup() {
+    this._isCleaningUp = true;
+
+    if (this._artifactsManager) {
+      await this._artifactsManager.onBeforeCleanup();
+      this._artifactsManager = null;
     }
 
-    if (handle.status === Deferred.PENDING) {
-      handle.reject(this._runtimeErrorComposer.abortedDetoxInit());
+    if (this._client) {
+      this._client.dumpPendingRequests();
+      await this._client.cleanup();
+      this._client = null;
     }
 
-    return handle.promise;
+    if (this.device) {
+      const shutdown = this._behaviorConfig ? this._behaviorConfig.cleanup.shutdownDevice : false;
+      // @ts-ignore
+      await this.device._cleanup();
+      await this._deviceAllocator.free(this._deviceCookie, { shutdown });
+    }
+
+    this._deviceAllocator = null;
+    this._deviceCookie = null;
+    this.device = null;
+  }
+
+  get log() {
+    return this._context.log;
   }
 
+  onRunStart = async (...args) => this._artifactsManager.onRunStart(...args);
+  onRunDescribeStart = async (...args) => this._artifactsManager.onRunDescribeStart(...args);
+  onTestStart = async (testSummary) => {
+    if (this._isCleaningUp) return;
+    this._validateTestSummary('beforeEach', testSummary);
+    this._logTestRunCheckpoint('DETOX_BEFORE_EACH', testSummary);
+
+    if (this._isCleaningUp) return;
+    await this._dumpUnhandledErrorsIfAny({
+      pendingRequests: false,
+      testName: testSummary.fullName,
+    });
+
+    if (this._isCleaningUp) return;
+    await this._artifactsManager.onTestStart(testSummary);
+  };
+  onHookStart = async (...args) => this._artifactsManager.onHookStart(...args);
+  onHookFailure = async (...args) => this._artifactsManager.onHookFailure(...args);
+  onHookSuccess = async (...args) => this._artifactsManager.onHookSuccess(...args);
+  onTestFnStart = async (...args) => this._artifactsManager.onTestFnStart(...args);
+  onTestFnFailure = async (...args) => this._artifactsManager.onTestFnFailure(...args);
+  onTestFnSuccess = async (...args) => this._artifactsManager.onTestFnSuccess(...args);
+  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);
+
+    if (this._isCleaningUp) return;
+    await this._dumpUnhandledErrorsIfAny({
+      pendingRequests: testSummary.timedOut,
+      testName: testSummary.fullName,
+    });
+  };
+  onRunDescribeFinish = async (...args) => this._artifactsManager.onRunDescribeFinish(...args);
+  onRunFinish = async (...args) => this._artifactsManager.onRunFinish(...args);
+
   async _reinstallAppsOnDevice() {
     const appNames = _(this._appsConfig)
       .map((config, key) => [key, `${config.binaryPath}:${config.testBinaryPath}`])
@@ -250,21 +229,21 @@ class Detox {
 
     for (const appName of appNames) {
       await this.device.selectApp(appName);
+      if (this._isCleaningUp) return;
       await this.device.uninstallApp();
+      if (this._isCleaningUp) return;
     }
 
     for (const appName of appNames) {
       await this.device.selectApp(appName);
+      if (this._isCleaningUp) return;
       await this.device.installApp();
-    }
-
-    if (appNames.length !== 1) {
-      await this.device.selectApp(null);
+      if (this._isCleaningUp) return;
     }
   }
 
   _logTestRunCheckpoint(event, { status, fullName }) {
-    log.trace({ event, status }, `${status} test: ${JSON.stringify(fullName)}`);
+    this.log.trace({ event, status }, `${status} test: ${JSON.stringify(fullName)}`);
   }
 
   _validateTestSummary(methodName, testSummary) {
@@ -289,29 +268,17 @@ class Detox {
   }
 
   _onEmitError({ error, eventName, eventObj }) {
-    log.error(
+    this.log.error(
       { event: 'EMIT_ERROR', fn: eventName },
       `Caught an exception in: emitter.emit("${eventName}", ${JSON.stringify(eventObj)})\n\n`,
       error
     );
   }
-
-  static async globalInit(configs) {
-    const handler = await environmentFactory.createGlobalLifecycleHandler(configs.deviceConfig);
-    if (handler) {
-      await handler.globalInit();
-    }
-  }
-
-  static async globalCleanup(configs) {
-    const handler = await environmentFactory.createGlobalLifecycleHandler(configs.deviceConfig);
-    if (handler) {
-      await handler.globalCleanup();
-    }
-  }
 }
 
-Detox.none = new MissingDetox();
-Detox.global = global;
+/**
+ * @type {NodeJS.Global}
+ */
+DetoxWorker.global = global;
 
-module.exports = Detox;
+module.exports = DetoxWorker;