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

package/src/logger/TraceThreadDispatcher.js

@@ -0,0 +1,52 @@
+const isUndefined = (x) => x === undefined;
+
+class TraceThreadDispatcher {
+  /**
+   * @param {object} options
+   * @param {Detox.Logger} options.logger
+   * @param {string} options.name
+   * @param {number} options.min
+   * @param {number} [options.max]
+   */
+  constructor({ logger, name, min, max = Infinity }) {
+    this.logger = logger;
+    this.name = name;
+    this.min = min;
+    this.max = max;
+    this.stacks = [];
+    this.threads = [];
+  }
+
+  begin(id = 0) {
+    const tid = this._findTID(id);
+    this.threads[tid] = id;
+    this.stacks[tid] = (this.stacks[tid] || 0) + 1;
+    return this._transpose(tid);
+  }
+
+  end(id = 0) {
+    const tid = this._findTID(id);
+    if (this.stacks[tid] && --this.stacks[tid] === 0) {
+      delete this.threads[tid];
+    }
+    return this._transpose(tid);
+  }
+
+  _findTID(id) {
+    let tid = this.threads.indexOf(id);
+    if (tid === -1) {
+      tid = this.threads.findIndex(isUndefined);
+    }
+    return tid === -1 ? this.threads.length : tid;
+  }
+
+  _transpose(id) {
+    const result = this.min + id;
+    if (result > this.max) {
+      this.logger.warn({ event: 'THREAD_DISPATCHER' }, `${this.name} trace thread dispatcher has run out of available thread IDs: ${this.min}..${this.max}`);
+    }
+    return Math.min(result, this.max);
+  }
+}
+
+module.exports = TraceThreadDispatcher;

package/src/{utils → logger}/customConsoleLogger.js

@@ -1,6 +1,6 @@
 const util = require('util');
 
-const callsites = require('./callsites');
+const callsites = require('../utils/callsites');
 
 const USER_STACK_FRAME_INDEX = 2;
 

package/src/realms/DetoxConstants.js

@@ -0,0 +1,13 @@
+module.exports = Object.freeze({
+  userNotificationTriggers: {
+    push: 'push',
+    calendar: 'calendar',
+    timeInterval: 'timeInterval',
+    location: 'location'
+  },
+  userActivityTypes: {
+    searchableItem: 'com.apple.corespotlightitem',
+    browsingWeb: 'NSUserActivityTypeBrowsingWeb',
+  },
+  searchableItemActivityIdentifier: 'kCSSearchableItemActivityIdentifier'
+});

package/src/realms/DetoxContext.js

