detox 20.0.2-breaking.new-global-lifecycle.0 → 20.0.2

package/index.d.ts

@@ -9,9 +9,9 @@
 // * Dor Ben Baruch <https://github.com/Dor256>
 
 import { BunyanDebugStreamOptions } from 'bunyan-debug-stream';
-import { EndHandle } from 'trace-event-lib';
 
 declare global {
+    const detox: Detox.DetoxExportWrapper;
     const device: Detox.DetoxExportWrapper['device'];
     const element: Detox.DetoxExportWrapper['element'];
     const waitFor: Detox.DetoxExportWrapper['waitFor'];
@@ -21,6 +21,7 @@ declare global {
 
     namespace NodeJS {
         interface Global {
+            detox: Detox.DetoxExportWrapper;
             device: Detox.DetoxExportWrapper['device'];
             element: Detox.DetoxExportWrapper['element'];
             waitFor: Detox.DetoxExportWrapper['waitFor'];
@@ -31,7 +32,7 @@ declare global {
     }
 
     namespace Detox {
-        // region DetoxConfig
+        //#region DetoxConfig
 
         interface DetoxConfig extends DetoxConfigurationCommon {
             /**
@@ -81,15 +82,19 @@ declare global {
                  */
                 exposeGlobals?: boolean;
                 /**
-                 * By default, Detox will uninstall and install the app upon the initialization.
+                 * By default, Detox will uninstall and install the app upon initialization.
                  * If you wish to reuse the existing app for a faster run, set the property to
                  * `false`.
                  */
                 reinstallApp?: boolean;
                 /**
-                 * If you wish to run multiple "detox test" commands in parallel,
-                 * make sure they don't delete the shared lock file – only the
-                 * first command should reset the lock file.
+                 * When false, `detox test` command always deletes the shared lock file on start,
+                 * assuming it had been left from the previous, already finished test session.
+                 * The lock file contains information about busy and free devices and ensures
+                 * no device can be used simultaneously by multiple test workers.
+                 *
+                 * Setting it to **true** might be useful when if you need to run multiple
+                 * `detox test` commands in parallel, e.g. test a few configurations at once.
                  *
                  * @default false
                  */
@@ -101,13 +106,43 @@ declare global {
             };
         }
 
+        type _DetoxLoggerOptions = Omit<BunyanDebugStreamOptions, 'out'>;
+
         interface DetoxLoggerConfig {
+            /**
+             * Log level filters the messages printed to your terminal,
+             * and it does not affect the logs written to the artifacts.
+             *
+             * Use `info` by default.
+             * Use `error` or warn when you want to make the output as silent as possible.
+             * Use `debug` to control what generally is happening under the hood.
+             * Use `trace` when troubleshooting specific issues.
+             *
+             * @default 'info'
+             */
             level?: DetoxLogLevel;
             /**
-             * @default 'sandbox'
+             * When enabled, hijacks all the console methods (console.log, console.warn, etc)
+             * so that the messages printed via them are formatted and saved as Detox logs.
+             *
+             * @default true
              */
-            overrideConsole?: 'all' | 'sandbox' | 'none';
-            options?: BunyanDebugStreamOptions;
+            overrideConsole?: boolean;
+            /**
+             * Since Detox is using
+             * {@link https://www.npmjs.com/package/bunyan-debug-stream bunyan-debug-stream}
+             * for printing logs, all its options are exposed for sake of simplicity
+             * of customization.
+             *
+             * The only exception is {@link BunyanDebugStreamOptions#out} option,
+             * which is always set to `process.stdout`.
+             *
+             * You can also pass a callback function to override the logger config
+             * programmatically, e.g. depending on the selected log level.
+             *
+             * @see {@link BunyanDebugStreamOptions}
+             */
+            options?: _DetoxLoggerOptions | ((config: Partial<DetoxLoggerConfig>) => _DetoxLoggerOptions);
         }
 
         interface DetoxSessionConfig {
@@ -132,32 +167,110 @@ declare global {
                  */
                 [prop: string]: unknown;
             };
+
             /**
-             * Configuration of custom integration features
-             * between Detox and Jest
+             * This is an add-on section used by our Jest integration code (but not Detox core itself).
+             * In other words, if you’re implementing (or using) a custom integration with some other test runner, feel free to define a section for yourself (e.g. `testRunner.mocha`)
              */
             jest?: {
                 /**
-                 * Device init timeout
+                 * Environment setup timeout
+                 *
+                 * As a part of the environment setup, Detox boots the device and installs the apps.
+                 * If that takes longer than the specified value, the entire test suite will be considered as failed, e.g.:
+                 * ```plain text
+                 * FAIL  e2e/starter.test.js
+                 * ● Test suite failed to run
+                 *
+                 * Exceeded timeout of 300000ms while setting up Detox environment
+                 * ```
+                 *
+                 * The default value is 5 minutes.
+                 *
+                 * @default 300000
+                 * @see {@link https://jestjs.io/docs/configuration/#testenvironment-string}
+                 */
+                setupTimeout?: number | undefined;
+                /**
+                 * Environemnt teardown timeout
+                 *
+                 * If the environment teardown takes longer than the specified value, Detox will throw a timeout error.
+                 * The default value is half a minute.
+                 *
+                 * @default 30000 (30 seconds)
+                 * @see {@link https://jestjs.io/docs/configuration/#testenvironment-string}
                  */
-                initTimeout?: number | undefined;
+                teardownTimeout?: number | undefined;
                 /**
-                 * Insist on CLI-based retry mechanism even when the failed tests have been handled
-                 * by jest.retryTimes(n) mechanism from Jest Circus.
+                 * Jest provides an API to re-run individual failed tests: `jest.retryTimes(count)`.
+                 * When Detox detects the use of this API, it suppresses its own CLI retry mechanism controlled via `detox test … --retries <N>` or {@link DetoxTestRunnerConfig#retries}.
+                 * The motivation is simple – activating the both mechanisms is apt to increase your test duration dramatically, if your tests are flaky.
+                 * If you wish nevertheless to use both the mechanisms simultaneously, set it to `true`.
+                 *
+                 * @default false
+                 * @see {@link https://jestjs.io/docs/29.0/jest-object#jestretrytimesnumretries-options}
                  */
                 retryAfterCircusRetries?: boolean;
+                /**
+                 * By default, Jest prints the test names and their status (_passed_ or _failed_) at the very end of the test session.
+                 * When enabled, it makes Detox to print messages like these each time the new test starts and ends:
+                 * ```plain text
+                 * 18:03:36.258 detox[40125] i Sanity: should have welcome screen
+                 * 18:03:37.495 detox[40125] i Sanity: should have welcome screen [OK]
+                 * 18:03:37.496 detox[40125] i Sanity: should show hello screen after tap
+                 * 18:03:38.928 detox[40125] i Sanity: should show hello screen after tap [OK]
+                 * 18:03:38.929 detox[40125] i Sanity: should show world screen after tap
+                 * 18:03:40.351 detox[40125] i Sanity: should show world screen after tap [OK]
+                 * ```
+                 * By default, it is enabled automatically in test sessions with a single worker.
+                 * And vice versa, if multiple tests are executed concurrently, Detox turns it off to avoid confusion in the log.
+                 * Use boolean values, `true` or `false`, to turn off the automatic choice.
+                 *
+                 * @default undefined
+                 */
                 reportSpecs?: boolean | undefined;
+                /**
+                 * In the environment setup phase, Detox boots the device and installs the apps.
+                 * This flag tells Detox to print messages like these every time the device gets assigned to a specific suite:
+                 *
+                 * ```plain text
+                 * 18:03:29.869 detox[40125] i starter.test.js is assigned to 4EC84833-C7EA-4CA3-A6E9-5C30A29EA596 (iPhone 12 Pro Max)
+                 * ```
+                 *
+                 * @default true
+                 */
                 reportWorkerAssign?: boolean | undefined;
             };
             /**
              * Retries count. Zero means a single attempt to run tests.
              */
             retries?: number;
+            /**
+             * When true, tells Detox CLI to cancel next retrying if it gets
+             * at least one report about a permanent test suite failure.
+             * Has no effect, if {@link DetoxTestRunnerConfig#retries} is
+             * undefined or set to zero.
+             *
+             * @default false
+             * @see {DetoxInternals.DetoxTestFileReport#isPermanentFailure}
+             */
+            bail?: boolean;
             /**
              * Custom handler to process --inspect-brk CLI flag.
-             * Use it when you rely on another test runner than Jest.
+             * Use it when you rely on another test runner than Jest to mutate the config.
+             */
+            inspectBrk?: (config: DetoxTestRunnerConfig) => void;
+            /**
+             * Forward environment variables to the spawned test runner
+             * accordingly to the given CLI argument overrides.
+             *
+             * If false, Detox CLI will be only printing a hint message on
+             * how to start the test runner using environment variables,
+             * in case when a user wants to avoid using Detox CLI.
+             *
+             * @default false
              */
-            inspectBrk?: boolean | ((config: DetoxTestRunnerConfig) => void);
+            forwardEnv?: boolean;
         }
 
         type DetoxAppConfig = (DetoxBuiltInAppConfig | DetoxCustomAppConfig) & {
@@ -228,6 +341,13 @@ declare global {
             build?: string;
             testBinaryPath?: string;
             launchArgs?: Record<string, any>;
+            /**
+             * TCP ports to `adb reverse` upon the installation.
+             * E.g. 8081 - to be able to access React Native packager in Debug mode.
+             *
+             * @example [8081]
+             */
+            reversePorts?: number[];
         }
 
         interface DetoxCustomAppConfig {
@@ -288,8 +408,6 @@ declare global {
             os: string;
         }
 
-        type DetoxKnownDeviceType = DetoxBuiltInDeviceConfig['type'];
-
         type DetoxConfiguration = DetoxConfigurationCommon & (
             | DetoxConfigurationSingleApp
             | DetoxConfigurationMultiApps
@@ -309,7 +427,7 @@ declare global {
 
         type DetoxAliasedApp = string | DetoxAppConfig;
 
-        // endregion DetoxConfig
+        //#endregion
 
         interface DetoxExportWrapper {
             readonly device: Device;
@@ -344,64 +462,81 @@ declare global {
             readonly log: Logger;
 
             /**
+             * @deprecated
+             *
+             * Deprecated - use {@link Detox.Logger#trace}
              * Detox tracer instance. Can be used for building timelines in Google Event Tracing format.
              */
-            readonly trace: Tracer;
+            readonly trace: {
+                /** @deprecated */
+                readonly startSection: (name: string) => void;
+                /** @deprecated */
+                readonly endSection: (name: string) => void;
+            };
 
             /**
+             * Trace a single call, with a given name and arguments.
+             *
              * @deprecated
+             * @param sectionName The name of the section to trace.
+             * @param promiseOrFunction Promise or a function that provides a promise.
+             * @param args Optional arguments to pass to the trace.
+             * @returns The returned value of the traced call.
+             * @see https://wix.github.io/Detox/docs/19.x/api/detox-object-api/#detoxtracecall
              */
-            readonly traceCall: _TraceCallSignature;
+            readonly traceCall: <T>(event: string, action: () => Promise<T>, args?: Record<string, unknown>) => Promise<T>;
         }
 
-        /** @internal */
-        type _TraceEventArgs = Record<string, unknown>;
+        interface Logger {
+            readonly level: DetoxLogLevel;
 
-        type TraceEvent = {
-            name?: string;
-            cat?: string;
-            cname?: string;
-            id?: number;
-            args?: _TraceEventArgs;
-        };
+            readonly fatal: _LogMethod;
+            readonly error: _LogMethod;
+            readonly warn: _LogMethod;
+            readonly info: _LogMethod;
+            readonly debug: _LogMethod;
+            readonly trace: _LogMethod;
 
-        /**
-         * Trace a duration event before and after executing the action function
-         *
-         * @internal
-         */
-        interface _TraceCallSignature {
-            <T>(event: string | TraceEvent, action: () => T): T;
-            <T>(event: string | TraceEvent, action: () => Promise<T>): Promise<T>;
+            child(context?: Partial<LogEvent>): Logger;
         }
 
         /** @internal */
-        interface _TraceSectionSignature<T> {
-            (event?: string, args?: _TraceEventArgs): T;
-            (event: TraceEvent): T;
+        interface _LogMethod extends _LogMethodSignature {
+            readonly begin: _LogMethodSignature;
+            readonly complete: _CompleteMethodSignature;
+            readonly end: _LogMethodSignature;
         }
 
-        interface Tracer extends _TraceCallSignature {
-            readonly begin: _TraceSectionSignature<EndHandle<{ cname: string; args: _TraceEventArgs; }>>;
-            readonly end: _TraceSectionSignature<void>;
+        /** @internal */
+        interface _LogMethodSignature {
+            (...args: unknown[]): void
+            (event: LogEvent, ...args: unknown[]): void;
+        }
 
-            /** @deprecated */
-            readonly startSection: _TraceSectionSignature<void>;
-            /** @deprecated */
-            readonly endSection: _TraceSectionSignature<void>;
+        /** @internal */
+        interface _CompleteMethodSignature {
+            <T>(message: string, action: T | (() => T)): T;
+            <T>(event: LogEvent, message: string, action: T | (() => T)): T;
         }
 
-        type Logger = {
-            readonly level: DetoxLogLevel;
+        type LogEvent = {
+            /** Use when there's a risk of logging several parallel duration events. */
+            id?: string | number;
+            /** Optional. Event categories (tags) to facilitate filtering. */
+            cat?: string | string[];
+            /** Optional. Color name (applicable in Google Chrome Trace Format) */
+            cname?: string;
 
-            fatal(context?: unknown, ...args: any[]): void;
-            error(context?: unknown, ...args: any[]): void;
-            warn(context?: unknown, ...args: any[]): void;
-            info(context?: unknown, ...args: any[]): void;
-            debug(context?: unknown, ...args: any[]): void;
-            trace(context?: unknown, ...args: any[]): void;
+            /** Reserved property. Process ID. */
+            pid?: never;
+            /** Reserved property. Thread ID. */
+            tid?: never;
+            /** Reserved property. Timestamp. */
+            ts?: never;
+            /** Reserved property. Event phase. */
+            ph?: never;
 
-            child(context?: Record<string, unknown>): Logger;
+            [customProperty: string]: unknown;
         };
 
         type DetoxLogLevel = 'fatal' | 'error' | 'warn' | 'info' | 'debug' | 'trace';
@@ -544,10 +679,11 @@ declare global {
              * Relaunch the app. Convenience method that calls {@link Device#launchApp}
              * with { newInstance: true } override.
              *
+             * @deprecated
              * @param config
              * @see Device#launchApp
              */
-            relaunchApp(config?: Omit<DeviceLaunchAppConfig, 'newInstance'>): Promise<void>;
+            relaunchApp(config?: DeviceLaunchAppConfig): Promise<void>;
 
             /**
              * Access the user-defined launch-arguments predefined through static scopes such as the Detox configuration file and