detox 19.13.0 → 20.0.0

package/runners/jest/JestCircusEnvironment.js

@@ -1,38 +1,3 @@
-const maybeNodeEnvironment = require('jest-environment-node'); // eslint-disable-line node/no-extraneous-require
-// @ts-ignore
-const NodeEnvironment = maybeNodeEnvironment.default || maybeNodeEnvironment;
-
-/**
- * @see https://www.npmjs.com/package/jest-circus#overview
- */
-class JestCircusEnvironment extends NodeEnvironment {
-  constructor(config) {
-    super(config);
-    this.testEventListeners = [];
-
-    // Enable access to this instance (single in each worker's scope) by exposing a get-function.
-    // Note: whatever's set into this.global will be exported in that way. The reason behind it is that
-    // each suite is run inside a sandboxed JS context which scope is in fact this specific instance. See
-    // NodeEnvironment's constructor for more info, or https://jestjs.io/docs/en/configuration#testenvironment-string
-    // for additional ref.
-    this.global.detoxCircus = {
-      getEnv: () => this,
-    };
-  }
-
-  addEventsListener(listener) {
-    this.testEventListeners.push(listener);
-  }
-
-  async handleTestEvent(event, state) {
-    const name = event.name;
-
-    for (const listener of this.testEventListeners) {
-      if (typeof listener[name] === 'function') {
-        await listener[name](event, state);
-      }
-    }
-  }
-}
-
-module.exports = JestCircusEnvironment;
+/** @deprecated */
+/** @type {never} */
+module.exports = require('../deprecation');

package/runners/jest/adapter.d.ts

@@ -1,12 +1,6 @@
-interface DetoxJestAdapter extends Detox.CircusTestEventListenerBase {
-    detox: Detox.DetoxExportWrapper;
-    beforeEach: () => Promise<void>;
-    afterAll: () => Promise<void>;
-    // These are not publicly used, but are defined in order to overlap with the jasmine.CustomReporter interface (which is a weak interface)
-    specDone: () => void;
-    specStarted: () => void;
-}
-
-declare const adapter: DetoxJestAdapter;
+/***
+ * @deprecated Detox does not support old Jest integrations since v20.0.0
+ */
+declare const adapter: never;
 
 export = adapter;

package/runners/jest/adapter.js

@@ -1,6 +1,3 @@
-const detox = require('../../src/index');
-
-const runnerInfo = require('./runnerInfo');
-const DetoxAdapter = runnerInfo.isJestCircus ? require('./DetoxAdapterCircus') : require('./DetoxAdapterJasmine');
-
-module.exports = new DetoxAdapter(detox);
+/** @deprecated */
+/** @type {never} */
+module.exports = require('../deprecation');

package/runners/jest/assignReporter.d.ts

@@ -1,3 +1,6 @@
-declare const assignReporter: Detox.CircusTestEventListenerBase;
+/***
+ * @deprecated Detox does not support old Jest integrations since v20.0.0
+ */
+declare const assignReporter: never;
 
 export = assignReporter;

package/runners/jest/assignReporter.js

@@ -1,6 +1,3 @@
-const detox = require('../../src/index');
-
-const runnerInfo = require('./runnerInfo');
-
-const Reporter = runnerInfo.isJestCircus ? require('./WorkerAssignReporterCircus') : require('./WorkerAssignReporterJasmine');
-module.exports = new Reporter({ detox });
+/** @deprecated */
+/** @type {never} */
+module.exports = require('../deprecation');

package/runners/jest/globalSetup.js

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

package/runners/jest/globalTeardown.js

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

package/runners/jest/index.d.ts

