codeceptjs 3.1.0 → 3.2.0

package/typings/types.d.ts

@@ -321,11 +321,11 @@ declare namespace CodeceptJS {
          * ```js
          * I.removeApp('appName', 'com.example.android.apis');
          * ```
-         * @param bundleId - String  ID of bundle
          *
          * Appium: support only Android
+         * @param [bundleId] - ID of bundle
          */
-        removeApp(appId: string, bundleId: string): void;
+        removeApp(appId: string, bundleId?: string): void;
         /**
          * Check current activity on an Android device.
          *
@@ -522,11 +522,12 @@ declare namespace CodeceptJS {
          * // or by pressing key
          * I.hideDeviceKeyboard('pressKey', 'Done');
          * ```
-         * @param strategy - desired strategy to close keyboard (‘tapOutside’ or ‘pressKey’)
          *
          * Appium: support Android and iOS
+         * @param [strategy] - Desired strategy to close keyboard (‘tapOutside’ or ‘pressKey’)
+         * @param [key] - Optional key
          */
-        hideDeviceKeyboard(strategy: 'tapOutside' | 'pressKey'): void;
+        hideDeviceKeyboard(strategy?: 'tapOutside' | 'pressKey', key?: string): void;
         /**
          * Send a key event to the device.
          * List of keys: https://developer.android.com/reference/android/view/KeyEvent.html
@@ -682,8 +683,9 @@ declare namespace CodeceptJS {
          * ```
          *
          * Appium: support Android and iOS
+         * @param actions - Array of touch actions
          */
-        touchPerform(): void;
+        touchPerform(actions: any[]): void;
         /**
          * Pulls a file from the device.
          *
@@ -886,6 +888,45 @@ declare namespace CodeceptJS {
          * @returns attribute value
          */
         grabTextFrom(locator: CodeceptJS.LocatorOrString): Promise<string>;
+        /**
+         * Grab number of visible elements by locator.
+         * Resumes test execution, so **should be used inside async function with `await`** operator.
+         *
+         * ```js
+         * let numOfElements = await I.grabNumberOfVisibleElements('p');
+         * ```
+         * @param locator - located by CSS|XPath|strict locator.
+         * @returns number of visible elements
+         */
+        grabNumberOfVisibleElements(locator: CodeceptJS.LocatorOrString): Promise<number>;
+        /**
+         * Can be used for apps only with several values ("contentDescription", "text", "className", "resourceId")
+         *
+         * Retrieves an attribute from an element located by CSS or XPath and returns it to test.
+         * Resumes test execution, so **should be used inside async with `await`** operator.
+         * If more than one element is found - attribute of first element is returned.
+         *
+         * ```js
+         * let hint = await I.grabAttributeFrom('#tooltip', 'title');
+         * ```
+         * @param locator - element located by CSS|XPath|strict locator.
+         * @param attr - attribute name.
+         * @returns attribute value
+         */
+        grabAttributeFrom(locator: CodeceptJS.LocatorOrString, attr: string): Promise<string>;
+        /**
+         * Can be used for apps only with several values ("contentDescription", "text", "className", "resourceId")
+         * Retrieves an array of attributes from elements located by CSS or XPath and returns it to test.
+         * Resumes test execution, so **should be used inside async with `await`** operator.
+         *
+         * ```js
+         * let hints = await I.grabAttributeFromAll('.tooltip', 'title');
+         * ```
+         * @param locator - element located by CSS|XPath|strict locator.
+         * @param attr - attribute name.
+         * @returns attribute value
+         */
+        grabAttributeFromAll(locator: CodeceptJS.LocatorOrString, attr: string): Promise<string[]>;
         /**
          * Retrieves an array of value from a form located by CSS or XPath and returns it to test.
          * Resumes test execution, so **should be used inside async function with `await`** operator.
@@ -909,6 +950,16 @@ declare namespace CodeceptJS {
          * @returns attribute value
          */
         grabValueFrom(locator: CodeceptJS.LocatorOrString): Promise<string>;
+        /**
+         * Saves a screenshot to ouput folder (set in codecept.json or codecept.conf.js).
+         * Filename is relative to output folder.
+         *
+         * ```js
+         * I.saveScreenshot('debug.png');
+         * ```
+         * @param fileName - file name to save.
+         */
+        saveScreenshot(fileName: string): void;
         /**
          * Scroll element into viewport.
          *
@@ -1096,7 +1147,7 @@ declare namespace CodeceptJS {
          * I.seeFileNameMatching('.pdf');
          * ```
          */
-        seeFileNameMatching(): void;
+        seeFileNameMatching(text: string): void;
         /**
          * Checks that file found by `seeFile` includes a text.
          */
@@ -2368,6 +2419,8 @@ declare namespace CodeceptJS {
      * * `restart`: (optional, default: true) - restart browser between tests.
      * * `disableScreenshots`: (optional, default: false)  - don't save screenshot on failure.
      * * `emulate`: (optional, default: {}) launch browser in device emulation mode.
+     * * `video`: (optional, default: false) enables video recording for failed tests; videos are saved into `output/videos` folder
+     * * `trace`: (optional, default: false) record [tracing information](https://playwright.dev/docs/trace-viewer) with screenshots and snapshots.
      * * `fullPageScreenshots` (optional, default: false) - make full page screenshots on failure.
      * * `uniqueScreenshotNames`: (optional, default: false)  - option to prevent screenshot override if you have scenarios with the same name in different suites.
      * * `keepBrowserState`: (optional, default: false) - keep browser state between tests when `restart` is set to false.
@@ -2380,10 +2433,27 @@ declare namespace CodeceptJS {
      * * `basicAuth`: (optional) the basic authentication to pass to base url. Example: {username: 'username', password: 'password'}
      * * `windowSize`: (optional) default window size. Set a dimension like `640x480`.
      * * `userAgent`: (optional) user-agent string.
+     * * `locale`: (optional) locale string. Example: 'en-GB', 'de-DE', 'fr-FR', ...
      * * `manualStart`: (optional, default: false) - do not start browser before a test, start it manually inside a helper with `this.helpers["Playwright"]._startBrowser()`.
      * * `chromium`: (optional) pass additional chromium options
      * * `electron`: (optional) pass additional electron options
      *
+     * #### Video Recording Customization
+     *
+     * By default, video is saved to `output/video` dir. You can customize this path by passing `dir` option to `recordVideo` option.
+     *
+     * * `video`: enables video recording for failed tests; videos are saved into `output/videos` folder
+     * * `keepVideoForPassedTests`: - save videos for passed tests
+     * * `recordVideo`: [additional options for videos customization](https://playwright.dev/docs/next/api/class-browser#browser-new-context)
+     *
+     * #### Trace Recording Customization
+     *
+     * Trace recording provides a complete information on test execution and includes DOM snapshots, screenshots, and network requests logged during run.
+     * Traces will be saved to `output/trace`
+     *
+     * * `trace`: enables trace recording for failed tests; trace are saved into `output/trace` folder
+     * * `keepTraceForPassedTests`: - save trace for passed tests
+     *
      * #### Example #1: Wait for 0 network connections.
      *
      * ```js
@@ -2435,7 +2505,7 @@ declare namespace CodeceptJS {
      *      Playwright: {
      *        url: "http://localhost",
      *        chromium: {
-     *          browserWSEndpoint: { wsEndpoint: 'ws://localhost:9222/devtools/browser/c5aa6160-b5bc-4d53-bb49-6ecb36cd2e0a' }
+     *          browserWSEndpoint: 'ws://localhost:9222/devtools/browser/c5aa6160-b5bc-4d53-bb49-6ecb36cd2e0a'
      *        }
      *      }
      *    }
@@ -2481,6 +2551,19 @@ declare namespace CodeceptJS {
      * }
      * ```
      *
+     * #### Example #7: Launch test with a specifc user locale
+     *
+     * ```js
+     * {
+     *  helpers: {
+     *   Playwright : {
+     *     url: "http://localhost",
+     *     locale: "fr-FR",
+     *   }
+     *  }
+     * }
+     * ```
+     *
      * Note: When connecting to remote browser `show` and specific `chrome` options (e.g. `headless` or `devtools`) are ignored.
      *
      * ## Access From Helpers
@@ -3791,11 +3874,11 @@ declare namespace CodeceptJS {
          */
         waitForRequest(urlOrPredicate: string | ((...params: any[]) => any), sec?: number): void;
         /**
-         * Waits for a network request.
+         * Waits for a network response.
          *
          * ```js
          * I.waitForResponse('http://example.com/resource');
-         * I.waitForResponse(request => request.url() === 'http://example.com' && request.method() === 'GET');
+         * I.waitForResponse(response => response.url() === 'https://example.com' && response.status() === 200);
          * ```
          * @param [sec = null] - number of seconds to wait
          */
@@ -3834,18 +3917,6 @@ declare namespace CodeceptJS {
          * See [Playwright's reference](https://playwright.dev/docs/api/class-page?_highlight=waitfornavi#pagewaitfornavigationoptions)
          */
         waitForNavigation(opts: any): void;
-        /**
-         * Waits for a function to return true (waits for 1sec by default).
-         *
-         * ```js
-         * I.waitUntil(() => window.requests == 0);
-         * I.waitUntil(() => window.requests == 0, 5);
-         * ```
-         * @param fn - function which is executed in browser context.
-         * @param [sec = 1] - (optional, `1` by default) time in seconds to wait
-         * @param [timeoutMsg = ''] - message to show in case of timeout fail.
-         */
-        waitUntil(fn: ((...params: any[]) => any) | string, sec?: number, timeoutMsg?: string, interval?: number): void;
         /**
          * Waits for an element to become not attached to the DOM on a page (by default waits for 1sec).
          * Element can be located by CSS or XPath.
@@ -3902,6 +3973,29 @@ declare namespace CodeceptJS {
          * @returns Element bounding rectangle
          */
         grabElementBoundingRect(locator: LocatorOrString, elementSize?: string): Promise<DOMRect> | Promise<number>;
+        /**
+         * Mocks network request using [`browserContext.route`](https://playwright.dev/docs/api/class-browsercontext#browser-context-route) of Playwright
+         *
+         * ```js
+         * I.mockRoute(/(\.png$)|(\.jpg$)/, route => route.abort());
+         * ```
+         * This method allows intercepting and mocking requests & responses. [Learn more about it](https://playwright.dev/docs/network#handle-requests)
+         * @param [url] - URL, regex or pattern for to match URL
+         * @param [handler] - a function to process request
+         */
+        mockRoute(url?: string, handler?: (...params: any[]) => any): void;
+        /**
+         * Stops network mocking created by `mockRoute`.
+         *
+         * ```js
+         * I.stopMockingRoute(/(\.png$)|(\.jpg$)/);
+         * I.stopMockingRoute(/(\.png$)|(\.jpg$)/, previouslySetHandler);
+         * ```
+         * If no handler is passed, all mock requests for the rote are disabled.
+         * @param [url] - URL, regex or pattern for to match URL
+         * @param [handler] - a function to process request
+         */
+        stopMockingRoute(url?: string, handler?: (...params: any[]) => any): void;
     }
     /**
      * This helper works the same as MockRequest helper. It has been included for backwards compatibility
@@ -4530,11 +4624,12 @@ declare namespace CodeceptJS {
         /**
          * Checks that title is equal to provided one.
          *
-         * ```js
-         * I.seeTitleEquals('Test title.');
-         * ```
+         *  ```js
+         *  I.seeTitleEquals('Test title.');
+         *  ```
+         * @param text - value to check.
          */
-        seeTitleEquals(): void;
+        seeTitleEquals(text: string): void;
         /**
          * Checks that title does not contain text.
          *
@@ -5064,18 +5159,6 @@ declare namespace CodeceptJS {
          * @param [sec = null] - (optional, `1` by default) time in seconds to wait
          */
         waitForFunction(fn: string | ((...params: any[]) => any), argsOrSec?: any[] | number, sec?: number): void;
-        /**
-         * Waits for a function to return true (waits for 1sec by default).
-         *
-         * ```js
-         * I.waitUntil(() => window.requests == 0);
-         * I.waitUntil(() => window.requests == 0, 5);
-         * ```
-         * @param fn - function which is executed in browser context.
-         * @param [sec = 1] - (optional, `1` by default) time in seconds to wait
-         * @param [timeoutMsg = ''] - message to show in case of timeout fail.
-         */
-        waitUntil(fn: ((...params: any[]) => any) | string, sec?: number, timeoutMsg?: string, interval?: number): void;
         /**
          * Waiting for the part of the URL to match the expected. Useful for SPA to understand that page was changed.
          *
@@ -5294,6 +5377,7 @@ declare namespace CodeceptJS {
      *    }
      * }
      * ```
+     * > Note: When connecting to remote browser `show` and specific `chrome` options (e.g. `headless` or `devtools`) are ignored.
      *
      * #### Example #5: Target URL with provided basic authentication
      *
@@ -5308,10 +5392,25 @@ declare namespace CodeceptJS {
      *    }
      * }
      * ```
+     * #### Troubleshooting
      *
+     * Error Message:  `No usable sandbox!`
+     *
+     * When running Puppeteer on CI try to disable sandbox if you see that message
+     *
+     * ```
+     * helpers: {
+     *  Puppeteer: {
+     *     url: 'http://localhost',
+     *     show: false,
+     *     chrome: {
+     *       args: ['--no-sandbox', '--disable-setuid-sandbox']
+     *     }
+     *   },
+     * }
+     * ```
      *
      *
-     * Note: When connecting to remote browser `show` and specific `chrome` options (e.g. `headless` or `devtools`) are ignored.
      *
      * ## Access From Helpers
      *
@@ -5526,11 +5625,12 @@ declare namespace CodeceptJS {
         /**
          * Checks that title is equal to provided one.
          *
-         * ```js
-         * I.seeTitleEquals('Test title.');
-         * ```
+         *  ```js
+         *  I.seeTitleEquals('Test title.');
+         *  ```
+         * @param text - value to check.
          */
-        seeTitleEquals(): void;
+        seeTitleEquals(text: string): void;
         /**
          * Checks that title does not contain text.
          *
@@ -6739,18 +6839,6 @@ declare namespace CodeceptJS {
          * See [Pupeteer's reference](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#pagewaitfornavigationoptions)
          */
         waitForNavigation(opts: any): void;
-        /**
-         * Waits for a function to return true (waits for 1sec by default).
-         *
-         * ```js
-         * I.waitUntil(() => window.requests == 0);
-         * I.waitUntil(() => window.requests == 0, 5);
-         * ```
-         * @param fn - function which is executed in browser context.
-         * @param [sec = 1] - (optional, `1` by default) time in seconds to wait
-         * @param [timeoutMsg = ''] - message to show in case of timeout fail.
-         */
-        waitUntil(fn: ((...params: any[]) => any) | string, sec?: number, timeoutMsg?: string, interval?: number): void;
         /**
          * Waits for an element to become not attached to the DOM on a page (by default waits for 1sec).
          * Element can be located by CSS or XPath.
@@ -6850,8 +6938,9 @@ declare namespace CodeceptJS {
     class REST {
         /**
          * Executes axios request
+         * @returns response
          */
-        _executeRequest(request: any): void;
+        _executeRequest(request: any): Promise<any>;
         /**
          * Generates url based on format sent (takes endpoint + url if latter lacks 'http')
          */
@@ -6862,8 +6951,9 @@ declare namespace CodeceptJS {
          * ```js
          * I.setRequestTimeout(10000); // In milliseconds
          * ```
+         * @param newTimeout - timeout in milliseconds
          */
-        setRequestTimeout(): void;
+        setRequestTimeout(newTimeout: number): void;
         /**
          * Send GET request to REST API
          *
@@ -6871,8 +6961,9 @@ declare namespace CodeceptJS {
          * I.sendGetRequest('/api/users.json');
          * ```
          * @param [headers = {}] - the headers object to be sent. By default it is sent as an empty object
+         * @returns response
          */
-        sendGetRequest(url: any, headers?: any): void;
+        sendGetRequest(url: any, headers?: any): Promise<any>;
         /**
          * Sends POST request to API.
          *
@@ -6885,8 +6976,9 @@ declare namespace CodeceptJS {
          * ```
          * @param [payload = {}] - the payload to be sent. By default it is sent as an empty object
          * @param [headers = {}] - the headers object to be sent. By default it is sent as an empty object
+         * @returns response
          */
-        sendPostRequest(url: any, payload?: any, headers?: any): void;
+        sendPostRequest(url: any, payload?: any, headers?: any): Promise<any>;
         /**
          * Sends PATCH request to API.
          *
@@ -6899,8 +6991,9 @@ declare namespace CodeceptJS {
          * ```
          * @param [payload = {}] - the payload to be sent. By default it is sent as an empty object
          * @param [headers = {}] - the headers object to be sent. By default it is sent as an empty object
+         * @returns response
          */
-        sendPatchRequest(url: string, payload?: any, headers?: any): void;
+        sendPatchRequest(url: string, payload?: any, headers?: any): Promise<any>;
         /**
          * Sends PUT request to API.
          *
@@ -6913,8 +7006,9 @@ declare namespace CodeceptJS {
          * ```
          * @param [payload = {}] - the payload to be sent. By default it is sent as an empty object
          * @param [headers = {}] - the headers object to be sent. By default it is sent as an empty object
+         * @returns response
          */
-        sendPutRequest(url: string, payload?: any, headers?: any): void;
+        sendPutRequest(url: string, payload?: any, headers?: any): Promise<any>;
         /**
          * Sends DELETE request to API.
          *
@@ -6922,8 +7016,9 @@ declare namespace CodeceptJS {
          * I.sendDeleteRequest('/api/users/1');
          * ```
          * @param [headers = {}] - the headers object to be sent. By default it is sent as an empty object
+         * @returns response
          */
-        sendDeleteRequest(url: any, headers?: any): void;
+        sendDeleteRequest(url: any, headers?: any): Promise<any>;
     }
     /**
      * SeleniumWebdriver helper is based on the official [Selenium Webdriver JS](https://www.npmjs.com/package/selenium-webdriver)
@@ -8308,7 +8403,7 @@ declare namespace CodeceptJS {
          * ```
          * @param timeouts - WebDriver timeouts object.
          */
-        defineTimeout(timeouts: WebdriverIO.Timeouts): void;
+        defineTimeout(timeouts: any): void;
         /**
          * Opens a web page in a browser. Requires relative or absolute url.
          * If url starts with `/`, opens a web page of a site defined in `url` config parameter.
@@ -8656,8 +8751,6 @@ declare namespace CodeceptJS {
          * @param locator - element located by CSS|XPath|strict locator.
          * @param attr - attribute name.
          * @returns attribute value
-         *
-         * Appium: can be used for apps only with several values ("contentDescription", "text", "className", "resourceId")
          */
         grabAttributeFromAll(locator: CodeceptJS.LocatorOrString, attr: string): Promise<string[]>;
         /**
@@ -8671,8 +8764,6 @@ declare namespace CodeceptJS {
          * @param locator - element located by CSS|XPath|strict locator.
          * @param attr - attribute name.
          * @returns attribute value
-         *
-         * Appium: can be used for apps only with several values ("contentDescription", "text", "className", "resourceId")
          */
         grabAttributeFrom(locator: CodeceptJS.LocatorOrString, attr: string): Promise<string>;
         /**
@@ -9532,18 +9623,6 @@ declare namespace CodeceptJS {
          * @param [sec = null] - (optional, `1` by default) time in seconds to wait
          */
         waitForFunction(fn: string | ((...params: any[]) => any), argsOrSec?: any[] | number, sec?: number): void;
-        /**
-         * Waits for a function to return true (waits for 1sec by default).
-         *
-         * ```js
-         * I.waitUntil(() => window.requests == 0);
-         * I.waitUntil(() => window.requests == 0, 5);
-         * ```
-         * @param fn - function which is executed in browser context.
-         * @param [sec = 1] - (optional, `1` by default) time in seconds to wait
-         * @param [timeoutMsg = ''] - message to show in case of timeout fail.
-         */
-        waitUntil(fn: ((...params: any[]) => any) | string, sec?: number, timeoutMsg?: string, interval?: number): void;
         /**
          * Switches frame or in case of null locator reverts to parent.
          *
@@ -9695,7 +9774,12 @@ declare namespace CodeceptJS {
          * add print comment method`
          */
         say(msg: string, color?: string): Promise<any> | undefined;
-        retry(opts: any): this;
+        /**
+         * set the maximum execution time for the next step
+         * @param timeout - step timeout in seconds
+         */
+        limitTime(timeout: number): this;
+        retry(opts?: any): this;
     }
     /**
      * Create CodeceptJS runner.
@@ -9839,6 +9923,34 @@ declare namespace CodeceptJS {
         xadd(array: any[]): void;
         filter(func: (...params: any[]) => any): void;
     }
+    /**
+     * DataTableArgument class to store the Cucumber data table from
+     * a step as an object with methods that can be used to access the data.
+     */
+    class DataTableArgument {
+        constructor(gherkinDataTable: any);
+        /**
+         * Returns the table as a 2-D array
+         */
+        raw(): string[][];
+        /**
+         * Returns the table as a 2-D array, without the first row
+         */
+        rows(): string[][];
+        /**
+         * Returns an array of objects where each row is converted to an object (column header is the key)
+         */
+        hashes(): any[];
+        /**
+         * Returns an object where each row corresponds to an entry
+         * (first column is the key, second column is the value)
+         */
+        rowsHash(): Record<string, string>;
+        /**
+         * Transposed the data
+         */
+        transpose(): void;
+    }
     namespace event {
         const dispatcher: NodeJS.EventEmitter;
         const test: {
@@ -9935,6 +10047,7 @@ declare namespace CodeceptJS {
         var pause: typeof CodeceptJS.pause;
         var within: typeof CodeceptJS.within;
         var dataTable: typeof CodeceptJS.DataTable;
+        var dataTableArgument: typeof CodeceptJS.DataTableArgument;
         var store: typeof CodeceptJS.store;
         var locator: typeof CodeceptJS.Locator;
     }
@@ -10020,6 +10133,7 @@ declare namespace CodeceptJS {
         isCustom(): boolean;
         isStrict(): boolean;
         isAccessibilityId(): boolean;
+        isBasic(): boolean;
         toXPath(): string;
         or(locator: CodeceptJS.LocatorOrString): Locator;
         find(locator: CodeceptJS.LocatorOrString): Locator;
@@ -10040,11 +10154,11 @@ declare namespace CodeceptJS {
         /**
          * Filters to modify locators
          */
-        static filters: any;
+        static filters: ((arg0: CodeceptJS.LocatorOrString, arg1: Locator) => void)[];
         /**
          * Appends new `Locator` filter to an `Locator.filters` array, and returns the new length of the array.
          */
-        static addFilter(): void;
+        static addFilter(fn: (...params: any[]) => any): number;
     }
     namespace output {
         var stepShift: number;
@@ -10134,7 +10248,7 @@ declare namespace CodeceptJS {
          *     true: it will retries if `retryOpts` set.
          *     false: ignore `retryOpts` and won't retry.
          */
-        add(taskName: string | ((...params: any[]) => any), fn?: (...params: any[]) => any, force?: boolean, retry?: boolean): Promise<any> | undefined;
+        add(taskName: string | ((...params: any[]) => any), fn?: (...params: any[]) => any, force?: boolean, retry?: boolean, timeout?: number): Promise<any> | undefined;
         retry(opts: any): any;
         catch(customErrFn?: (...params: any[]) => any): Promise<any>;
         catchWithoutStop(customErrFn: (...params: any[]) => any): Promise<any>;
@@ -10197,6 +10311,7 @@ declare namespace CodeceptJS {
         args: any[];
         metaStep: MetaStep;
         stack: string;
+        totalTimeout: number;
         setTrace(): void;
         setArguments(args: any[]): void;
         run(...args: any[]): any;
@@ -10218,6 +10333,7 @@ declare namespace CodeceptJS {
      */
     namespace store {
         var debugMode: boolean;
+        var timeouts: boolean;
     }
     /**
      * Describe a "suite" with the given `title`