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

package/index.js

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

package/internals.d.ts

@@ -0,0 +1,124 @@
+/// <reference types="node" />
+/// <reference path="index.d.ts"/>
+
+declare global {
+  namespace DetoxInternals {
+    type Facade = {
+      // region Initialization
+      /**
+       * Use with a caution, when you still have no config, yet need to avoid {@link Facade#globalSetup}
+       */
+      resolveConfig(options?: Partial<DetoxGlobalSetupOptions>): Promise<RuntimeConfig>;
+
+      /**
+       * This is the phase where Detox reads its configuration, starts a server.
+       */
+      globalSetup(options?: Partial<DetoxGlobalSetupOptions>): Promise<void>;
+
+      /**
+       * This is the phase where Detox loads its expection library and starts a device.
+       */
+      setup(options?: Partial<DetoxConfigurationSetupOptions>): Promise<void>;
+
+      /**
+       * The teardown phase deallocates the device.
+       */
+      teardown(): 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>;
+      // endregion
+
+      // region Lifecycle
+      onRunStart(event: unknown): Promise<void>;
+      onRunDescribeStart(event: unknown): Promise<void>;
+      onTestStart(event: unknown): Promise<void>;
+      onHookStart(event: unknown): Promise<void>;
+      onHookFailure(event: unknown): Promise<void>;
+      onHookSuccess(event: unknown): Promise<void>;
+      onTestFnStart(event: unknown): Promise<void>;
+      onTestFnFailure(event: unknown): Promise<void>;
+      onTestFnSuccess(event: unknown): Promise<void>;
+      onTestDone(event: unknown): Promise<void>;
+      onRunDescribeFinish(event: unknown): Promise<void>;
+      onRunFinish(event: unknown): Promise<void>;
+
+      /**
+       * Powers the "--retries <N>" of Detox CLI under the hood.
+       */
+      reportFailedTests(testFilePaths: string[]): Promise<void>;
+      // endregion
+
+      readonly config: RuntimeConfig;
+      readonly log: Detox.Logger;
+      readonly trace: Detox.Tracer;
+      readonly session: SessionState;
+
+      readonly worker: unknown;
+    }
+
+    type DetoxGlobalSetupOptions = {
+      cwd: string;
+      argv: Record<string, unknown>;
+      testRunnerArgv: Record<string, unknown>;
+      override: Partial<Detox.DetoxConfig>;
+    };
+
+    type DetoxConfigurationSetupOptions = {
+      global: NodeJS.Global;
+      workerId: number;
+    };
+
+    type SessionState = Readonly<{
+      failedTestFiles: string[];
+      workersCount: number;
+    }>;
+
+    type RuntimeConfig = Readonly<{
+      configurationName: string;
+
+      appsConfig: Record<string, Readonly<Detox.DetoxAppConfig>>;
+      artifactsConfig: Detox.DetoxArtifactsConfig;
+      behaviorConfig: Detox.DetoxBehaviorConfig;
+      cliConfig: DetoxCLIConfig;
+      deviceConfig: Detox.DetoxDeviceConfig;
+      loggerConfig: Detox.DetoxLoggerConfig;
+      runnerConfig: Detox.DetoxTestRunnerConfig;
+      sessionConfig: Detox.DetoxSessionConfig;
+    }>;
+
+    type DetoxCLIConfig = Readonly<Partial<{
+      appLaunchArgs: string;
+      artifactsLocation: string;
+      captureViewHierarchy: string;
+      cleanup: boolean;
+      configPath: string;
+      configuration: string;
+      debugSynchronization: number;
+      deviceBootArgs: string;
+      deviceName: string;
+      forceAdbInstall: boolean;
+      gpu: string;
+      inspectBrk: boolean;
+      headless: boolean;
+      jestReportSpecs: boolean;
+      keepLockFile: boolean;
+      loglevel: string;
+      readonlyEmu: boolean;
+      recordLogs: string;
+      recordPerformance: string;
+      recordVideos: string;
+      retries: number;
+      reuse: string;
+      takeScreenshots: string;
+      useCustomLogger: string;
+    }>>;
+  }
+}
+
+declare const detox: DetoxInternals.Facade;
+export = detox;
+

package/internals.js

