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

package/src/logger/DetoxLogger.js

@@ -0,0 +1,244 @@
+const path = require('path');
+const { PassThrough } = require('stream');
+
+const bunyan = require('bunyan');
+const bunyanDebugStream = require('bunyan-debug-stream');
+const _ = require('lodash');
+
+const temporaryPath = require('../artifacts/utils/temporaryPath');
+const { DetoxInternalError } = require('../errors');
+const { shortFormat } = require('../utils/dateUtils');
+
+const customConsoleLogger = require('./customConsoleLogger');
+
+/**
+ * @typedef PrivateLoggerConfig
+ * @property {string} [file]
+ */
+
+class DetoxLogger {
+  /**
+   * @param {Detox.DetoxLoggerConfig & PrivateLoggerConfig} [config]
+   * @param {object} [context]
+   * @param {bunyan} [bunyanLogger]
+   */
+  constructor(config, context, bunyanLogger) {
+    // IMPORTANT: all the loggers should share the same object instance of this._config
+    this._config = config || {
+      level: 'info',
+      overrideConsole: 'none',
+      options: {
+        showDate: true,
+        showLoggerName: true,
+        showPid: true,
+        showMetadata: false,
+      },
+    };
+
+    if (config && !context) {
+      this._config.file = temporaryPath.for.jsonl();
+    }
+
+    /** @type {object | undefined} */
+    this._context = context;
+    /** @type {bunyan} */
+    this._bunyan = bunyanLogger || this._initBunyanLogger();
+
+    this.fatal = this._forward.bind(this, 'fatal');
+    this.error = this._forward.bind(this, 'error');
+    this.warn = this._forward.bind(this, 'warn');
+    this.info = this._forward.bind(this, 'info');
+    this.debug = this._forward.bind(this, 'debug');
+    this.trace = this._forward.bind(this, 'trace');
+
+    this.overrideConsole();
+  }
+
+  /**
+   * @internal
+   */
+  get config() {
+    return this._config;
+  }
+
+  /** @returns {Detox.DetoxLogLevel} */
+  get level() {
+    return this._config.level;
+  }
+
+  /**
+   * @internal
+   */
+  get file() {
+    return this._config.file;
+  }
+
+  /**
+   * @param config
+   */
+  async setConfig(config) {
+    if (this._context !== undefined) {
+      throw new DetoxInternalError('Trying to set a config for a non-root logger');
+    }
+
+    if (this.file) {
+      throw new DetoxInternalError('Trying to set a config for a fully initialized logger');
+    }
+
+    _.merge(this._config, config);
+
+    // @ts-ignore
+    const [oldStream] = this._bunyan.streams.splice(0, 1);
+    oldStream.stream.end();
+    this._bunyan.addStream(this._createDebugStream());
+
+    this._config.file = temporaryPath.for.jsonl();
+    this._bunyan.addStream({
+      level: 'trace',
+      path: this._config.file,
+    });
+
+    this.overrideConsole();
+  }
+
+  /**
+   * @param {object} [overrides]
+   * @returns {DetoxLogger}
+   */
+  child(overrides) {
+    if (overrides && overrides.__filename) {
+      overrides.__filename = path.basename(overrides.__filename, '.js');
+    }
+
+    return new DetoxLogger(this._config, {
+      ...this._context,
+      ...overrides,
+    }, this._bunyan);
+  }
+
+  /**
+   * @param {bunyan.LogLevel} level
+   * @param {any[]} args
+   * @private
+   */
+  _forward(level, ...args) {
+    const msgContext = _.isError(args[0]) ? { err: args[0] } : _.isObject(args[0]) ? args[0] : undefined;
+    const msgArgs = msgContext !== undefined ? args.slice(1) : args;
+    const mergedContext = sanitizeBunyanContext({
+      ...this._context,
+      ...msgContext,
+    });
+
+    this._bunyan[level](mergedContext, ...msgArgs);
+  }
+
+  _initBunyanLogger() {
+    /** @type {bunyan.Stream[]} */
+    const streams = [this._createDebugStream()];
+
+    if (this._config.file) {
+      streams.push({
+        level: 'trace',
+        path: this._config.file,
+      });
+    }
+
+    return bunyan.createLogger({ name: 'detox', streams });
+  }
+
+  _createDebugStream() {
+    const { out = process.stderr, ...streamOptions } = this._config.options;
+    const passthrough = new PassThrough().pipe(out);
+
+    return {
+      type: 'raw',
+      level: this._config.level,
+      stream: bunyanDebugStream.default({
+        ...streamOptions,
+        out: passthrough,
+      }),
+    };
+  }
+
+  overrideConsole(sandbox) {
+    const option = this._config.overrideConsole;
+    if (option === 'none') {
+      return;
+    }
+
+    if ((option === 'sandbox' && sandbox) || option === 'all') {
+      customConsoleLogger.overrideConsoleMethods((sandbox || global).console, this);
+    }
+  }
+
+  /** @type {bunyanDebugStream.BunyanDebugStreamOptions} */
+  static defaultOptions = {
+    showDate: shortFormat,
+    showLoggerName: true,
+    showPid: true,
+    showMetadata: false,
+    basepath: path.join(__dirname, '..'),
+    prefixers: {
+      '__filename': (filename, { entry }) => {
+        if (entry.event === 'USER_LOG') {
+          return '';
+        }
+
+        if (entry.event === 'ERROR') {
+          return `${filename}/${entry.event}`;
+        }
+
+        return entry.event ? entry.event : filename;
+      },
+      'trackingId': id => ` #${id}`,
+      'cpid': pid => ` cpid=${pid}`,
+    },
+  };
+
+  /**
+   * @param {string} level
+   * @returns {Detox.DetoxLogLevel}
+   */
+  static castLevel(level) {
+    switch (level) {
+      case 'fatal':
+      case 'error':
+      case 'warn':
+      case 'info':
+      case 'debug':
+      case 'trace':
+        return level;
+      case 'verbose':
+        return 'debug';
+      default:
+        return 'info';
+    }
+  }
+}
+
+const RESERVED_PROPERTIES = [
+  'hostname',
+  'level',
+  'msg',
+  'name',
+  'pid',
+  'time',
+];
+
+function hasProperty(p) {
+  return _.has(this, p);
+}
+
+function hasReservedProperties(o) {
+  return RESERVED_PROPERTIES.some(hasProperty, o); // eslint-disable-line unicorn/no-array-method-this-argument
+}
+
+function escapeCallback(value, key) {
+  return RESERVED_PROPERTIES.includes(key) ? `${key}$` : key;
+}
+
+function sanitizeBunyanContext(context) {
+  return hasReservedProperties(context) ? _.mapKeys(context, escapeCallback) : context;
+}
+
+module.exports = DetoxLogger;

