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

package/index.d.ts

@@ -8,6 +8,9 @@
 // * Max Komarychev <https://github.com/maxkomarychev>
 // * Dor Ben Baruch <https://github.com/Dor256>
 
+import { BunyanDebugStreamOptions } from 'bunyan-debug-stream';
+import { EndHandle } from 'trace-event-lib';
+
 declare global {
     const device: Detox.DetoxExportWrapper['device'];
     const element: Detox.DetoxExportWrapper['element'];
@@ -15,7 +18,6 @@ declare global {
     const expect: Detox.DetoxExportWrapper['expect'];
     const by: Detox.DetoxExportWrapper['by'];
     const web: Detox.DetoxExportWrapper['web'];
-    const detoxCircus: Detox.DetoxCircus;
 
     namespace NodeJS {
         interface Global {
@@ -25,49 +27,33 @@ declare global {
             expect: Detox.DetoxExportWrapper['expect'];
             by: Detox.DetoxExportWrapper['by'];
             web: Detox.DetoxExportWrapper['web'];
-            detoxCircus: Detox.DetoxCircus;
         }
     }
 
     namespace Detox {
         // region DetoxConfig
 
-        interface DetoxConfig {
+        interface DetoxConfig extends DetoxConfigurationCommon {
             /**
              * @example extends: './relative/detox.config'
              * @example extends: '@my-org/detox-preset'
              */
             extends?: string;
-            /**
-             * @example testRunner: 'jest'
-             * @example testRunner: 'mocha'
-             */
-            testRunner?: string;
-            /**
-             * Stops passing default `--maxWorkers 1` to the test runner,
-             * presuming that from now on you have that already configured
-             * in your test runner config as a default.
-             */
-            skipLegacyWorkersInjection?: boolean;
-            /**
-             * @example runnerConfig: 'e2e/config.js'
-             */
-            runnerConfig?: string;
-            /**
-             * Optional. A default glob pattern for a test runner to use when no test files are specified.
-             *
-             * @example specs: 'detoxE2E'
-             */
-            specs?: string;
-            artifacts?: DetoxArtifactsConfig;
-            behavior?: DetoxBehaviorConfig;
-            session?: DetoxSessionConfig;
+
             apps?: Record<string, DetoxAppConfig>;
             devices?: Record<string, DetoxDeviceConfig>;
             selectedConfiguration?: string;
             configurations: Record<string, DetoxConfiguration>;
         }
 
+        type DetoxConfigurationCommon = {
+            artifacts?: false | DetoxArtifactsConfig;
+            behavior?: DetoxBehaviorConfig;
+            logger?: DetoxLoggerConfig;
+            session?: DetoxSessionConfig;
+            testRunner?: DetoxTestRunnerConfig;
+        };
+
         interface DetoxArtifactsConfig {
             rootDir?: string;
             pathBuilder?: string;
@@ -76,7 +62,6 @@ declare global {
                 screenshot?: 'none' | 'manual' | 'failing' | 'all' | DetoxScreenshotArtifactsPluginConfig;
                 video?: 'none' | 'failing' | 'all' | DetoxVideoArtifactsPluginConfig;
                 instruments?: 'none' | 'all' | DetoxInstrumentsArtifactsPluginConfig;
-                timeline?: 'none' | 'all' | DetoxTimelineArtifactsPluginConfig;
                 uiHierarchy?: 'disabled' | 'enabled' | DetoxUIHierarchyArtifactsPluginConfig;
 
                 [pluginId: string]: unknown;
@@ -96,11 +81,19 @@ declare global {
                  */
                 exposeGlobals?: boolean;
                 /**
-                 * By default, `await detox.init()` will uninstall and install the app.
+                 * By default, Detox will uninstall and install the app upon the 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.
+                 *
+                 * @default false
+                 */
+                keepLockFile?: boolean;
             };
             launchApp?: 'auto' | 'manual';
             cleanup?: {
@@ -108,6 +101,15 @@ declare global {
             };
         }
 
+        interface DetoxLoggerConfig {
+            level?: DetoxLogLevel;
+            /**
+             * @default 'sandbox'
+             */
+            overrideConsole?: 'all' | 'sandbox' | 'none';
+            options?: BunyanDebugStreamOptions;
+        }
+
         interface DetoxSessionConfig {
             autoStart?: boolean;
             debugSynchronization?: number;
@@ -115,7 +117,45 @@ declare global {
             sessionId?: string;
         }
 
-        type DetoxAppConfig = (DetoxIosAppConfig | DetoxAndroidAppConfig) & {
+        interface DetoxTestRunnerConfig {
+            args?: {
+                /**
+                 * The command to use for runner: 'jest', 'nyc jest',
+                 */
+                $0: string;
+                /**
+                 * The positional arguments to pass to the runner.
+                 */
+                _?: string[];
+                /**
+                 * Any other properties recognized by test runner
+                 */
+                [prop: string]: unknown;
+            };
+            /**
+             * Configuration of custom integration features
+             * between Detox and Jest
+             */
+            jest?: {
+                /**
+                 * Device init timeout
+                 */
+                initTimeout?: number | undefined;
+                reportSpecs?: boolean | undefined;
+                reportWorkerAssign?: boolean | undefined;
+            };
+            /**
+             * Retries count. Zero means a single attempt to run tests.
+             */
+            retries?: number;
+            /**
+             * Custom handler to process --inspect-brk CLI flag.
+             * Use it when you rely on another test runner than Jest.
+             */
+            inspectBrk?: boolean | ((config: DetoxTestRunnerConfig) => void);
+        }
+
+        type DetoxAppConfig = (DetoxBuiltInAppConfig | DetoxCustomAppConfig) & {
             /**
              * App name to use with device.selectApp(appName) calls.
              * Can be omitted if you have a single app under the test.
@@ -127,8 +167,6 @@ declare global {
 
         type DetoxDeviceConfig = DetoxBuiltInDeviceConfig | DetoxCustomDriverConfig;
 
-        type DetoxConfiguration = DetoxPlainConfiguration | DetoxAliasedConfiguration;
-
         interface DetoxLogArtifactsPluginConfig {
             enabled?: boolean;
             keepOnlyFailedTestsArtifacts?: boolean;
@@ -168,9 +206,7 @@ declare global {
             enabled?: boolean;
         }
 
-        interface DetoxTimelineArtifactsPluginConfig {
-            enabled?: boolean;
-        }
+        type DetoxBuiltInAppConfig = (DetoxIosAppConfig | DetoxAndroidAppConfig);
 
         interface DetoxIosAppConfig {
             type: 'ios.app';
@@ -189,29 +225,17 @@ declare global {
             launchArgs?: Record<string, any>;
         }
 
-        interface _DetoxAppConfigFragment {
-            binaryPath: string;
-            bundleId?: string;
-            build?: string;
-            testBinaryPath?: string;
-            launchArgs?: Record<string, any>;
+        interface DetoxCustomAppConfig {
+            type: string;
+
+            [prop: string]: unknown;
         }
 
         type DetoxBuiltInDeviceConfig =
-          | DetoxIosSimulatorDriverConfig
-          | DetoxIosNoneDriverConfig
-          | DetoxAttachedAndroidDriverConfig
-          | DetoxAndroidEmulatorDriverConfig
-          | DetoxGenymotionCloudDriverConfig;
-
-        type DetoxPlainConfiguration = DetoxConfigurationOverrides & (
-          | (DetoxIosSimulatorDriverConfig & _DetoxAppConfigFragment)
-          | (DetoxIosNoneDriverConfig & _DetoxAppConfigFragment)
-          | (DetoxAttachedAndroidDriverConfig & _DetoxAppConfigFragment)
-          | (DetoxAndroidEmulatorDriverConfig & _DetoxAppConfigFragment)
-          | (DetoxGenymotionCloudDriverConfig & _DetoxAppConfigFragment)
-          | (DetoxCustomDriverConfig)
-          );
+            | DetoxIosSimulatorDriverConfig
+            | DetoxAttachedAndroidDriverConfig
+            | DetoxAndroidEmulatorDriverConfig
+            | DetoxGenymotionCloudDriverConfig;
 
         interface DetoxIosSimulatorDriverConfig {
             type: 'ios.simulator';
@@ -219,12 +243,6 @@ declare global {
             bootArgs?: string;
         }
 
-        interface DetoxIosNoneDriverConfig {
-            type: 'ios.none';
-            // TODO: check if we need it at all?
-            device?: string | Partial<IosSimulatorQuery>;
-        }
-
         interface DetoxSharedAndroidDriverConfig {
             forceAdbInstall?: boolean;
             utilBinaryPaths?: string[];
@@ -239,8 +257,11 @@ declare global {
             type: 'android.emulator';
             device: string | { avdName: string };
             bootArgs?: string;
-            gpuMode?: 'auto' | 'host' | 'swiftshader_indirect' | 'angle_indirect' | 'guest';
+            gpuMode?: 'auto' | 'host' | 'swiftshader_indirect' | 'angle_indirect' | 'guest' | 'off';
             headless?: boolean;
+            /**
+             * @default true
+             */
             readonly?: boolean;
         }
 
@@ -264,109 +285,127 @@ declare global {
 
         type DetoxKnownDeviceType = DetoxBuiltInDeviceConfig['type'];
 
-        type DetoxConfigurationOverrides = {
-            artifacts?: false | DetoxArtifactsConfig;
-            behavior?: DetoxBehaviorConfig;
-            session?: DetoxSessionConfig;
-        };
-
-        type DetoxAliasedConfiguration =
-          | DetoxAliasedConfigurationSingleApp
-          | DetoxAliasedConfigurationMultiApps;
+        type DetoxConfiguration = DetoxConfigurationCommon & (
+            | DetoxConfigurationSingleApp
+            | DetoxConfigurationMultiApps
+            );
 
-        interface DetoxAliasedConfigurationSingleApp {
-            type?: never;
+        interface DetoxConfigurationSingleApp {
             device: DetoxAliasedDevice;
-            app: string | DetoxAppConfig;
+            app: DetoxAliasedApp;
         }
 
-        interface DetoxAliasedConfigurationMultiApps {
-            type?: never;
+        interface DetoxConfigurationMultiApps {
             device: DetoxAliasedDevice;
-            apps: string[];
+            apps: DetoxAliasedApp[];
         }
 
         type DetoxAliasedDevice = string | DetoxDeviceConfig;
 
+        type DetoxAliasedApp = string | DetoxAppConfig;
+
         // endregion DetoxConfig
 
-        // Detox exports all methods from detox global and all of the global constants.
-        interface DetoxInstance {
-            device: Device;
-            element: ElementFacade;
-            waitFor: WaitForFacade;
-            expect: ExpectFacade;
-            by: ByFacade;
-            web: WebFacade;
-        }
+        interface DetoxExportWrapper {
+            readonly device: Device;
 
-        interface DetoxExportWrapper extends DetoxInstance {
-            /**
-             * The setup phase happens inside detox.init(). This is the phase where detox reads its configuration, starts a server, loads its expection library and starts a simulator
-             *
-             * @param configOverride - this object is deep-merged with the selected Detox configuration from .detoxrc
-             * @example
-             * beforeAll(async () => {
-             *   await detox.init();
-             * });
-             */
-            init(configOverride?: Partial<DetoxConfig>, options?: DetoxInitOptions): Promise<void>;
+            readonly element: ElementFacade;
 
-            beforeEach(...args: any[]): Promise<void>;
+            readonly waitFor: WaitForFacade;
 
-            afterEach(...args: any[]): Promise<void>;
+            readonly expect: ExpectFacade;
 
-            /**
-             * The cleanup phase should happen after all the tests have finished.
-             * This is the phase where the Detox server shuts down.
-             *
-             * @example
-             * after(async () => {
-             *  await detox.cleanup();
-             * });
-             */
-            cleanup(): Promise<void>;
+            readonly by: ByFacade;
+
+            readonly web: WebFacade;
+
+            readonly DetoxConstants: {
+                userNotificationTriggers: {
+                    push: 'push';
+                    calendar: 'calendar';
+                    timeInterval: 'timeInterval';
+                    location: 'location';
+                };
+                userActivityTypes: {
+                    searchableItem: string;
+                    browsingWeb: string;
+                },
+                searchableItemActivityIdentifier: string;
+            };
 
             /**
-             * Unstable. API to access an assembled detox config before it gets passed to testRunner
-             * or detox.init(). Use it only if you don't have another option.
-             * @internal
+             * Detox logger instance. Can be used for saving user logs to the general log file.
              */
-            hook(event: 'UNSAFE_configReady', listener: (config: unknown) => void): void;
-        }
+            readonly log: Logger;
 
-        interface DetoxInitOptions {
             /**
-             * By default, Detox exports `device`, `expect`, `element`, `by` and `waitFor`
-             * as global variables. If you want to control their initialization manually,
-             * set this property to `false`.
-             *
-             * This is useful when during E2E tests you also need to run regular expectations
-             * in Node.js. Jest's `expect` for instance, will not be overridden by Detox when
-             * this option is used.
+             * Detox tracer instance. Can be used for building timelines in Google Event Tracing format.
              */
-            initGlobals?: boolean;
+            readonly trace: Tracer;
+
             /**
-             * By default, `await detox.init()` will uninstall and install the app.
-             * If you wish to reuse the existing app for a faster run, set the property to
-             * `false`.
+             * @deprecated
              */
-            reuse?: boolean;
+            readonly traceCall: _TraceCallSignature;
+        }
+
+        /** @internal */
+        type _TraceEventArgs = Record<string, unknown>;
+
+        type TraceEvent = {
+            name?: string;
+            cat?: string;
+            cname?: string;
+            id?: number;
+            args?: _TraceEventArgs;
+        };
+
+        /**
+         * 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>;
+        }
+
+        /** @internal */
+        interface _TraceSectionSignature<T> {
+            (event?: string, args?: _TraceEventArgs): T;
+            (event: TraceEvent): T;
         }
 
+        interface Tracer extends _TraceCallSignature {
+            readonly begin: _TraceSectionSignature<EndHandle<{ cname: string; args: _TraceEventArgs; }>>;
+            readonly end: _TraceSectionSignature<void>;
+
+            /** @deprecated */
+            readonly startSection: _TraceSectionSignature<void>;
+            /** @deprecated */
+            readonly endSection: _TraceSectionSignature<void>;
+        }
+
+        type Logger = {
+            readonly level: DetoxLogLevel;
+
+            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;
+
+            child(context?: Record<string, unknown>): Logger;
+        };
+
+        type DetoxLogLevel = 'fatal' | 'error' | 'warn' | 'info' | 'debug' | 'trace';
+
         type Point2D = {
             x: number,
             y: number,
         }
 
-        /**
-         * @deprecated
-         */
-        type AppLaunchArgsOperationOptions = Partial<{
-            /** Changes the scope of the operation: transient or permanent app launch args */
-            permanent: boolean;
-        }>;
-
         /**
          * A construct allowing for the querying and modification of user arguments passed to an app upon launch by Detox.
          *
@@ -414,20 +453,12 @@ declare global {
              * // }
              */
             modify(modifier: object): this;
-            /**
-             * @deprecated Use {@link AppLaunchArgs#shared} instead.
-             */
-            modify(modifier: object, options: AppLaunchArgsOperationOptions): this;
 
             /**
              * Reset all app-specific launch arguments (back to an empty object).
              * If you need to reset the shared launch args, use {@link AppLaunchArgs#shared}.
              */
             reset(): this;
-            /**
-             * @deprecated Use {@link AppLaunchArgs#shared} instead.
-             */
-            reset(options: AppLaunchArgsOperationOptions): this;
 
             /**
              * Get all currently set launch arguments (including shared ones).
@@ -435,10 +466,6 @@ declare global {
              * Note: mutating the values inside the result object is pointless, as it is immutable.
              */
             get(): object;
-            /**
-             * @deprecated Use {@link AppLaunchArgs#shared} instead.
-             */
-            get(options: AppLaunchArgsOperationOptions): object;
         }
 
         /**
@@ -460,12 +487,10 @@ declare global {
              * 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).
              *
-             * The value will be undefined until the device is properly prepared (i.e. in detox.init())
              */
             id: string;
             /**
              * Holds a descriptive name of the device. Example: emulator-5554 (Pixel_API_29)
-             * The value will be undefined until the device is properly prepared (i.e. in detox.init()).
              */
             name: string;
 
@@ -510,6 +535,15 @@ declare global {
              */
             launchApp(config?: DeviceLaunchAppConfig): Promise<void>;
 
+            /**
+             * Relaunch the app. Convenience method that calls {@link Device#launchApp}
+             * with { newInstance: true } override.
+             *
+             * @param config
+             * @see Device#launchApp
+             */
+            relaunchApp(config?: Omit<DeviceLaunchAppConfig, 'newInstance'>): Promise<void>;
+
             /**
              * Access the user-defined launch-arguments predefined through static scopes such as the Detox configuration file and
              * command-line arguments. This access allows - through dedicated methods, for both value-querying and
@@ -535,6 +569,7 @@ declare global {
              * @see AppLaunchArgs
              */
             appLaunchArgs: AppLaunchArgs;
+
             /**
              * Terminate the app.
              *
@@ -899,11 +934,13 @@ declare global {
              * @example await element(by.text('Product').and(by.id('product_name'));
              */
             and(by: NativeMatcher): NativeMatcher;
+
             /**
              * Find an element by a matcher with a parent matcher
              * @example await element(by.id('Grandson883').withAncestor(by.id('Son883')));
              */
             withAncestor(parentBy: NativeMatcher): NativeMatcher;
+
             /**
              * Find an element by a matcher with a child matcher
              * @example await element(by.id('Son883').withDescendant(by.id('Grandson883')));
@@ -917,6 +954,7 @@ declare global {
 
         interface ExpectFacade {
             (element: NativeElement): Expect;
+
             (webElement: WebElement): WebExpect;
         }
 
@@ -1011,6 +1049,7 @@ declare global {
              * @example await expect(element(by.id('switch'))).toHaveToggleValue(true);
              */
             toHaveToggleValue(value: boolean): R;
+
             /**
              * Expect components like a Switch to have a value ('0' for off, '1' for on).
              * @example await expect(element(by.id('UniqueId533'))).toHaveValue('0');
@@ -1047,6 +1086,7 @@ declare global {
              * @example await waitFor(element(by.text('Text5'))).toBeVisible().whileElement(by.id('ScrollView630')).scroll(50, 'down');
              */
             whileElement(by: NativeMatcher): NativeElement & WaitFor;
+
             // TODO: not sure about & WaitFor - check if we can chain whileElement multiple times
         }
 
@@ -1072,6 +1112,7 @@ declare global {
              */
             longPressAndDrag(duration: number, normalizedPositionX: number, normalizedPositionY: number, targetElement: NativeElement,
                              normalizedTargetPositionX: number, normalizedTargetPositionY: number, speed: Speed, holdDuration: number): Promise<void>;
+
             /**
              * Simulate multiple taps on an element.
              * @param times number of times to tap
@@ -1127,10 +1168,10 @@ declare global {
              * @example await element(by.id('scrollView')).scroll(100, 'up');
              */
             scroll(
-              pixels: number,
-              direction: Direction,
-              startPositionX?: number,
-              startPositionY?: number,
+                pixels: number,
+                direction: Direction,
+                startPositionX?: number,
+                startPositionY?: number
             ): Promise<void>;
 
             /**
@@ -1138,7 +1179,7 @@ declare global {
              * @example await element(by.id('scrollView')).scrollToIndex(10);
              */
             scrollToIndex(
-              index: Number
+                index: Number
             ): Promise<void>;
 
             /**
@@ -1227,7 +1268,7 @@ declare global {
              *   // * on failure, to: <artifacts-location>/✗ Menu items should have Logout/tap on menu.png
              * });
              */
-             takeScreenshot(name: string): Promise<string>;
+            takeScreenshot(name: string): Promise<string>;
 
             /**
              * Gets the native (OS-dependent) attributes of the element.
@@ -1245,7 +1286,7 @@ declare global {
              *    jestExpect(attributes.width).toHaveValue(100);
              * })
              */
-             getAttributes(): Promise<IosElementAttributes | AndroidElementAttributes | { elements: IosElementAttributes[]; }>;
+            getAttributes(): Promise<IosElementAttributes | AndroidElementAttributes | { elements: IosElementAttributes[]; }>;
         }
 
         interface WebExpect<R = Promise<void>> {
@@ -1261,7 +1302,7 @@ declare global {
              * @example
              * await expect(web.element(by.web.id('UniqueId205'))).toHaveText('ExactText');
              */
-            toHaveText(text: string): R
+            toHaveText(text: string): R;
 
             /**
              * Expect the view to exist in the webview DOM tree.
@@ -1282,56 +1323,56 @@ declare global {
         }
 
         interface WebElementActions {
-            tap(): Promise<void>
+            tap(): Promise<void>;
 
             /**
              * @param text to type
              * @param isContentEditable whether its a ContentEditable element, default is false.
              */
-            typeText(text: string, isContentEditable: boolean): Promise<void>
+            typeText(text: string, isContentEditable: boolean): Promise<void>;
 
             /**
              * At the moment not working on content-editable
              * @param text to replace with the old content.
              */
-            replaceText(text: string): Promise<void>
+            replaceText(text: string): Promise<void>;
 
             /**
              * At the moment not working on content-editable
              */
-            clearText(): Promise<void>
+            clearText(): Promise<void>;
 
             /**
              * scrolling to the view, the element top position will be at the top of the screen.
              */
-            scrollToView(): Promise<void>
+            scrollToView(): Promise<void>;
 
             /**
              * Gets the input content
              */
-            getText(): Promise<string>
+            getText(): Promise<string>;
 
             /**
              * Calls the focus function on the element
              */
-            focus(): Promise<void>
+            focus(): Promise<void>;
 
             /**
              * Selects all the input content, works on ContentEditable at the moment.
              */
-            selectAllText(): Promise<void>
+            selectAllText(): Promise<void>;
 
             /**
              * Moves the input cursor / caret to the end of the content, works on ContentEditable at the moment.
              */
-            moveCursorToEnd(): Promise<void>
+            moveCursorToEnd(): Promise<void>;
 
             /**
              * Running a script on the element
              * @param script a method that accept the element as its first arg
              * @example function foo(element) { console.log(element); }
              */
-            runScript(script: string): Promise<any>
+            runScript(script: string): Promise<any>;
 
             /**
              * Running a script on the element that accept args
@@ -1445,25 +1486,6 @@ declare global {
             languageAndLocale?: LanguageAndLocale;
         }
 
-        interface CircusTestEventListenerBase {
-            handleTestEvent(event: any, state: any): Promise<void>;
-        }
-
-        interface DetoxCircus {
-            /**
-             * A get function that Enables access to this instance (single in each worker's scope)
-             */
-            getEnv(): {
-                /**
-                 * Registers a listener such as an adapter or reporter
-                 * @example
-                 * detoxCircus.getEnv().addEventsListener(adapter)
-                 * detoxCircus.getEnv().addEventsListener(assignReporter)
-                 */
-                addEventsListener(listener: CircusTestEventListenerBase): void
-            };
-        }
-
         // Element Attributes Shared Among iOS and Android
         interface ElementAttributes {
             /**