@@ -0,0 +1,4 @@
+const realm = require('./src/realms');
+const DetoxInternalsFacade = require('./src/realms/DetoxInternalsFacade');
+
+module.exports = new DetoxInternalsFacade(realm);

package/local-cli/build-framework-cache.js

@@ -2,7 +2,7 @@ const cp = require('child_process');
 const os = require('os');
 const path = require('path');
 
-const log = require('../src/utils/logger').child({ __filename });
+const detox = require('../internals');
 
 module.exports.command = 'build-framework-cache';
 module.exports.desc = 'Builds 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)';
@@ -11,6 +11,6 @@ module.exports.handler = async function buildFrameworkCache() {
   if (os.platform() === 'darwin') {
     cp.execSync(path.join(__dirname, '../scripts/build_framework.ios.sh'), { stdio: 'inherit' });
   } else {
-    log.info(`The command is supported only on macOS, skipping the execution.`);
+    detox.log.info(`The command is supported only on macOS, skipping the execution.`);
   }
 };

package/local-cli/build.js

@@ -4,8 +4,7 @@ const fs = require('fs');
 
 const _ = require('lodash');
 
-const { composeDetoxConfig } = require('../src/configuration');
-const log = require('../src/utils/logger').child({ __filename });
+const detox = require('../internals');
 
 module.exports.command = 'build';
 module.exports.desc = "Runs the user-provided build command, as defined in the 'build' property of the specified configuration.";