@@ -0,0 +1,170 @@
+const funpermaproxy = require('funpermaproxy');
+
+const { DetoxRuntimeError } = require('../errors');
+const DetoxLogger = require('../logger/DetoxLogger');
+const DetoxTracer = require('../logger/DetoxTracer');
+const symbols = require('../symbols');
+
+const DetoxConstants = require('./DetoxConstants');
+
+const $cleanup = Symbol('cleanup');
+const $logger = Symbol('logger');
+const $restoreSessionState = Symbol('restoreSessionState');
+const $sessionState = Symbol('restoreSessionState');
+const $tracer = Symbol('tracer');
+
+const _worker = Symbol('worker');
+
+class DetoxContext {
+  constructor() {
+    this[symbols.globalSetup] = this[symbols.globalSetup].bind(this);
+    this[symbols.globalTeardown] = this[symbols.globalTeardown].bind(this);
+    this[symbols.reportFailedTests] = this[symbols.reportFailedTests].bind(this);
+    this[symbols.resolveConfig] = this[symbols.resolveConfig].bind(this);
+    this[symbols.setup] = this[symbols.setup].bind(this);
+    this[symbols.teardown] = this[symbols.teardown].bind(this);
+
+    this[$sessionState] = this[$restoreSessionState]();
+
+    const loggerConfig = this[$sessionState].detoxConfig
+      ? this[$sessionState].detoxConfig.loggerConfig
+      : undefined;
+
+    /**
+     * @protected
+     * @type {DetoxLogger & Detox.Logger}
+     */
+    this[$logger] = new DetoxLogger(loggerConfig);
+    /** @protected */
+    this[$tracer] = DetoxTracer.default({
+      logger: this[$logger],
+    });
+    /** @deprecated */
+    this.traceCall = this[$tracer].bind(this[$tracer]);
+    /** @type {import('../DetoxWorker') | null} */
+    this[_worker] = null;
+  }
+
+  //#region Public members
+  device = funpermaproxy(() => this[symbols.worker].device);
+
+  element = funpermaproxy.callable(() => this[symbols.worker].element);
+
+  waitFor = funpermaproxy.callable(() => this[symbols.worker].waitFor);
+
+  expect = funpermaproxy.callable(() => this[symbols.worker].expect);
+
+  by = funpermaproxy(() => this[symbols.worker].by);
+
+  web = funpermaproxy.callable(() => this[symbols.worker].web);
+
+  get DetoxConstants() {
+    return DetoxConstants;
+  }
+
+  /**
+   * @returns {Detox.Logger}
+   */
+  get log() {
+    return this[$logger];
+  }
+
+  /**
+   * @returns {Detox.Tracer}
+   */
+  get trace() {
+    return this[$tracer];
+  }
+  //#endregion
+
+  //#region Internal members
+  [symbols.onRunStart] = (...args) => this[symbols.worker].onRunStart(...args);
+  [symbols.onRunDescribeStart] = (...args) => this[symbols.worker].onRunDescribeStart(...args);
+  [symbols.onTestStart] = (...args) => this[symbols.worker].onTestStart(...args);
+  [symbols.onHookStart] = (...args) => this[symbols.worker].onHookStart(...args);
+  [symbols.onHookFailure] = (...args) => this[symbols.worker].onHookFailure(...args);
+  [symbols.onHookSuccess] = (...args) => this[symbols.worker].onHookSuccess(...args);
+  [symbols.onTestFnStart] = (...args) => this[symbols.worker].onTestFnStart(...args);
+  [symbols.onTestFnFailure] = (...args) => this[symbols.worker].onTestFnFailure(...args);
+  [symbols.onTestFnSuccess] = (...args) => this[symbols.worker].onTestFnSuccess(...args);
+  [symbols.onTestDone] = (...args) => this[symbols.worker].onTestDone(...args);
+  [symbols.onRunDescribeFinish] = (...args) => this[symbols.worker].onRunDescribeFinish(...args);
+  [symbols.onRunFinish] = (...args) => this[symbols.worker].onRunFinish(...args);
+  [symbols.config] = funpermaproxy(() => this[symbols.session].detoxConfig);
+  [symbols.session] = funpermaproxy(() => this[$sessionState]);
+  /** @abstract */
+  [symbols.reportFailedTests](_testFilePaths) {}
+  /**
+   * @abstract
+   * @param {Partial<DetoxInternals.DetoxGlobalSetupOptions>} _opts
+   * @returns {Promise<DetoxInternals.RuntimeConfig>}
+   */
+  async [symbols.resolveConfig](_opts) { return null; }
+
+  get [symbols.worker]() {
+    if (!this[_worker]) {
+      throw new DetoxRuntimeError({
+        message: `Detox worker instance has not been initialized in this context (${this.constructor.name}).`,
+        hint: DetoxRuntimeError.reportIssueIfJest + '\n' + 'Otherwise, make sure you call detox.setup() beforehand.',
+      });
+    }
+
+    return this[_worker];
+  }
+
+  /**
+   * @abstract
+   * @param {Partial<DetoxInternals.DetoxGlobalSetupOptions>} [_opts]
+   * @returns {Promise<void>}
+   */
+  async [symbols.globalSetup](_opts = {}) {}
+
+  /**
+   * @param {Partial<DetoxInternals.DetoxConfigurationSetupOptions>} [opts]
+   */
+  async [symbols.setup](opts) {
+    const theGlobal = opts.global || global;
+    theGlobal['__detox__'] = this;
+    this[$logger].overrideConsole(theGlobal);
+
+    const DetoxWorker = require('../DetoxWorker');
+    DetoxWorker.global = theGlobal;
+    this[_worker] = new DetoxWorker(this);
+    await this[_worker].init();
+  }
+
+  async [symbols.teardown]() {
+    try {
+      if (this[_worker]) {
+        await this[_worker].cleanup();
+      }
+    } finally {
+      this[_worker] = null;
+    }
+  }
+
+  /**
+   * @abstract
+   */
+  async [symbols.globalTeardown]() {}
+  //#endregion
+
+  //#region Protected members
+  /**
+   * @abstract
+   * @protected
+   */
+  [$restoreSessionState]() {
+    return null;
+  }
+  //#endregion
+}
+
+module.exports = DetoxContext;
+module.exports.protected = {
+  $cleanup,
+  $logger,
+  $restoreSessionState,
+  $sessionState,
+  $tracer,
+};