@@ -0,0 +1,60 @@
+declare module 'detox/runners/jest' {
+  import type NodeEnvironment from 'jest-environment-node';
+
+  export function globalSetup(): Promise<void>;
+  export function globalTeardown(): Promise<void>;
+
+  export type DetoxCircusListenerConstructorOpts = {
+    readonly env: DetoxCircusEnvironment;
+  }
+
+  /**
+   * @example
+   * class CustomListener implements DetoxCircusListener {
+   *   constructor(opts: DetoxCircusListenerConstructorOpts) {
+   *     console.log('Current test path is:', opts.env.testPath);
+   *   }
+   * }
+   */
+  export interface DetoxCircusListener {
+    start_describe_definition?(event: unknown, state: unknown): void;
+    finish_describe_definition?(event: unknown, state: unknown): void;
+    add_hook?(event: unknown, state: unknown): void;
+    add_test?(event: unknown, state: unknown): void;
+    error?(event: unknown, state: unknown): void;
+
+    setup?(event: unknown, state: unknown): void | Promise<void>;
+    include_test_location_in_result?(event: unknown, state: unknown): void | Promise<void>;
+    hook_start?(event: unknown, state: unknown): void | Promise<void>;
+    hook_success?(event: unknown, state: unknown): void | Promise<void>;
+    hook_failure?(event: unknown, state: unknown): void | Promise<void>;
+    test_fn_start?(event: unknown, state: unknown): void | Promise<void>;
+    test_fn_success?(event: unknown, state: unknown): void | Promise<void>;
+    test_fn_failure?(event: unknown, state: unknown): void | Promise<void>;
+    test_retry?(event: unknown, state: unknown): void | Promise<void>;
+    test_start?(event: unknown, state: unknown): void | Promise<void>;
+    test_skip?(event: unknown, state: unknown): void | Promise<void>;
+    test_todo?(event: unknown, state: unknown): void | Promise<void>;
+    test_done?(event: unknown, state: unknown): void | Promise<void>;
+    run_describe_start?(event: unknown, state: unknown): void | Promise<void>;
+    run_describe_finish?(event: unknown, state: unknown): void | Promise<void>;
+    run_start?(event: unknown, state: unknown): void | Promise<void>;
+    run_finish?(event: unknown, state: unknown): void | Promise<void>;
+    teardown?(event: unknown, state: unknown): void | Promise<void>;
+  }
+
+  export interface DetoxListenerFactory {
+    new (opts: DetoxCircusListenerConstructorOpts): DetoxCircusListener;
+  }
+
+  export class DetoxCircusEnvironment extends NodeEnvironment {
+    public readonly handleTestEvent: (event: unknown, state: unknown) => void | Promise<void>;
+    public readonly testPath: string;
+
+    protected registerListeners(map: Record<string, DetoxListenerFactory>): void;
+    protected setupTimeout: number;
+    protected teardownTimeout: number;
+    protected initDetox(): Promise<DetoxInternals.Worker>;
+    protected cleanupDetox(): Promise<void>;
+  }
+}

package/runners/jest/index.js

@@ -0,0 +1,16 @@
+// Lazy require() is used to avoid initializing a bare Detox context when it is not needed.
+// At the moment, this safety measure is not really needed, but it's better to be on the safe side.
+
+module.exports = {
+  get DetoxCircusEnvironment() {
+    return require('./testEnvironment');
+  },
+
+  get globalSetup() {
+    return require('./globalSetup');
+  },
+
+  get globalTeardown() {
+    return require('./globalTeardown');
+  },
+};

package/runners/jest/index.test.js

@@ -0,0 +1,13 @@
+describe('detox/runners/jest', () => {
+  it('should lazily require the exported modules', () => {
+    const index = require('./index');
+
+    jest.mock('./testEnvironment', () => 0);
+    jest.mock('./globalSetup', () => 1);
+    jest.mock('./globalTeardown', () => 2);
+
+    expect(index.DetoxCircusEnvironment).toBe(0);
+    expect(index.globalSetup).toBe(1);
+    expect(index.globalTeardown).toBe(2);
+  });
+});

package/runners/jest/reporter.js

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

package/runners/jest/reporters/DetoxReporter.js

@@ -0,0 +1,36 @@
+const resolveFrom = require('resolve-from');
+/** @type {typeof import('@jest/reporters').VerboseReporter} */
+const JestVerboseReporter = require(resolveFrom(process.cwd(), '@jest/reporters')).VerboseReporter;
+
+const { config, reportTestResults } = require('../../../internals');
+
+class DetoxReporter extends JestVerboseReporter {
+  /**
+   * @param {import('@jest/test-result').AggregatedResult} results
+   */
+  // @ts-ignore
+  async onRunComplete(_contexts, results) {
+    // @ts-ignore
+    await super.onRunComplete(_contexts, results);
+
+    await reportTestResults(results.testResults.map(r => ({
+      success: !r.failureMessage,
+      testFilePath: r.testFilePath,
+      testExecError: r.testExecError,
+      isPermanentFailure: this._isPermanentFailure(r),
+    })));
+  }
+
+  /**
+   * @param {import('@jest/test-result').TestResult} testResult
+   */
+  _isPermanentFailure(testResult) {
+    if (config.testRunner.jest.retryAfterCircusRetries) {
+      return false;
+    }
+
+    return testResult.testResults.some(r => r.status === 'failed' && r.invocations > 1);
+  }
+}
+
+module.exports = DetoxReporter;