@@ -38,27 +37,27 @@ module.exports.builder = {
 };
 
 module.exports.handler = async function build(argv) {
-  const { errorComposer, appsConfig } = await composeDetoxConfig({ argv });
+  const { appsConfig, errorComposer } = await detox.resolveConfig({ argv });
   const apps = _.entries(appsConfig);
 
   for (const [appName, app] of apps) {
     const buildScript = app.build;
 
     if (argv['if-missing'] && app.binaryPath && fs.existsSync(app.binaryPath)) {
-      log.info(`Skipping build for "${appName}" app...`);
+      detox.log.info(`Skipping build for "${appName}" app...`);
       continue;
     }
 
     if (buildScript) {
       try {
         if (apps.length > 1) {
-          log.info(`Building "${appName}" app...`);
+          detox.log.info(`Building "${appName}" app...`);
         }
 
-        log.info(buildScript);
+        detox.log.info(buildScript);
         cp.execSync(buildScript, { stdio: 'inherit' });
       } catch (e) {
-        log.warn("\n\nImportant: 'detox build' is a convenience shortcut for calling your own build command, as provided in the config file.\nFailures in this build command are not the responsibility of Detox. You are responsible for maintaining this command.\n");
+        detox.log.warn("\n\nImportant: 'detox build' is a convenience shortcut for calling your own build command, as provided in the config file.\nFailures in this build command are not the responsibility of Detox. You are responsible for maintaining this command.\n");
         throw e;
       }
     } else if (!argv.silent) {
@@ -66,7 +65,7 @@ module.exports.handler = async function build(argv) {
     }
 
     if (app.binaryPath && !fs.existsSync(app.binaryPath)) {
-      log.warn('\nImportant: after running the build command, Detox could not find your app at the given binary path:\n\t' + app.binaryPath + "\nMake sure it is correct, otherwise you'll get an error on an attempt to install your app.\n");
+      detox.log.warn('\nImportant: after running the build command, Detox could not find your app at the given binary path:\n\t' + app.binaryPath + "\nMake sure it is correct, otherwise you'll get an error on an attempt to install your app.\n");
     }
   }
 };

package/local-cli/build.test.js

@@ -1,51 +1,57 @@
-// @ts-nocheck
-jest.mock('child_process');
-jest.mock('../src/utils/logger');
-jest.mock('../src/configuration');
-
 const tempfile = require('tempfile');
 
-const DetoxConfigErrorComposer = require('../src/errors/DetoxConfigErrorComposer');
-
 describe('build', () => {
-  let log, execSync, composeDetoxConfig, detoxConfig;
+  let execSync, detox, callCli;
 
   beforeEach(() => {
-    detoxConfig = {
-      appsConfig: {},
-      artifactsConfig: {},
-      behaviorConfig: {},
-      deviceConfig: {},
-      sessionConfig: {},
-      errorComposer: new DetoxConfigErrorComposer(),
-    };
-
-    log = require('../src/utils/logger');
+    // @ts-ignore
+    callCli = global.callCli;
+    jest.mock('child_process');
     execSync = require('child_process').execSync;
-    composeDetoxConfig = require('../src/configuration').composeDetoxConfig;
-    composeDetoxConfig.mockReturnValue(Promise.resolve(detoxConfig));
+
+    jest.mock('../src/utils/logger');
+    jest.mock('../internals', () => {
+      const DetoxConfigErrorComposer = require('../src/errors/DetoxConfigErrorComposer');
+
+      const config = {
+        appsConfig: {},
+        artifactsConfig: {},
+        behaviorConfig: {},
+        errorComposer: new DetoxConfigErrorComposer(),
+        deviceConfig: {},
+        sessionConfig: {}
+      };
+
+      return ({
+        config,
+        resolveConfig: jest.fn().mockResolvedValue(config),
+        log: require('../src/utils/logger')
+      });
+    });
+
+    detox = require('../internals');
   });
 
-  it('passes argv to composeConfig', async () => {
+  it('passes argv to resolveConfig', async () => {
     await callCli('./build', 'build -C /etc/.detoxrc.js -c myconf').catch(() => {});
 
-    expect(composeDetoxConfig).toHaveBeenCalledWith({
+    expect(detox.resolveConfig).toHaveBeenCalledWith({
       argv: expect.objectContaining({
-        'config-path': '/etc/.detoxrc.js',
-        'configuration': 'myconf',
+        'C': '/etc/.detoxrc.js',
+        'c': 'myconf',
       }),
     });
   });
 
   it('runs the build script from the composed device config', async () => {
-    detoxConfig.appsConfig.default = { build: 'yet another command' };
+    detox.config.appsConfig.default = { build: 'yet another command' };
 
     await callCli('./build', 'build');
     expect(execSync).toHaveBeenCalledWith('yet another command', expect.anything());
   });
 
   it('skips building the app if the binary exists and --if-missing flag is set', async () => {
-    detoxConfig.appsConfig.default = { build: 'yet another command', binaryPath: __filename };
+    detox.config.appsConfig.default = { build: 'yet another command', binaryPath: __filename };
 
     await callCli('./build', 'build -i');
     expect(execSync).not.toHaveBeenCalled();
@@ -53,46 +59,46 @@ describe('build', () => {
     await callCli('./build', 'build --if-missing');
     expect(execSync).not.toHaveBeenCalled();
 
-    expect(log.info).toHaveBeenCalledWith('Skipping build for "default" app...');
+    expect(detox.log.info).toHaveBeenCalledWith('Skipping build for "default" app...');
   });
 
   it('fails with an error if a build script has not been found', async () => {
-    detoxConfig.appsConfig.default = {};
+    detox.config.appsConfig.default = {};
     await expect(callCli('./build', 'build')).rejects.toThrowError(/Failed to build/);
   });
 
   it('should ignore missing build command with -s, --silent flag', async () => {
-    detoxConfig.appsConfig.default = {};
+    detox.config.appsConfig.default = {};
     await expect(callCli('./build', 'build -s')).resolves.not.toThrowError();
-    expect(log.warn).not.toHaveBeenCalled();
+    expect(detox.log.warn).not.toHaveBeenCalled();
   });
 
   it('should print a warning upon user build script failure', async () => {
-    detoxConfig.appsConfig.default = { build: 'a command' };
+    detox.config.appsConfig.default = { build: 'a command' };
     execSync.mockImplementation(() => { throw new Error('Build failure'); });
     await expect(callCli('./build', 'build')).rejects.toThrowError(/Build failure/);
-    expect(log.warn).toHaveBeenCalledWith(expect.stringContaining('You are responsible'));
+    expect(detox.log.warn).toHaveBeenCalledWith(expect.stringContaining('You are responsible'));
   });
 
   it('should print a warning if app is not found at binary path', async () => {
-    detoxConfig.appsConfig.default = { binaryPath: tempfile() };
+    detox.config.appsConfig.default = { binaryPath: tempfile() };
     await expect(callCli('./build', 'build -s')).resolves.not.toThrowError();
-    expect(log.warn).toHaveBeenCalledWith(expect.stringContaining('could not find your app at the given binary path'));
+    expect(detox.log.warn).toHaveBeenCalledWith(expect.stringContaining('could not find your app at the given binary path'));
   });
 
   it('should print extra message with the app name before building (in a multi-app configuration)', async () => {
-    detoxConfig.appsConfig.app1 = { binaryPath: tempfile(), build: ':' };
-    detoxConfig.appsConfig.app2 = { binaryPath: tempfile(), build: ':' };
+    detox.config.appsConfig.app1 = { binaryPath: tempfile(), build: ':' };
+    detox.config.appsConfig.app2 = { binaryPath: tempfile(), build: ':' };
 
     await expect(callCli('./build', 'build -s')).resolves.not.toThrowError();
-    expect(log.info).toHaveBeenCalledWith(expect.stringContaining('app1'));
-    expect(log.info).toHaveBeenCalledWith(expect.stringContaining('app2'));
+    expect(detox.log.info).toHaveBeenCalledWith(expect.stringContaining('app1'));
+    expect(detox.log.info).toHaveBeenCalledWith(expect.stringContaining('app2'));
   });
 
   it('should not print that extra message when the app is single', async () => {
-    detoxConfig.appsConfig.default = { binaryPath: tempfile(), build: ':' };
+    detox.config.appsConfig.default = { binaryPath: tempfile(), build: ':' };
 
     await expect(callCli('./build', 'build -s')).resolves.not.toThrowError();
-    expect(log.info).not.toHaveBeenCalledWith(expect.stringContaining('default'));
+    expect(detox.log.info).not.toHaveBeenCalledWith(expect.stringContaining('default'));
   });
 });

package/local-cli/clean-framework-cache.js

@@ -3,7 +3,7 @@ const path = require('path');
 
 const fs = require('fs-extra');
 
-const log = require('../src/utils/logger').child({ __filename });
+const detox = require('../internals');
 
 module.exports.command = 'clean-framework-cache';
 module.exports.desc = "Deletes all Detox cached frameworks from ~/Library/Detox. Cached framework can be rebuilt using the 'build-framework-cache' command. (macOS only)";
@@ -11,9 +11,9 @@ module.exports.desc = "Deletes all Detox cached frameworks from ~/Library/Detox.
 module.exports.handler = async function cleanFrameworkCache() {
   if (os.platform() === 'darwin') {
     const frameworkPath = path.join(os.homedir(), '/Library/Detox');
-    log.info(`Removing framework binaries from ${frameworkPath}`);
+    detox.log.info(`Removing framework binaries from ${frameworkPath}`);
     await fs.remove(frameworkPath);
   } else {
-    log.info(`The command is supported only on macOS, skipping the execution.`);
+    detox.log.info(`The command is supported only on macOS, skipping the execution.`);
   }
 };

package/local-cli/cli.js

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-global.DETOX_CLI = true;
 const yargs = require('yargs');
 
 const DetoxError = require('../src/errors/DetoxError');

package/local-cli/init.js

@@ -1,47 +1,18 @@
 const fs = require('fs');
 const path = require('path');
 
-const DetoxRuntimeError = require('../src/errors/DetoxRuntimeError');
-const log = require('../src/utils/logger').child({ __filename });
+const detox = require('../internals');
 
 const jestTemplates = require('./templates/jest');
-const mochaTemplates = require('./templates/mocha');
 
 let exitCode = 0;
 
 module.exports.command = 'init';
-module.exports.desc = 'Scaffold initial E2E test folder structure for a specified test runner';
-module.exports.builder = {
-  runner: {
-    alias: 'r',
-    demandOption: true,
-    describe: 'test runner name (supported values: mocha, jest)',
-    group: 'Configuration:',
-    default: 'jest',
-  }
-};
-
-module.exports.handler = async function init(argv) {
-  const { runner } = argv;
-
-  switch (runner) {
-    case 'mocha':
-      createMochaFolderE2E();
-      break;
-    case 'jest':
-      createJestFolderE2E();
-      break;
-    default:
-      throw new DetoxRuntimeError([
-        `Convenience scaffolding for \`${runner}\` test runner is not supported currently.\n`,
-        'Supported runners at the moment are: `mocha` and `jest`:',
-        '* detox init -r mocha',
-        '* detox init -r jest\n',
-        `If it is not a typo, and you plan to work with \`${runner}\` runner, then you have to create test setup files manually.`,
-        'HINT: Try running one of the commands above, look what it does, and take similar steps for your use case.',
-      ].join('\n'));
-  }
+module.exports.desc = 'Scaffold initial E2E test folder structure for Detox';
+module.exports.builder = {};
 
+module.exports.handler = async function init() {
+  createJestFolderE2E();
   process.exit(exitCode); // eslint-disable-line
 };
 
@@ -72,43 +43,37 @@ function createFile(filename, content) {
 
   try {
     fs.writeFileSync(filename, content);
-    log.info(`Created a file at path: ${filename}`);
+    detox.log.info(`Created a file at path: ${filename}`);
   } catch (err) {
     reportError({ err }, `Failed to create a file at path: ${filename}`);
   }
 }
 
-function createMochaFolderE2E() {
-  createFolder('e2e', {
-    '.mocharc.json': mochaTemplates.runnerConfig,
-    'init.js': mochaTemplates.initjs,
-    'firstTest.spec.js': mochaTemplates.firstTest
-  });
-
-  createFile('.detoxrc.json', JSON.stringify({
-    testRunner: 'mocha',
-    runnerConfig: 'e2e/.mocharc.json',
-    ...createDefaultConfigurations(),
-  }, null, 2));
-}
-
 function createJestFolderE2E() {
   createFolder('e2e', {
     'config.json': jestTemplates.runnerConfig,
-    'environment.js': jestTemplates.environment,
-    'firstTest.e2e.js': jestTemplates.firstTest,
+    'starter.test.js': jestTemplates.starter,
   });
 
   createFile('.detoxrc.json', JSON.stringify({
-    testRunner: 'jest',
-    runnerConfig: 'e2e/config.json',
-    skipLegacyWorkersInjection: true,
+    testRunner: {
+      args: {
+        config: 'e2e/config.json'
+      },
+    },
+
     ...createDefaultConfigurations(),
   }, null, 2));
 }
 
 function createDefaultConfigurations() {
   return {
+    testRunner: {
+      args: {
+        $0: 'jest',
+        config: 'e2e/config.json',
+      },
+    },
     apps: {
       ios: {
         type: 'ios.app',
@@ -147,6 +112,6 @@ function createDefaultConfigurations() {
 }
 
 function reportError(...args) {
-  log.error(...args);
+  detox.log.error(...args);
   exitCode = 1;
 }

package/local-cli/templates/jest.js

@@ -1,41 +1,16 @@
 const firstTestContent = require('./firstTestContent');
 
 const runnerConfig = `{
-    "maxWorkers": 1,
-    "testEnvironment": "./environment",
-    "testRunner": "jest-circus/runner",
-    "testTimeout": 120000,
-    "testRegex": "\\\\.e2e\\\\.js$",
-    "reporters": ["detox/runners/jest/streamlineReporter"],
-    "verbose": true
+  "globalSetup": "detox/runners/jest/globalSetup",
+  "globalTeardown": "detox/runners/jest/globalTeardown",
+  "maxWorkers": 1,
+  "reporters": ["detox/runners/jest/reporter"],
+  "testEnvironment": "detox/runners/jest/testEnvironment",
+  "testMatch": ["<rootDir>/e2e/**/*.test.js"],
+  "testTimeout": 120000,
+  "verbose": true
 }
 `;
 
-const environmentJsContent = `const {
-  DetoxCircusEnvironment,
-  SpecReporter,
-  WorkerAssignReporter,
-} = require('detox/runners/jest-circus');
-
-class CustomDetoxEnvironment extends DetoxCircusEnvironment {
-  constructor(config, context) {
-    super(config, context);
-
-    // Can be safely removed, if you are content with the default value (=300000ms)
-    this.initTimeout = 300000;
-
-    // This takes care of generating status logs on a per-spec basis. By default, Jest only reports at file-level.
-    // This is strictly optional.
-    this.registerListeners({
-      SpecReporter,
-      WorkerAssignReporter,
-    });
-  }
-}
-
-module.exports = CustomDetoxEnvironment;
-`;
-
-exports.environment = environmentJsContent;
-exports.firstTest = firstTestContent;
+exports.starter = firstTestContent;
 exports.runnerConfig = runnerConfig;