package/src/realms/DetoxInternalsFacade.js

@@ -0,0 +1,35 @@
+const funpermaproxy = require('funpermaproxy');
+
+const symbols = require('../symbols');
+
+class DetoxInternalsFacade {
+  /**
+   * @param context
+   */
+  constructor(context) {
+    this.config = context[symbols.config];
+    this.globalSetup = context[symbols.globalSetup];
+    this.globalTeardown = context[symbols.globalTeardown];
+    this.log = context.log;
+    this.setup = context[symbols.setup];
+    this.teardown = context[symbols.teardown];
+    this.onHookFailure = context[symbols.onHookFailure];
+    this.onHookStart = context[symbols.onHookStart];
+    this.onHookSuccess = context[symbols.onHookSuccess];
+    this.onRunDescribeFinish = context[symbols.onRunDescribeFinish];
+    this.onRunDescribeStart = context[symbols.onRunDescribeStart];
+    this.onRunFinish = context[symbols.onRunFinish];
+    this.onRunStart = context[symbols.onRunStart];
+    this.onTestDone = context[symbols.onTestDone];
+    this.onTestFnFailure = context[symbols.onTestFnFailure];
+    this.onTestFnStart = context[symbols.onTestFnStart];
+    this.onTestFnSuccess = context[symbols.onTestFnSuccess];
+    this.onTestStart = context[symbols.onTestStart];
+    this.reportFailedTests = context[symbols.reportFailedTests];
+    this.resolveConfig = context[symbols.resolveConfig];
+    this.session = context[symbols.session];
+    this.worker = funpermaproxy(() => context[symbols.worker]);
+  }
+}
+
+module.exports = DetoxInternalsFacade;

package/src/realms/DetoxPrimaryContext.js

