detox 19.13.0 → 20.0.0

package/index.js

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

package/internals.d.ts

@@ -0,0 +1,298 @@
+/// <reference types="node" />
+/// <reference path="index.d.ts"/>
+
+declare global {
+  namespace DetoxInternals {
+    type DetoxStatus = 'inactive' | 'init' | 'active' | 'cleanup';
+
+    type Facade = {
+      //#region Initialization
+      /**
+       * Use with a caution, when you still have no config, yet need to avoid {@link Facade#init}
+       */
+      resolveConfig(options?: Partial<DetoxInitOptions>): Promise<RuntimeConfig>;
+
+      /**
+       * Returns one of statuses depending on what’s going with the current Detox context:
+       *
+       * `inactive` – before `init()` and after `cleanup()` is called.
+       * `init` – while `init()` is executing.
+       * `active` – after `init()` and before `cleanup()` is called.
+       * `cleanup` – while `cleanup()` is executing.
+       */
+      getStatus(): DetoxStatus;
+
+      /**
+       * Starts a new Detox test session with the provided configuration.
+       * See {@link https://wix.github.io/Detox/docs/api/internals} for more details.
+       */
+      init(options?: Partial<DetoxInitOptions>): Promise<void>;
+
+      /**
+       * This is the phase where Detox loads its expectation library and boots a device.
+       * You don't need to call it separately unless you use `init({ workerId: null })` override.
+       */
+      installWorker(options?: Partial<DetoxInstallWorkerOptions>): Promise<void>;
+
+      /**
+       * Deallocates the device.
+       * Most Client API (device, by, element, expect) will stop working, except for the logger.
+       */
+      uninstallWorker(): Promise<void>;
+
+      /**
+       * This method should be called when the main or child process is about to exit.
+       * See {@link https://wix.github.io/Detox/docs/api/internals} for more details.
+       */
+      cleanup(): Promise<void>;
+      //#endregion
+
+      //#region Lifecycle
+      /**
+       * Reports that the test runner started executing a test suite, e.g. a `beforeAll` hook or a first test.
+       */
+      onRunDescribeStart(event: {
+        /** Test suite name */
+        name: string;
+      }): Promise<void>;
+      /**
+       * Reports that the test runner started executing a specific test.
+       */
+      onTestStart(event: {
+        /** Test name */
+        title: string;
+        /** Test name including the ancestor suite titles */
+        fullName: string;
+        /**
+         * N-th time this test is running, if there is a retry mechanism.
+         *
+         * @default 1
+         */
+        invocations?: number;
+        status: 'running';
+      }): Promise<void>;
+      /**
+       * Reports about an error in the midst of `beforeAll`, `beforeEach`, `afterEach`, `afterAll` or any other hook.
+       */
+      onHookFailure(event: {
+        error: Error | string;
+        /**
+         * @example 'beforeAll'
+         * @example 'afterEach'
+         */
+        hook: string;
+      }): Promise<void>;
+      /**
+       * Reports about an error in the midst of a test function, `test` or `it`.
+       */
+      onTestFnFailure(event: {
+        error: Error | string;
+      }): Promise<void>;
+      /**
+       * Reports the final status of the test, `passed` or `failed`.
+       */
+      onTestDone(event: {
+        /** Test name */
+        title: string;
+        /** Test name including the ancestor suite titles */
+        fullName: string;
+        /**
+         * N-th time this test is running, if there is a retry mechanism.
+         *
+         * @default 1
+         */
+        invocations?: number;
+        status: 'passed' | 'failed';
+        /** Whether a timeout was the reason for why the test failed. */
+        timedOut?: boolean;
+      }): Promise<void>;
+      /**
+       * Reports that the test runner has finished executing a test suite, e.g. all the `afterAll` hooks have been executed or the last test has finished running.
+       */
+      onRunDescribeFinish(event: {
+        /** Test suite name */
+        name: string;
+      }): Promise<void>;
+
+      /**
+       * Reports to Detox CLI about passed and failed test files.
+       * The failed test files might be re-run again if
+       * {@link Detox.DetoxTestRunnerConfig#retries} is set to a non-zero.
+       *
+       * @param testResults - reports about test files
+       */
+      reportTestResults(testResults: DetoxTestFileReport[]): Promise<void>;
+      //#endregion
+
+      readonly config: RuntimeConfig;
+      readonly log: Detox.Logger;
+      readonly session: SessionState;
+      readonly tracing: {
+        /**
+         * Creates a readable stream of the currently recorded events in Chrome Trace Event format.
+         *
+         * @see {@link https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQtYMH4h6I0nSsKchNAySU}
+         * @see {import('trace-event-lib').DurationBeginEvent}
+         * @see {import('trace-event-lib').DurationEndEvent}
+         * @see {import('trace-event-lib').InstantEvent}
+         */
+        createEventStream(): NodeJS.ReadableStream;
+      };
+
+      /**
+       * Not documented on purpose.
+       * Provides direct access to the object which holds the device driver, websocket client, matchers, expectations, etc.
+       */
+      readonly worker: Worker;
+    }
+
+    interface Worker extends Detox.DetoxExportWrapper {
+      readonly id: string;
+    }
+
+    type DetoxInitOptions = {
+      cwd: string;
+      /**
+       * @internal
+       */
+      argv: Record<string, unknown>;
+      testRunnerArgv: Record<string, unknown>;
+      override: Partial<Detox.DetoxConfig>;
+      /** @inheritDoc */
+      global: NodeJS.Global | {};
+      /**
+       * Worker ID. Used to distinguish allocated workers in parallel test execution environment.
+       *
+       * If explicitly set to null, tells {@link Facade#init} to skip {@link Facade#installWorker} call.
+       * Useful for complex test runner integrations, where you have to install the worker via a separate call,
+       * when the environment is ready for that.
+       *
+       * @default 'worker'
+       */
+      workerId: string | null;
+    };
+
+    type DetoxInstallWorkerOptions = {
+      /**
+       * Used for integration with sandboxed test environments.
+       * {@link DetoxInternals.Facade#setup} might override {@link Console} methods
+       * to integrate it with Detox loggeing subsystem.
+       */
+      global: NodeJS.Global | {};
+      /**
+       * Worker ID. Used to distinguish allocated workers in parallel test execution environment.
+       *
+       * @default 'worker'
+       */
+      workerId: string;
+    };
+
+    type DetoxTestFileReport = {
+      /**
+       * Global or relative path to the failed test file.
+       */
+      testFilePath: string;
+      /**
+       * Whether the test passed or not.
+       */
+      success: boolean;
+      /**
+       * Top-level error if the entire test file failed.
+       */
+      testExecError?: { name?: string; message: string; stack?: string; };
+      /**
+       * If the test failed, it should tell whether the failure is permanent.
+       * Permanent failure means that the test file should not be re-run.
+       *
+       * @default false
+       * @see {Detox.DetoxTestRunnerConfig#retries}
+       */
+      isPermanentFailure?: boolean;
+    };
+
+    type SessionState = Readonly<{
+      /**
+       * Randomly generated ID for the entire Detox test session, including retries.
+       */
+      id: string;
+      /**
+       * Results of test file executions. Primarily used for Detox CLI retry mechanism.
+       */
+      testResults: DetoxTestFileReport[];
+      /**
+       * Retry index of the test session: 0..retriesCount.
+       */
+      testSessionIndex: number;
+      /**
+       * Count of Detox contexts with a worker installed.
+       * Oversimplified, it reflects the count of allocated devices in the current test session.
+       *
+       * @see {Facade#init}
+       * @see {Facade#installWorker}
+       */
+      workersCount: number;
+    }>;
+
+    type RuntimeConfig = Readonly<{
+      configurationName: string;
+
+      /**
+       * Dictionary of app configurations,
+       * where the keys are defined by {@link Detox.DetoxAppConfig#name}
+       * or equal to "default" if the name is not configured.
+       */
+      apps: Record<string, Readonly<Detox.DetoxAppConfig>>;
+      artifacts: Readonly<RuntimeArtifactsConfig>;
+      behavior: Readonly<Detox.DetoxBehaviorConfig>;
+      cli: Readonly<CLIConfig>;
+      device: Readonly<Detox.DetoxDeviceConfig>;
+      logger: Readonly<Detox.DetoxLoggerConfig>;
+      testRunner: Readonly<Detox.DetoxTestRunnerConfig>;
+      session: Readonly<Detox.DetoxSessionConfig>;
+    }>;
+
+    type RuntimeArtifactsConfig = {
+      rootDir: string;
+      pathBuilder: string;
+      plugins: Readonly<{
+        log: Readonly<Detox.DetoxLogArtifactsPluginConfig>;
+        screenshot: Readonly<Detox.DetoxScreenshotArtifactsPluginConfig>;
+        video: Readonly<Detox.DetoxVideoArtifactsPluginConfig>;
+        instruments: Readonly<Detox.DetoxInstrumentsArtifactsPluginConfig>;
+        uiHierarchy: Readonly<Detox.DetoxUIHierarchyArtifactsPluginConfig>;
+        [pluginId: string]: unknown;
+      }>;
+    };
+
+    type CLIConfig = 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 { apps: 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('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 = {
+        apps: {},
+        artifacts: {},
+        behavior: {},
+        errorComposer: new DetoxConfigErrorComposer(),
+        device: {},
+        session: {}
+      };
+
+      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.apps.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.apps.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.apps.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.apps.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.apps.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.apps.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.apps.app1 = { binaryPath: tempfile(), build: ':' };
+    detox.config.apps.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.apps.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,9 +1,11 @@
 #!/usr/bin/env node
-global.DETOX_CLI = true;
+const fs = require('fs');
+
+const _ = require('lodash');
 const yargs = require('yargs');
 
+const logger = require('../internals').log.child({ cat: 'cli' });
 const DetoxError = require('../src/errors/DetoxError');
-const logger = require('../src/utils/logger').child({ __filename });
 
 yargs
   .scriptName('detox')
@@ -26,12 +28,11 @@ yargs
   .wrap(yargs.terminalWidth() * 0.9)
   .fail(function(msg, err, program) {
     if (err) {
-      const lines = DetoxError.format(err).split('\n');
-      for (const line of lines) {
-        logger.error(line);
-      }
+      logger.error(DetoxError.format(err));
       // eslint-disable-next-line no-console
-      console.error('');
+      process.stderr.write('\n');
+      // @ts-ignore
+      _.attempt(() => fs.unlinkSync(logger.file));
       // eslint-disable-next-line no-process-exit
       process.exit(1);
     }