detox 21.0.0-breaking.new-global-lifecycle.0 → 21.0.1-rc.0

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,27 +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}
+                 */
+                teardownTimeout?: number | undefined;
+                /**
+                 * 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
                  */
-                initTimeout?: number | 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?: boolean | ((config: DetoxTestRunnerConfig) => void);
+            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
+             */
+            forwardEnv?: boolean;
         }
 
         type DetoxAppConfig = (DetoxBuiltInAppConfig | DetoxCustomAppConfig) & {
@@ -213,6 +331,7 @@ declare global {
             binaryPath: string;
             bundleId?: string;
             build?: string;
+            start?: string;
             launchArgs?: Record<string, any>;
         }
 
@@ -221,8 +340,16 @@ declare global {
             binaryPath: string;
             bundleId?: string;
             build?: string;
+            start?: 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 {
@@ -283,8 +410,6 @@ declare global {
             os: string;
         }
 
-        type DetoxKnownDeviceType = DetoxBuiltInDeviceConfig['type'];
-
         type DetoxConfiguration = DetoxConfigurationCommon & (
             | DetoxConfigurationSingleApp
             | DetoxConfigurationMultiApps
@@ -304,7 +429,7 @@ declare global {
 
         type DetoxAliasedApp = string | DetoxAppConfig;
 
-        // endregion DetoxConfig
+        //#endregion
 
         interface DetoxExportWrapper {
             readonly device: Device;
@@ -339,64 +464,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';
@@ -484,9 +626,8 @@ declare global {
 
         interface Device {
             /**
-             * Holds the environment-unique ID of the device - namely, the adb ID on Android (e.g. emulator-5554) and the Mac-global simulator UDID on iOS,
+             * Holds the environment-unique ID of the device, namely, the adb ID on Android (e.g. emulator-5554) and the Mac-global simulator UDID on iOS -
              * as used by simctl (e.g. AAAAAAAA-BBBB-CCCC-DDDD-EEEEEEEEEEEE).
-             *
              */
             id: string;
             /**
@@ -539,10 +680,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
@@ -979,39 +1121,39 @@ declare global {
              * expectation with a `not` expects the view's visible area to be smaller than N%.
              * @param pct optional integer ranging from 1 to 100, indicating how much percent of the view should be
              *  visible to the user to be accepted.
-             * @example await expect(element(by.id('UniqueId204'))).toBeVisible(35);
+             * @example await expect(element(by.id('mainTitle'))).toBeVisible(35);
              */
             toBeVisible(pct?: number): R;
 
             /**
              * Negate the expectation.
-             * @example await expect(element(by.id('UniqueId205'))).not.toBeVisible();
+             * @example await expect(element(by.id('cancelButton'))).not.toBeVisible();
              */
             not: this;
 
             /**
              * Expect the view to not be visible.
-             * @example await expect(element(by.id('UniqueId205'))).toBeNotVisible();
+             * @example await expect(element(by.id('cancelButton'))).toBeNotVisible();
              * @deprecated Use `.not.toBeVisible()` instead.
              */
             toBeNotVisible(): R;
 
             /**
              * Expect the view to exist in the UI hierarchy.
-             * @example await expect(element(by.id('UniqueId205'))).toExist();
+             * @example await expect(element(by.id('okButton'))).toExist();
              */
             toExist(): R;
 
             /**
              * Expect the view to not exist in the UI hierarchy.
-             * @example await expect(element(by.id('RandomJunk959'))).toNotExist();
+             * @example await expect(element(by.id('cancelButton'))).toNotExist();
              * @deprecated Use `.not.toExist()` instead.
              */
             toNotExist(): R;
 
             /**
              * Expect the view to be focused.
-             * @example await expect(element(by.id('loginInput'))).toBeFocused();
+             * @example await expect(element(by.id('emailInput'))).toBeFocused();
              */
             toBeFocused(): R;
 
@@ -1025,21 +1167,23 @@ declare global {
             /**
              * In React Native apps, expect UI component of type <Text> to have text.
              * In native iOS apps, expect UI elements of type UIButton, UILabel, UITextField or UITextViewIn to have inputText with text.
-             * @example await expect(element(by.id('UniqueId204'))).toHaveText('I contain some text');
+             * @example await expect(element(by.id('mainTitle'))).toHaveText('Welcome back!);
              */
             toHaveText(text: string): R;
 
             /**
-             * It searches by accessibilityLabel on iOS, or by contentDescription on Android.
-             * In React Native it can be set for both platforms by defining an accessibilityLabel on the view.
-             * @example await expect(element(by.id('UniqueId204'))).toHaveLabel('Done');
+             * Expects a specific accessibilityLabel, as specified via the `accessibilityLabel` prop in React Native.
+             * On the native side (in both React Native and pure-native apps), that is equivalent to `accessibilityLabel`
+             * on iOS and contentDescription on Android. Refer to Detox's documentation in order to learn about caveats
+             * with accessibility-labels in React Native apps.
+             * @example await expect(element(by.id('submitButton'))).toHaveLabel('Submit');
              */
             toHaveLabel(label: string): R;
 
             /**
              * In React Native apps, expect UI component to have testID with that id.
              * In native iOS apps, expect UI element to have accessibilityIdentifier with that id.
-             * @example await expect(element(by.text('I contain some text'))).toHaveId('UniqueId204');
+             * @example await expect(element(by.text('Submit'))).toHaveId('submitButton');
              */
             toHaveId(id: string): R;
 
@@ -1052,7 +1196,7 @@ declare global {
 
             /**
              * Expect components like a Switch to have a value ('0' for off, '1' for on).
-             * @example await expect(element(by.id('UniqueId533'))).toHaveValue('0');
+             * @example await expect(element(by.id('temperatureDial'))).toHaveValue('25');
              */
             toHaveValue(value: any): R;
 
@@ -1069,7 +1213,7 @@ declare global {
             /**
              * This API polls using the given expectation continuously until the expectation is met. Use manual synchronization with waitFor only as a last resort.
              * NOTE: Every waitFor call must set a timeout using withTimeout(). Calling waitFor without setting a timeout will do nothing.
-             * @example await waitFor(element(by.id('UniqueId336'))).toExist().withTimeout(2000);
+             * @example await waitFor(element(by.id('bigButton'))).toExist().withTimeout(2000);
              */
             (element: NativeElement): Expect<WaitFor>;
         }
@@ -1077,13 +1221,13 @@ declare global {
         interface WaitFor {
             /**
              * Waits for the condition to be met until the specified time (millis) have elapsed.
-             * @example await waitFor(element(by.id('UniqueId336'))).toExist().withTimeout(2000);
+             * @example await waitFor(element(by.id('bigButton'))).toExist().withTimeout(2000);
              */
             withTimeout(millis: number): Promise<void>;
 
             /**
              * Performs the action repeatedly on the element until an expectation is met
-             * @example await waitFor(element(by.text('Text5'))).toBeVisible().whileElement(by.id('ScrollView630')).scroll(50, 'down');
+             * @example await waitFor(element(by.text('Item #5'))).toBeVisible().whileElement(by.id('itemsList')).scroll(50, 'down');
              */
             whileElement(by: NativeMatcher): NativeElement & WaitFor;
 
@@ -1224,15 +1368,25 @@ declare global {
             setColumnToValue(column: number, value: string): Promise<void>;
 
             /**
-             * Sets the date of a date picker to a date generated from the provided string and date format. (iOS only)
-             * @param dateString string representing a date in the supplied `dateFormat`
-             * @param dateFormat format for the `dateString` supplied
+             * Sets the date of a date-picker according to the specified date-string and format.
+             * @param dateString Textual representation of a date (e.g. '2023/01/01'). Should be in coherence with the format specified by `dateFormat`.
+             * @param dateFormat Format of `dateString`: Generally either 'ISO8601' or an explicitly specified format (e.g. 'yyyy/MM/dd'); It should
+             *      follow the rules of NSDateFormatter for iOS and DateTimeFormatter for Android.
+             * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString
              * @example
-             * await expect(element(by.id('datePicker'))).toBeVisible();
-             * await element(by.id('datePicker')).setDatePickerDate('2019-02-06T05:10:00-08:00', "yyyy-MM-dd'T'HH:mm:ssZZZZZ");
+             * await element(by.id('datePicker')).setDatePickerDate('2023-01-01T00:00:00Z', 'ISO8601');
+             * await element(by.id('datePicker')).setDatePickerDate(new Date().toISOString(), 'ISO8601');
+             * await element(by.id('datePicker')).setDatePickerDate('2023/01/01', 'yyyy/MM/dd');
              */
             setDatePickerDate(dateString: string, dateFormat: string): Promise<void>;
 
+            /**
+             * Triggers a given [accessibility action]{@link https://reactnative.dev/docs/accessibility#accessibility-actions}.
+             * @param actionName - name of the accessibility action
+             * @example await element(by.id('view')).performAccessibilityAction('activate');
+             */
+            performAccessibilityAction(actionName: string): Promise<void>
+
             /**
              * Pinches in the given direction with speed and angle. (iOS only)
              * @param angle value in radiant, default is `0`
@@ -1292,7 +1446,7 @@ declare global {
         interface WebExpect<R = Promise<void>> {
             /**
              * Negate the expectation.
-             * @example await expect(web.element(by.web.id('UniqueId205'))).not.toExist();
+             * @example await expect(web.element(by.web.id('sessionTimeout'))).not.toExist();
              */
             not: this;
 
@@ -1300,13 +1454,13 @@ declare global {
              * Expect the element content to have the `text` supplied
              * @param text expected to be on the element content
              * @example
-             * await expect(web.element(by.web.id('UniqueId205'))).toHaveText('ExactText');
+             * await expect(web.element(by.web.id('checkoutButton'))).toHaveText('Proceed to check out');
              */
             toHaveText(text: string): R;
 
             /**
              * Expect the view to exist in the webview DOM tree.
-             * @example await expect(web.element(by.web.id('UniqueId205'))).toExist();
+             * @example await expect(web.element(by.web.id('submitButton'))).toExist();
              */
             toExist(): R;
         }
@@ -1505,7 +1659,9 @@ declare global {
              */
             text?: string;
             /**
-             * The label of the element. Matches accessibilityLabel for ios, and contentDescription for android.
+             * The label of the element. Largely matches accessibilityLabel for ios, and contentDescription for android.
+             * Refer to Detox's documentation (`toHaveLabel()` subsection) in order to learn about caveats associated with
+             * this property in React Native apps.
              */
             label?: string;
             /**

package/index.js

@@ -1 +1,12 @@
-module.exports = require('./src/realms');
+function create() {
+  if (process.env.DETOX_CONFIG_SNAPSHOT_PATH) {
+    return require('./src/realms/secondary');
+  } else {
+    return require('./src/realms/primary');
+  }
+}
+
+/** @type {Detox.DetoxExportWrapper} */
+module.exports = global['__detox__']
+  ? global['__detox__'].clientApi
+  : create();