@@ -0,0 +1,229 @@
+const path = require('path');
+const { URL } = require('url');
+
+const fs = require('fs-extra');
+const pipe = require('multipipe');
+
+const temporary = require('../artifacts/utils/temporaryPath');
+const { DetoxRuntimeError } = require('../errors');
+const { PrimarySessionState } = require('../ipc/state');
+const symbols = require('../symbols');
+
+const DetoxContext = require('./DetoxContext');
+
+const { $logger, $restoreSessionState, $sessionState } = DetoxContext.protected;
+
+const _finalizeLogs = Symbol('finalizeLogs');
+const _globalLifecycleHandler = Symbol('globalLifecycleHandler');
+const _ipcServer = Symbol('ipcServer');
+const _resetLockFile = Symbol('resetLockFile');
+const _wss = Symbol('wss');
+const _dirty = Symbol('dirty');
+
+class DetoxPrimaryContext extends DetoxContext {
+  constructor() {
+    super();
+
+    this[_dirty] = false;
+    this[_wss] = null;
+    this[_globalLifecycleHandler] = null;
+    /**
+     * @type {import('../ipc/IPCServer') | null}
+     */
+    this[_ipcServer] = null;
+  }
+
+  //#region Internal members
+  async [symbols.reportFailedTests](testFilePaths) {
+    if (this[_ipcServer]) {
+      this[_ipcServer].onFailedTests({ testFilePaths });
+    }
+  }
+
+  async [symbols.resolveConfig](opts = {}) {
+    const session = this[symbols.session];
+    if (!session.detoxConfig) {
+      const configuration = require('../configuration');
+      session.detoxConfig = await configuration.composeDetoxConfig(opts);
+    }
+
+    return session.detoxConfig;
+  }
+
+  /**
+   * @override
+   * @param {Partial<DetoxInternals.DetoxGlobalSetupOptions>} [opts]
+   */
+  async [symbols.globalSetup](opts) {
+    if (this[_dirty]) {
+      throw new DetoxRuntimeError({
+        message: 'Cannot initialize primary Detox context more than once.',
+        hint: DetoxRuntimeError.reportIssueIfJest,
+      });
+    }
+
+    this[_dirty] = true;
+    const detoxConfig = await this[symbols.resolveConfig](opts);
+
+    const { behaviorConfig, deviceConfig, loggerConfig, sessionConfig } = detoxConfig;
+    await this[$logger].setConfig(loggerConfig);
+
+    this.trace.begin({
+      cat: 'lifecycle',
+      args: this[$sessionState],
+      name: process.argv.slice(1).join(' '),
+    });
+
+    const IPCServer = require('../ipc/IPCServer');
+    this[_ipcServer] = new IPCServer({
+      sessionState: this[$sessionState],
+      logger: this[$logger],
+    });
+
+    await this[_ipcServer].init();
+
+    const environmentFactory = require('../environmentFactory');
+    this[_globalLifecycleHandler] = await environmentFactory.createGlobalLifecycleHandler(deviceConfig);
+
+    if (this[_globalLifecycleHandler]) {
+      await this[_globalLifecycleHandler].globalInit();
+    }
+
+    if (!behaviorConfig.init.keepLockFile) {
+      await this[_resetLockFile]();
+    }
+
+    const DetoxServer = require('../server/DetoxServer');
+    if (sessionConfig.autoStart) {
+      this[_wss] = new DetoxServer({
+        port: sessionConfig.server
+          ? new URL(sessionConfig.server).port
+          : 0,
+        standalone: false,
+      });
+
+      await this[_wss].open();
+    }
+
+    if (!sessionConfig.server && this[_wss]) {
+      sessionConfig.server = `ws://localhost:${this[_wss].port}`;
+    }
+
+    await fs.writeFile(this[$sessionState].detoxConfigSnapshotPath, this[$sessionState].stringify());
+    process.env.DETOX_CONFIG_SNAPSHOT_PATH = this[$sessionState].detoxConfigSnapshotPath;
+
+    // TODO: think about signal-exit and cleaning up the logs
+  }
+
+  /**
+   * @override
+   * @param {Partial<DetoxInternals.DetoxConfigurationSetupOptions>} [opts]
+   */
+  async [symbols.setup](opts) {
+    const workerId = opts.workerId || 1;
+    this[$sessionState].workerId = workerId;
+    this[_ipcServer].onRegisterWorker({ workerId });
+    await super[symbols.setup](opts);
+  }
+
+  /** @override */
+  async [symbols.globalTeardown]() {
+    if (this[_globalLifecycleHandler]) {
+      await this[_globalLifecycleHandler].globalCleanup();
+      this[_globalLifecycleHandler] = null;
+    }
+
+    if (this[_wss]) {
+      await this[_wss].close();
+      this[_wss] = null;
+    }
+
+    if (this[_ipcServer]) {
+      await this[_ipcServer].dispose();
+      this[_ipcServer] = null;
+    }
+
+    await fs.remove(this[$sessionState].detoxConfigSnapshotPath);
+    delete process.env.DETOX_CONFIG_SNAPSHOT_PATH;
+
+    try {
+      this.trace.end({ cat: 'lifecycle' });
+      await this[_finalizeLogs]();
+    } catch (err) {
+      this[$logger].error({ err }, 'Encountered an error while merging the process logs:');
+    }
+  }
+  //#endregion
+
+  //#region Protected members
+  /**
+   * @protected
+   * @override
+   * @return {PrimarySessionState}
+   */
+  [$restoreSessionState]() {
+    return new PrimarySessionState({
+      detoxConfigSnapshotPath: temporary.for.json(),
+      detoxIPCServer: `primary-${process.pid}`,
+    });
+  }
+  //#endregion
+
+  //#region Private members
+  async[_finalizeLogs]() {
+    const logs = [this[$logger].file, ...this[$sessionState].logFiles].filter(f => f && fs.existsSync(f));
+    if (logs.length === 0) {
+      return;
+    }
+
+    const streamUtils = require('../utils/streamUtils');
+    const { rootDir, plugins } = this[symbols.config].artifactsConfig || {};
+    const logConfig = plugins && plugins.log || 'none';
+    const enabled = rootDir && (typeof logConfig === 'string' ? logConfig !== 'none' : logConfig.enabled);
+
+    if (enabled) {
+      await fs.mkdirp(rootDir);
+      const [out1Stream, out2Stream, out3Stream] = ['detox.log.jsonl', 'detox.log', 'detox.trace.json']
+        .map((filename) => fs.createWriteStream(path.join(rootDir, filename)));
+
+      const mergedStream = streamUtils
+        .mergeSortedJSONL(
+          logs.map(filePath => fs.createReadStream(filePath).pipe(streamUtils.readJSONL()))
+        );
+
+      await Promise.all([
+        pipe(mergedStream, streamUtils.writeJSONL(), out1Stream),
+        pipe(mergedStream, streamUtils.debugStream(this[$logger].config.options), out2Stream),
+        pipe(mergedStream, streamUtils.chromeTraceStream(), streamUtils.writeJSON(), out3Stream),
+      ]);
+    }
+
+    await Promise.all(logs.map(filepath => fs.remove(filepath)));
+  }
+
+  async[_resetLockFile]() {
+    const DeviceRegistry = require('../devices/DeviceRegistry');
+
+    const deviceType = this[symbols.config].deviceConfig.type;
+
+    switch (deviceType) {
+      case 'ios.none':
+      case 'ios.simulator':
+        await DeviceRegistry.forIOS().reset();
+        break;
+      case 'android.attached':
+      case 'android.emulator':
+      case 'android.genycloud':
+        await DeviceRegistry.forAndroid().reset();
+        break;
+    }
+
+    if (deviceType === 'android.genycloud') {
+      const GenyDeviceRegistryFactory = require('../devices/allocation/drivers/android/genycloud/GenyDeviceRegistryFactory');
+      await GenyDeviceRegistryFactory.forGlobalShutdown().reset();
+    }
+  }
+  //#endregion
+}
+
+module.exports = DetoxPrimaryContext;