package/runners/jest/specReporter.d.ts

@@ -1,11 +1,6 @@
-interface SpecReporter extends Detox.CircusTestEventListenerBase {
-    // These are not publicly used, but are defined in order to overlap with the jasmine.CustomReporter interface (which is a weak interface)
-    suiteStarted: () => void;
-    suiteDone: () => void;
-    specDone: () => void;
-    specStarted: () => void;
-}
-
-declare const specReporter: SpecReporter;
+/***
+ * @deprecated Detox does not support old Jest integrations since v20.0.0
+ */
+declare const specReporter: never;
 
 export = specReporter;

package/runners/jest/specReporter.js

@@ -1,10 +1,3 @@
-const argparse = require('../../src/utils/argparse');
-
-const runnerInfo = require('./runnerInfo');
-
-if (argparse.getArgValue('reportSpecs') === 'true') {
-  const Reporter = runnerInfo.isJestCircus ? require('./SpecReporterCircus') : require('./SpecReporterJasmine');
-  module.exports = new Reporter();
-} else {
-  module.exports = {};
-}
+/** @deprecated */
+/** @type {never} */
+module.exports = require('../deprecation');

package/runners/jest/streamlineReporter.js

@@ -1,22 +1,3 @@
-// @ts-nocheck
-/*
- * This is here to make it easier for users to apply this reporter in config.json (naming-wise)
- * TODO: rename this file to reporter.js in the next major version (Detox 18)
- */
-
-const DetoxStreamlineJestReporter = require('./DetoxStreamlineJestReporter');
-const FailingTestsReporter = require('./FailingTestsReporter');
-
-class DetoxReporter extends DetoxStreamlineJestReporter {
-  constructor(globalConfig) {
-    super(globalConfig);
-    this._failingTestsReporter = new FailingTestsReporter();
-  }
-
-  async onRunComplete(contexts, results) {
-    await super.onRunComplete(contexts, results);
-    await this._failingTestsReporter.onRunComplete(contexts, results);
-  }
-}
-
-module.exports = DetoxReporter;
+/** @deprecated */
+/** @type {never} */
+module.exports = require('../deprecation');

package/runners/jest/testEnvironment/index.js