package/src/logger/DetoxTraceEventBuilder.js

@@ -0,0 +1,21 @@
+const { AbstractEventBuilder } = require('trace-event-lib');
+
+class DetoxTraceEventBuilder extends AbstractEventBuilder {
+  constructor(forward) {
+    super();
+
+    this._forward = forward;
+  }
+
+  send(event) {
+    // eslint-disable-next-line no-unused-vars, @typescript-eslint/no-unused-vars
+    const { pid, ts, name, args = {}, ...trace } = event;
+    if (trace.ph === 'E') {
+      this._forward({ ...args, trace }, `end`);
+    } else {
+      this._forward({ ...args, trace }, name);
+    }
+  }
+}
+
+module.exports = DetoxTraceEventBuilder;

package/src/logger/DetoxTracer.js

@@ -0,0 +1,133 @@
+const _ = require('lodash');
+
+const isPromise = require('../utils/isPromise');
+
+const DetoxTraceEventBuilder = require('./DetoxTraceEventBuilder');
+const TraceThreadDispatcher = require('./TraceThreadDispatcher');
+
+class DetoxTracer {
+  /**
+   * @param {object} options
+   * @param {Detox.Logger} options.logger
+   */
+  constructor({ logger }) {
+    this.logger = logger;
+    this.builder = new DetoxTraceEventBuilder(this.logger.trace);
+    this.categories = {};
+    this.defaultEventDispatcher = new TraceThreadDispatcher({
+      logger,
+      name: 'Default',
+      min: 10000,
+    });
+    this.eventDispatchers = { '': this.defaultEventDispatcher };
+  }
+
+  /**
+   * @param {Detox.TraceEvent | string} eventOrName
+   * @param {Detox.TraceEvent['args']} [args]
+   * @returns {import('trace-event-lib').EndHandle<Detox.TraceEvent>}
+   */
+  begin(eventOrName, args) {
+    const event = typeof eventOrName === 'string' ? { name: eventOrName, args } : eventOrName;
+    const mainCategory = event.cat ? event.cat.split(',', 1)[0] : '';
+    const dispatcher = this.eventDispatchers[mainCategory] || this.defaultEventDispatcher;
+    const tid = dispatcher.begin(event.id);
+
+    return this.builder.begin({
+      args: event.args,
+      cat: event.cat || '',
+      cname: event.cname,
+      name: event.name,
+      tid,
+    });
+  }
+
+  end(eventOrName, args) {
+    const event = typeof eventOrName === 'string' ? { name: eventOrName, args } : eventOrName || {};
+    const mainCategory = event.cat ? event.cat.split(',', 1)[0] : '';
+    const dispatcher = this.eventDispatchers[mainCategory] || this.defaultEventDispatcher;
+    const tid = dispatcher.end(event.id);
+
+    this.builder.end({
+      args: event.args,
+      cname: event.cname,
+      tid,
+    });
+  }
+
+  section(sectionName, func) {
+    let result;
+
+    this.begin(sectionName);
+    try {
+      result = func();
+      if (!isPromise(result)) {
+        this.end(sectionName, { success: true });
+      } else {
+        result.then(
+          () => this.end(sectionName, { success: true }),
+          (err) => this.end(sectionName, { success: false, err }),
+        );
+      }
+    } catch (err) {
+      this.end(sectionName, { success: false, err });
+      throw err;
+    }
+
+    return result;
+  }
+
+  registerThreads(event, [min, max]) {
+    this.eventDispatchers[event] = new TraceThreadDispatcher({
+      logger: this.logger,
+      name: event,
+      min,
+      max,
+    });
+
+    return this;
+  }
+
+  static default(options) {
+    const tracer = new DetoxTracer(options);
+    for (const [key, range] of Object.entries(this.CATEGORIES)) {
+      tracer.registerThreads(key, range);
+    }
+
+    return Object.assign(
+      tracer.section.bind(tracer),
+      {
+        begin: tracer.begin.bind(tracer),
+        startSection: tracer.begin.bind(tracer),
+        end: tracer.end.bind(tracer),
+        endSection: tracer.end.bind(tracer),
+      });
+  }
+
+  static categorize(tid) {
+    return _.findKey(this.CATEGORIES, ([min, max]) => min <= tid && tid <= max) || 'user';
+  }
+
+  static threadize(cat) {
+    const [mainCategory] = cat ? cat.split(',', 1) : 'user';
+    const threads = _.find(this.CATEGORIES, (_, key) => key === mainCategory);
+    return threads ? threads[0] : 10000;
+  }
+
+  /**
+   * @type {Record<string, [number, number]>}
+   */
+  static CATEGORIES = {
+    'lifecycle': [0, 0],
+    'ipc': [29, 29],
+    'ws-server': [50, 99],
+    'ws-client': [100, 149],
+    'device': [150, 159],
+    'artifacts-manager': [300, 300],
+    'artifact-plugin': [310, 349],
+    'artifact': [350, 399],
+    'child-process': [400, 499],
+  };
+}
+
+module.exports = DetoxTracer;

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.globalTeardown].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;