package/src/realms/DetoxSecondaryContext.js

@@ -0,0 +1,94 @@
+const fs = require('fs');
+
+const { DetoxInternalError } = require('../errors');
+const { SecondarySessionState } = require('../ipc/state');
+const symbols = require('../symbols');
+
+const DetoxContext = require('./DetoxContext');
+
+const { $logger, $restoreSessionState, $sessionState } = DetoxContext.protected;
+const _ipcClient = Symbol('ipcClient');
+
+class DetoxSecondaryContext extends DetoxContext {
+  constructor() {
+    super();
+
+    /**
+     * @protected
+     * @type {*}
+     */
+    this[_ipcClient] = null;
+  }
+
+  //#region Internal members
+  async [symbols.reportFailedTests](testFilePaths) {
+    if (this[_ipcClient]) {
+      await this[_ipcClient].reportFailedTests(testFilePaths);
+    } else {
+      throw new DetoxInternalError('Detected an attempt to report failed tests using a non-initialized context.');
+    }
+  }
+
+  async [symbols.resolveConfig]() {
+    return this[symbols.config];
+  }
+
+  /** @override */
+  async [symbols.globalSetup](_opts = {}) {
+    // This is a no-op function.
+    // It is forbidden to add any logic to `globalSetup` of the secondary context.
+    // Violating this principle will almost definitely break some flows, where it is
+    // not guaranteed that `globalSetup` will ever get called. See UML diagrams.
+  }
+
+  /** @override */
+  async [symbols.globalTeardown]() {
+    // This is a no-op function.
+    // It is forbidden to add any logic to `globalTeardown` of the secondary context.
+    // Violating this principle will almost definitely break some flows, where it is
+    // not guaranteed that `globalTeardown` will ever get called. See UML diagrams.
+  }
+
+  /** @override */
+  async [symbols.setup](opts) {
+    const IPCClient = require('../ipc/IPCClient');
+
+    this[_ipcClient] = new IPCClient({
+      id: `secondary-${process.pid}`,
+      state: this[$sessionState],
+      logger: this[$logger],
+    });
+
+    const workerId = opts.workerId || 1;
+    await this[_ipcClient].init();
+    await this[_ipcClient].registerWorker(workerId);
+    await super[symbols.setup](opts);
+  }
+
+  /** @override */
+  async [symbols.teardown]() {
+    try {
+      await super[symbols.teardown]();
+    } finally {
+      if (this[_ipcClient]) {
+        await this[_ipcClient].dispose();
+        this[_ipcClient] = null;
+      }
+    }
+  }
+  //#endregion
+
+  //#region Protected members
+
+  /**
+   * @protected
+   * @override
+   * @return {SecondarySessionState}
+   */
+  [$restoreSessionState]() {
+    return SecondarySessionState.parse(fs.readFileSync(process.env.DETOX_CONFIG_SNAPSHOT_PATH));
+  }
+  //#endregion
+}
+
+module.exports = DetoxSecondaryContext;