@@ -0,0 +1,205 @@
+const path = require('path');
+
+const resolveFrom = require('resolve-from');
+const maybeNodeEnvironment = require(resolveFrom(process.cwd(), 'jest-environment-node'));
+/** @type {typeof import('@jest/environment').JestEnvironment} */
+const NodeEnvironment = maybeNodeEnvironment.default || maybeNodeEnvironment;
+
+const detox = require('../../../internals');
+const Timer = require('../../../src/utils/Timer');
+
+const {
+  DetoxCoreListener,
+  DetoxInitErrorListener,
+  DetoxPlatformFilterListener,
+  SpecReporter,
+  WorkerAssignReporter
+} = require('./listeners');
+const assertExistingContext = require('./utils/assertExistingContext');
+const { assertJestCircus27 } = require('./utils/assertJestCircus27');
+
+const SYNC_CIRCUS_EVENTS = new Set([
+  'start_describe_definition',
+  'finish_describe_definition',
+  'add_hook',
+  'add_test',
+  'error',
+]);
+
+const log = detox.log.child({ cat: 'lifecycle,jest-environment' });
+
+/**
+ * @see https://www.npmjs.com/package/jest-circus#overview
+ */
+class DetoxCircusEnvironment extends NodeEnvironment {
+  constructor(config, context) {
+    super(assertJestCircus27(config), assertExistingContext(context));
+
+    /** @private */
+    this._shouldManageDetox = detox.getStatus() === 'inactive';
+    /** @private */
+    this._timer = new Timer();
+
+    /** @internal */
+    this.testPath = path.relative(process.cwd(), context.testPath);
+    /** @protected */
+    this.testEventListeners = [];
+    /** @protected */
+    this.setupTimeout = detox.config.testRunner.jest.setupTimeout;
+    /** @protected */
+    this.teardownTimeout = detox.config.testRunner.jest.teardownTimeout;
+
+    log.trace.begin(this.testPath);
+
+    this.setup = this._wrapSetup(this.setup);
+    this.teardown = this._wrapTeardown(this.teardown);
+
+    this.registerListeners({
+      DetoxInitErrorListener,
+      DetoxPlatformFilterListener,
+      DetoxCoreListener,
+      SpecReporter,
+      WorkerAssignReporter,
+    });
+  }
+
+  /** @override */
+  async setup() {
+    await super.setup();
+    await this.initDetox();
+  }
+
+  handleTestEvent = async (event, state) => {
+    this._timer.schedule(state.testTimeout != null ? state.testTimeout : this.setupTimeout);
+
+    if (SYNC_CIRCUS_EVENTS.has(event.name)) {
+      this._handleTestEventSync(event, state);
+    } else {
+      await this._handleTestEventAsync(event, state);
+    }
+  };
+
+  /** @override */
+  async teardown() {
+    try {
+      await this.cleanupDetox();
+    } finally {
+      await super.teardown();
+    }
+  }
+
+  /** @protected */
+  registerListeners(map) {
+    for (const Listener of Object.values(map)) {
+      this.testEventListeners.push(new Listener({
+        env: this,
+      }));
+    }
+  }
+
+  /**
+   * @protected
+   */
+  async initDetox() {
+    const opts = {
+      global: this.global,
+      workerId: `w${process.env.JEST_WORKER_ID}`,
+    };
+
+    if (this._shouldManageDetox) {
+      await detox.init(opts);
+    } else {
+      await detox.installWorker(opts);
+    }
+
+    return detox.worker;
+  }
+
+  /** @protected */
+  async cleanupDetox() {
+    if (this._shouldManageDetox) {
+      await detox.cleanup();
+    } else {
+      await detox.uninstallWorker();
+    }
+  }
+
+  /** @private */
+  _handleTestEventSync(event, state) {
+    const { name } = event;
+
+    for (const listener of this.testEventListeners) {
+      if (typeof listener[name] === 'function') {
+        listener[name](event, state);
+      }
+    }
+  }
+
+  /** @private */
+  async _handleTestEventAsync(event, state = null) {
+    const description = `handling ${state ? 'jest-circus' : 'jest-environment'} "${event.name}" event`;
+
+    for (const listener of this.testEventListeners) {
+      if (typeof listener[event.name] !== 'function') {
+        continue;
+      }
+
+      try {
+        await this._timer.run(description, () => listener[event.name](event, state));
+      } catch (listenerError) {
+        log.error(listenerError);
+        if (this._timer.expired) {
+          break;
+        }
+      }
+    }
+  }
+
+  _wrapSetup(fn) {
+    const _setup = fn.bind(this);
+
+    return async () => {
+      await log.trace.complete('set up environment', async () => {
+        try {
+          this._timer.schedule(this.setupTimeout);
+          await this._handleTestEventAsync({ name: 'environment_setup_start' });
+          await this._timer.run(`setting up Detox environment`, _setup);
+          await this._handleTestEventAsync({ name: 'environment_setup_success' });
+        } catch (error) {
+          this._timer.schedule(this.teardownTimeout);
+          await this._handleTestEventAsync({ name: 'environment_setup_failure', error });
+          throw error;
+        } finally {
+          this._timer.clear();
+        }
+      });
+    };
+  }
+
+  _wrapTeardown(fn) {
+    const _teardown = fn.bind(this);
+
+    return async () => {
+      await log.trace.complete('tear down environment', async () => {
+        try {
+          this._timer.schedule(this.teardownTimeout);
+          await this._handleTestEventAsync({ name: 'environment_teardown_start' });
+          await this._timer.run(`tearing down Detox environment`, _teardown);
+          await this._handleTestEventAsync({ name: 'environment_teardown_success' });
+        } catch (error) {
+          if (this._timer.expired) {
+            this._timer.schedule(this.teardownTimeout);
+          }
+
+          await this._handleTestEventAsync({ name: 'environment_teardown_failure', error });
+          throw error;
+        } finally {
+          this._timer.clear();
+          log.trace.end();
+        }
+      });
+    };
+  }
+}
+
+module.exports = DetoxCircusEnvironment;

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

