codeceptjs 3.0.6 → 3.1.2

package/typings/types.d.ts

@@ -886,6 +886,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 +948,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.
          *
@@ -2363,11 +2412,13 @@ declare namespace CodeceptJS {
      * This helper should be configured in codecept.json or codecept.conf.js
      *
      * * `url`: base url of website to be tested
-     * * `browser`: a browser to test on, either: `chromium`, `firefox`, `webkit`. Default: chromium.
+     * * `browser`: a browser to test on, either: `chromium`, `firefox`, `webkit`, `electron`. Default: chromium.
      * * `show`: (optional, default: false) - show browser window.
      * * `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.
@@ -2382,6 +2433,23 @@ declare namespace CodeceptJS {
      * * `userAgent`: (optional) user-agent string.
      * * `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.
      *
@@ -2426,7 +2494,7 @@ declare namespace CodeceptJS {
      * }
      * ```
      *
-     * #### Example #4: Connect to remote browser by specifying [websocket endpoint](https://chromedevtools.github.io/devtools-protocol/#how-do-i-access-the-browser-target)
+     * #### Example #4: Connect to remote browser by specifying [websocket endpoint](https://playwright.dev/docs/api/class-browsertype#browsertypeconnectparams)
      *
      * ```js
      * {
@@ -2434,7 +2502,7 @@ declare namespace CodeceptJS {
      *      Playwright: {
      *        url: "http://localhost",
      *        chromium: {
-     *          browserWSEndpoint: "ws://localhost:9222/devtools/browser/c5aa6160-b5bc-4d53-bb49-6ecb36cd2e0a"
+     *          browserWSEndpoint: 'ws://localhost:9222/devtools/browser/c5aa6160-b5bc-4d53-bb49-6ecb36cd2e0a'
      *        }
      *      }
      *    }
@@ -2452,6 +2520,7 @@ declare namespace CodeceptJS {
      *      url: "http://localhost",
      *      show: true // headless mode not supported for extensions
      *      chromium: {
+     *        userDataDir: '/tmp/playwright-tmp', // necessary to launch the browser in normal mode instead of incognito,
      *        args: [
      *           `--disable-extensions-except=${pathToExtension}`,
      *           `--load-extension=${pathToExtension}`
@@ -3466,6 +3535,10 @@ declare namespace CodeceptJS {
          * @param [arg] - optional argument to pass to the function
          */
         executeScript(fn: string | ((...params: any[]) => any), arg?: any): Promise<any>;
+        /**
+         * Grab Locator if called within Context
+         */
+        _contextLocator(locator: any): void;
         /**
          * Retrieves a text 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.
@@ -3896,6 +3969,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
@@ -5288,6 +5384,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
      *
@@ -5302,10 +5399,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
      *
@@ -6844,8 +6956,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')
          */
@@ -6865,8 +6978,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.
          *
@@ -6879,8 +6993,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.
          *
@@ -6893,8 +7008,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.
          *
@@ -6907,8 +7023,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.
          *
@@ -6916,8 +7033,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)
@@ -8451,6 +8569,7 @@ declare namespace CodeceptJS {
          * @param value - text value to fill.
          *
          * {{ react }}
+         * {{ custom }}
          */
         fillField(field: CodeceptJS.LocatorOrString, value: CodeceptJS.StringOrSecret): void;
         /**
@@ -8649,8 +8768,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[]>;
         /**
@@ -8664,8 +8781,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>;
         /**
@@ -9753,7 +9868,7 @@ declare namespace CodeceptJS {
         /**
          * Get current config.
          */
-        static get(key: string, val: any): any;
+        static get(key?: string, val?: any): any;
         /**
          * Appends values to current config
          */
@@ -9868,6 +9983,7 @@ declare namespace CodeceptJS {
             before: 'global.before';
             after: 'global.after';
             result: 'global.result';
+            failures: 'global.failures';
         };
         const multiple: {
             before: 'multiple.before';
@@ -10012,6 +10128,7 @@ declare namespace CodeceptJS {
         isCustom(): boolean;
         isStrict(): boolean;
         isAccessibilityId(): boolean;
+        isBasic(): boolean;
         toXPath(): string;
         or(locator: CodeceptJS.LocatorOrString): Locator;
         find(locator: CodeceptJS.LocatorOrString): Locator;
@@ -10048,7 +10165,7 @@ declare namespace CodeceptJS {
          * Print information for a process
          * Used in multiple-run
          */
-        function process(process: string): string;
+        function process(process: string | null): string;
         /**
          * Print information in --debug mode
          */
@@ -10149,6 +10266,10 @@ declare namespace CodeceptJS {
          * Get a list of all chained tasks
          */
         scheduled(): string;
+        /**
+         * Get the queue id
+         */
+        getQueueId(): number;
         /**
          * Get a state of current queue and tasks
          */