package/src/realms/index.js

@@ -0,0 +1,10 @@
+function current() {
+  if (process.env.DETOX_CONFIG_SNAPSHOT_PATH) {
+    return require('./secondary');
+  } else {
+    return require('./primary');
+  }
+}
+
+/** @type {DetoxInternals.Facade} */
+module.exports = global['__detox__'] || current();

package/src/realms/primary.js

@@ -0,0 +1,3 @@
+const DetoxPrimaryContext = require('./DetoxPrimaryContext');
+
+module.exports = new DetoxPrimaryContext();

package/src/realms/secondary.js

@@ -0,0 +1,3 @@
+const DetoxSecondaryContext = require('./DetoxSecondaryContext');
+
+module.exports = new DetoxSecondaryContext();

package/src/server/DetoxConnection.js

@@ -3,7 +3,7 @@ const _ = require('lodash');
 const { WebSocket } = require('ws'); // eslint-disable-line @typescript-eslint/no-unused-vars, no-unused-vars
 
 const DetoxRuntimeError = require('../errors/DetoxRuntimeError');
-const logger = require('../utils/logger').child({ __filename });
+const logger = require('../utils/logger').child({ __filename, cat: 'ws-server,ws' });
 
 const AnonymousConnectionHandler = require('./handlers/AnonymousConnectionHandler');
 

package/src/symbols.js

@@ -0,0 +1,56 @@
+/**
+ * @type {{
+ *   readonly config: unique symbol;
+ *   readonly globalSetup: unique symbol;
+ *   readonly globalTeardown: unique symbol;
+ *   readonly onHookFailure: unique symbol;
+ *   readonly onHookStart: unique symbol;
+ *   readonly onHookSuccess: unique symbol;
+ *   readonly onRunDescribeFinish: unique symbol;
+ *   readonly onRunDescribeStart: unique symbol;
+ *   readonly onRunFinish: unique symbol;
+ *   readonly onRunStart: unique symbol;
+ *   readonly onTestDone: unique symbol;
+ *   readonly onTestFnFailure: unique symbol;
+ *   readonly onTestFnStart: unique symbol;
+ *   readonly onTestFnSuccess: unique symbol;
+ *   readonly onTestStart: unique symbol;
+ *   readonly reportFailedTests: unique symbol;
+ *   readonly resolveConfig: unique symbol;
+ *   readonly session: unique symbol;
+ *   readonly setup: unique symbol;
+ *   readonly teardown: unique symbol;
+ *   readonly worker: unique symbol;
+ * }}
+ */
+module.exports = {
+  //#region Lifecycle
+  onRunStart: Symbol('run_start'),
+  onRunDescribeStart: Symbol('run_describe_start'),
+  onTestStart: Symbol('test_start'),
+  onHookStart: Symbol('hook_start'),
+  onHookFailure: Symbol('hook_failure'),
+  onHookSuccess: Symbol('hook_success'),
+  onTestFnStart: Symbol('test_fn_start'),
+  onTestFnFailure: Symbol('test_fn_failure'),
+  onTestFnSuccess: Symbol('test_fn_success'),
+  onTestDone: Symbol('test_done'),
+  onRunDescribeFinish: Symbol('run_describe_finish'),
+  onRunFinish: Symbol('run_finish'),
+  //#endregion
+
+  //#region IPC
+  reportFailedTests: Symbol('reportFailedTests'),
+  //#endregion
+
+  //#region Main
+  config: Symbol('config'),
+  globalSetup: Symbol('globalSetup'),
+  globalTeardown: Symbol('globalTeardown'),
+  resolveConfig: Symbol('resolveConfig'),
+  session: Symbol('session'),
+  setup: Symbol('setup'),
+  teardown: Symbol('teardown'),
+  worker: Symbol('worker'),
+  //#endregion
+};