@@ -0,0 +1,166 @@
+// @ts-nocheck
+const _ = require('lodash');
+
+const detox = require('../../../..');
+const detoxInternals = require('../../../../internals');
+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 Set();
+    this._testsFailedBeforeStart = new Set();
+    this._env = env;
+    this._circusRetryTimes = 1;
+  }
+
+  async setup() {
+    // Workaround to override Jest's expect
+    if (detoxInternals.config.behavior.init.exposeGlobals) {
+      this._env.global.expect = detox.expect;
+    }
+  }
+
+  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 }) {
+    if (describeBlock.children.length) {
+      await detoxInternals.onRunDescribeFinish({ name: describeBlock.name });
+      log.trace.end();
+    }
+  }
+
+  async test_start({ test }) {
+    const metadata = this._getTestMetadata(test);
+    if (metadata.status === 'failed') {
+      this._testsFailedBeforeStart.add(test);
+    }
+
+    const logTrace = this._isTestSkipped(test)
+      ? log.trace
+      : log.trace.begin;
+
+    logTrace({
+      context: 'test',
+      status: metadata.status,
+      fullName: metadata.fullName,
+      invocations: metadata.invocations,
+    }, metadata.title);
+
+    const circusRetryTimes = +this._env.global[RETRY_TIMES];
+    this._circusRetryTimes = isNaN(circusRetryTimes) ? 1 : 1 + circusRetryTimes;
+  }
+
+  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,
+    });
+
+    log.trace.end({ success: false, error });
+  }
+
+  async test_fn_start({ test }) {
+    await this._onBeforeActualTestStart(test);
+
+    if (!this._testsFailedBeforeStart.has(test)) {
+      // Jest bug workaround: beforeAll hook errors result into an unterminated test_fn_start event.
+      log.trace.begin({ functionCode: test.fn.toString() }, 'test_fn');
+    }
+  }
+
+  async test_fn_success() {
+    log.trace.end({ success: true });
+  }
+
+  async test_fn_failure({ error }) {
+    await detoxInternals.onTestFnFailure({ error });
+    log.trace.end({ success: false, error });
+  }
+
+  async test_done({ test }) {
+    const metadata = this._getTestMetadata(test);
+
+    if (this._startedTests.has(test)) {
+      await detoxInternals.onTestDone(metadata);
+      this._startedTests.delete(test);
+    }
+
+    log.trace.end(_.pick(metadata, ['status', 'timedOut']));
+  }
+
+  async _onBeforeActualTestStart(test) {
+    if (!this._isTestActuallyStarting(test)) {
+      return;
+    }
+
+    this._startedTests.add(test);
+    await detoxInternals.onTestStart(this._getTestMetadata(test));
+  }
+
+  _isTestActuallyStarting(test) {
+    return test && !this._isTestSkipped(test) && !this._startedTests.has(test) && !this._testsFailedBeforeStart.has(test);
+  }
+
+  _isTestSkipped(test) {
+    return test && (test.mode === 'skip' || test.mode === 'todo');
+  }
+
+  _getTestMetadata(test) {
+    const result = {
+      title: test.name,
+      fullName: getFullTestName(test),
+      status: this._getTestStatus(test),
+      invocations: this._getTestInvocations(test),
+    };
+
+    if (result.status === 'failed') {
+      result.timedOut = hasTimedOut(test);
+    }
+
+    return result;
+  }
+
+  /** @returns { 'failed' | 'passed' | 'running' | 'skip' | 'todo' } */
+  _getTestStatus(test) {
+    if (!_.isEmpty(test.errors)) {
+      return 'failed';
+    }
+
+    if (this._isTestSkipped(test)) {
+      return test.mode;
+    }
+
+    if (test.status === 'done') {
+      return 'passed';
+    } else {
+      return test.status || 'running';
+    }
+  }
+
+  _getTestInvocations(test) {
+    const { testSessionIndex } = detoxInternals.session;
+    return testSessionIndex * this._circusRetryTimes + test.invocations;
+  }
+}
+
+module.exports = DetoxCoreListener;

package/runners/{jest-circus → jest/testEnvironment}/listeners/DetoxInitErrorListener.js

@@ -15,7 +15,7 @@ class DetoxInitErrorListener {
     if (!_.isEmpty(unhandledErrors)) {
       const currentTest = _.last(currentDescribeBlock.children);
       const dummyError = new Error('Environment setup failed. See the detailed error below.');
-      delete dummyError.stack;
+      dummyError.stack = '';
 
       currentTest.errors.push(dummyError);
     }