codeceptjs 3.3.7 → 3.4.0-beta.1

package/typings/types.d.ts

@@ -42,8 +42,8 @@ declare namespace CodeceptJS {
      * ```js
      * // tests/factories/posts.js
      *
-     * const Factory = require('rosie').Factory;
-     * const faker = require('@faker-js/faker');
+     * const { Factory } = require('rosie');
+     * const { faker } = require('@faker-js/faker');
      *
      * module.exports = new Factory()
      *    // no need to set id, it will be set by REST API
@@ -190,10 +190,10 @@ declare namespace CodeceptJS {
          * I.have('user', { }, { age: 33, height: 55 })
          * ```
          * @param factory - factory to use
-         * @param params - predefined parameters
-         * @param options - options for programmatically generate the attributes
+         * @param [params] - predefined parameters
+         * @param [options] - options for programmatically generate the attributes
          */
-        have(factory: any, params: any, options: any): Promise<any>;
+        have(factory: any, params?: any, options?: any): Promise<any>;
         /**
          * Generates bunch of records and saves multiple API requests to store them.
          *
@@ -208,7 +208,7 @@ declare namespace CodeceptJS {
          * I.haveMultiple('post', 3, { author: 'davert' }, { publish_date: '01.01.1997' });
          * ```
          */
-        haveMultiple(factory: any, times: any, params: any, options: any): void;
+        haveMultiple(factory: any, times: any, params?: any, options?: any): void;
         /**
          * Executes request to create a record in API.
          * Can be replaced from a in custom helper.
@@ -1153,10 +1153,10 @@ declare namespace CodeceptJS {
          */
         seeFile(name: string): void;
         /**
-         * Waits for file to be present in current directory.
+         * Waits for the file to be present in the current directory.
          *
          * ```js
-         * I.handleDownloads();
+         * I.handleDownloads('downloads/largeFilesName.txt');
          * I.click('Download large File');
          * I.amInPath('output/downloads');
          * I.waitForFile('largeFilesName.txt', 10); // wait 10 seconds for file
@@ -1340,8 +1340,8 @@ declare namespace CodeceptJS {
      * ```js
      * // tests/factories/users.js
      *
-     * const Factory = require('rosie').Factory;
-     * const faker = require('@faker-js/faker');
+     * const { Factory } = require('rosie').Factory;
+     * const { faker } = require('@faker-js/faker');
      *
      * // Used with a constructor function passed to Factory, so that the final build
      * // object matches the necessary pattern to be sent as the variables object.
@@ -2679,136 +2679,74 @@ declare namespace CodeceptJS {
      * ## Configuration
      *
      * This helper should be configured in codecept.conf.js
+     * @property url - base url of website to be tested
+     * @property [browser] - a browser to test on, either: `chromium`, `firefox`, `webkit`, `electron`. Default: chromium.
+     * @property [show = false] - show browser window.
+     * @property [restart = false] - restart strategy between tests. Possible values:
+     *   * 'context' or **false** - restarts [browser context](https://playwright.dev/docs/api/class-browsercontext) but keeps running browser. Recommended by Playwright team to keep tests isolated.
+     *   * 'browser' or **true** - closes browser and opens it again between tests.
+     *   * 'session' or 'keep' - keeps browser context and session, but cleans up cookies and localStorage between tests. The fastest option when running tests in windowed mode. Works with `keepCookies` and `keepBrowserState` options. This behavior was default before CodeceptJS 3.1
+     * @property [timeout = 1000] - -  [timeout](https://playwright.dev/docs/api/class-page#page-set-default-timeout) in ms of all Playwright actions .
+     * @property [disableScreenshots = false] - don't save screenshot on failure.
+     * @property [emulate] - browser in device emulation mode.
+     * @property [video = false] - enables video recording for failed tests; videos are saved into `output/videos` folder
+     * @property [keepVideoForPassedTests = false] - save videos for passed tests; videos are saved into `output/videos` folder
+     * @property [trace = false] - record [tracing information](https://playwright.dev/docs/trace-viewer) with screenshots and snapshots.
+     * @property [keepTraceForPassedTests = false] - save trace for passed tests.
+     * @property [fullPageScreenshots = false] - make full page screenshots on failure.
+     * @property [uniqueScreenshotNames = false] - option to prevent screenshot override if you have scenarios with the same name in different suites.
+     * @property [keepBrowserState = false] - keep browser state between tests when `restart` is set to 'session'.
+     * @property [keepCookies = false] - keep cookies between tests when `restart` is set to 'session'.
+     * @property [waitForAction] - how long to wait after click, doubleClick or PressKey actions in ms. Default: 100.
+     * @property [waitForNavigation] - When to consider navigation succeeded. Possible options: `load`, `domcontentloaded`, `networkidle`. Choose one of those options is possible. See [Playwright API](https://playwright.dev/docs/api/class-page#page-wait-for-navigation).
+     * @property [pressKeyDelay = 10] - Delay between key presses in ms. Used when calling Playwrights page.type(...) in fillField/appendField
+     * @property [getPageTimeout] - config option to set maximum navigation time in milliseconds.
+     * @property [waitForTimeout] - default wait* timeout in ms. Default: 1000.
+     * @property [basicAuth] - the basic authentication to pass to base url. Example: {username: 'username', password: 'password'}
+     * @property [windowSize] - default window size. Set a dimension like `640x480`.
+     * @property [colorScheme] - default color scheme. Possible values: `dark` | `light` | `no-preference`.
+     * @property [userAgent] - user-agent string.
+     * @property [locale] - locale string. Example: 'en-GB', 'de-DE', 'fr-FR', ...
+     * @property [manualStart] - do not start browser before a test, start it manually inside a helper with `this.helpers["Playwright"]._startBrowser()`.
+     * @property [chromium] - pass additional chromium options
+     * @property [firefox] - pass additional firefox options
+     * @property [electron] - (pass additional electron options
+     * @property [channel] - (While Playwright can operate against the stock Google Chrome and Microsoft Edge browsers available on the machine. In particular, current Playwright version will support Stable and Beta channels of these browsers. See [Google Chrome & Microsoft Edge](https://playwright.dev/docs/browsers/#google-chrome--microsoft-edge).
+     * @property [ignoreLog] - An array with console message types that are not logged to debug log. Default value is `['warning', 'log']`. E.g. you can set `[]` to log all messages. See all possible [values](https://playwright.dev/docs/api/class-consolemessage#console-message-type).
+     * @property [ignoreHTTPSErrors] - Allows access to untrustworthy pages, e.g. to a page with an expired certificate. Default value is `false`
      */
     type PlaywrightConfig = {
-        /**
-         * base url of website to be tested
-         */
         url: string;
-        /**
-         * a browser to test on, either: `chromium`, `firefox`, `webkit`, `electron`. Default: chromium.
-         */
         browser?: string;
-        /**
-         * show browser window.
-         */
         show?: boolean;
-        /**
-         * restart strategy between tests. Possible values:
-          * 'context' or **false** - restarts [browser context](https://playwright.dev/docs/api/class-browsercontext) but keeps running browser. Recommended by Playwright team to keep tests isolated.
-          * 'browser' or **true** - closes browser and opens it again between tests.
-          * 'session' or 'keep' - keeps browser context and session, but cleans up cookies and localStorage between tests. The fastest option when running tests in windowed mode. Works with `keepCookies` and `keepBrowserState` options. This behavior was default before CodeceptJS 3.1
-         */
         restart?: string | boolean;
-        /**
-         * -  [timeout](https://playwright.dev/docs/api/class-page#page-set-default-timeout) in ms of all Playwright actions .
-         * @defaultValue 1000
-         */
         timeout?: number;
-        /**
-         * don't save screenshot on failure.
-         */
         disableScreenshots?: boolean;
-        /**
-         * browser in device emulation mode.
-         */
         emulate?: any;
-        /**
-         * enables video recording for failed tests; videos are saved into `output/videos` folder
-         */
         video?: boolean;
-        /**
-         * save videos for passed tests; videos are saved into `output/videos` folder
-         */
         keepVideoForPassedTests?: boolean;
-        /**
-         * record [tracing information](https://playwright.dev/docs/trace-viewer) with screenshots and snapshots.
-         */
         trace?: boolean;
-        /**
-         * make full page screenshots on failure.
-         */
+        keepTraceForPassedTests?: boolean;
         fullPageScreenshots?: boolean;
-        /**
-         * option to prevent screenshot override if you have scenarios with the same name in different suites.
-         */
         uniqueScreenshotNames?: boolean;
-        /**
-         * keep browser state between tests when `restart` is set to 'session'.
-         */
         keepBrowserState?: boolean;
-        /**
-         * keep cookies between tests when `restart` is set to 'session'.
-         */
         keepCookies?: boolean;
-        /**
-         * how long to wait after click, doubleClick or PressKey actions in ms. Default: 100.
-         */
         waitForAction?: number;
-        /**
-         * When to consider navigation succeeded. Possible options: `load`, `domcontentloaded`, `networkidle`. Choose one of those options is possible. See [Playwright API](https://playwright.dev/docs/api/class-page#page-wait-for-navigation).
-         */
         waitForNavigation?: string;
-        /**
-         * Delay between key presses in ms. Used when calling Playwrights page.type(...) in fillField/appendField
-         * @defaultValue 10
-         */
         pressKeyDelay?: number;
-        /**
-         * config option to set maximum navigation time in milliseconds.
-         */
         getPageTimeout?: number;
-        /**
-         * default wait* timeout in ms. Default: 1000.
-         */
         waitForTimeout?: number;
-        /**
-         * the basic authentication to pass to base url. Example: {username: 'username', password: 'password'}
-         */
         basicAuth?: any;
-        /**
-         * default window size. Set a dimension like `640x480`.
-         */
         windowSize?: string;
-        /**
-         * default color scheme. Possible values: `dark` | `light` | `no-preference`.
-         */
         colorScheme?: string;
-        /**
-         * user-agent string.
-         */
         userAgent?: string;
-        /**
-         * locale string. Example: 'en-GB', 'de-DE', 'fr-FR', ...
-         */
         locale?: string;
-        /**
-         * do not start browser before a test, start it manually inside a helper with `this.helpers["Playwright"]._startBrowser()`.
-         */
         manualStart?: boolean;
-        /**
-         * pass additional chromium options
-         */
         chromium?: any;
-        /**
-         * pass additional firefox options
-         */
         firefox?: any;
-        /**
-         * (pass additional electron options
-         */
         electron?: any;
-        /**
-         * (While Playwright can operate against the stock Google Chrome and Microsoft Edge browsers available on the machine. In particular, current Playwright version will support Stable and Beta channels of these browsers. See [Google Chrome & Microsoft Edge](https://playwright.dev/docs/browsers/#google-chrome--microsoft-edge).
-         */
         channel?: any;
-        /**
-         * An array with console message types that are not logged to debug log. Default value is `['warning', 'log']`. E.g. you can set `[]` to log all messages. See all possible [values](https://playwright.dev/docs/api/class-consolemessage#console-message-type).
-         */
         ignoreLog?: string[];
-        /**
-         * Allows access to untrustworthy pages, e.g. to a page with an expired certificate. Default value is `false`
-         */
         ignoreHTTPSErrors?: boolean;
     };
     /**
@@ -3412,9 +3350,9 @@ declare namespace CodeceptJS {
          * I.waitForFile('avatar.jpg', 5);
          *
          * ```
-         * @param [fileName] - set filename for downloaded file
+         * @param fileName - set filename for downloaded file
          */
-        handleDownloads(fileName?: string): Promise<void>;
+        handleDownloads(fileName: string): Promise<void>;
         /**
          * Perform a click on a link or a button, given by a locator.
          * If a fuzzy locator is given, the page will be searched for a button, link, or image matching the locator string.
@@ -5918,90 +5856,45 @@ declare namespace CodeceptJS {
      * ## Configuration
      *
      * This helper should be configured in codecept.conf.js
+     * @property url - base url of website to be tested
+     * @property [basicAuth] - (optional) the basic authentication to pass to base url. Example: {username: 'username', password: 'password'}
+     * @property [show] - show Google Chrome window for debug.
+     * @property [restart = true] - restart browser between tests.
+     * @property [disableScreenshots = false] - don't save screenshot on failure.
+     * @property [fullPageScreenshots = false] - make full page screenshots on failure.
+     * @property [uniqueScreenshotNames = false] - option to prevent screenshot override if you have scenarios with the same name in different suites.
+     * @property [keepBrowserState = false] - keep browser state between tests when `restart` is set to false.
+     * @property [keepCookies = false] - keep cookies between tests when `restart` is set to false.
+     * @property [waitForAction = 100] - how long to wait after click, doubleClick or PressKey actions in ms. Default: 100.
+     * @property [waitForNavigation = load] - when to consider navigation succeeded. Possible options: `load`, `domcontentloaded`, `networkidle0`, `networkidle2`. See [Puppeteer API](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#pagewaitfornavigationoptions). Array values are accepted as well.
+     * @property [pressKeyDelay = 10] - delay between key presses in ms. Used when calling Puppeteers page.type(...) in fillField/appendField
+     * @property [getPageTimeout = 30000] - config option to set maximum navigation time in milliseconds. If the timeout is set to 0, then timeout will be disabled.
+     * @property [waitForTimeout = 1000] - default wait* timeout in ms.
+     * @property [windowSize] - default window size. Set a dimension in format WIDTHxHEIGHT like `640x480`.
+     * @property [userAgent] - user-agent string.
+     * @property [manualStart = false] - do not start browser before a test, start it manually inside a helper with `this.helpers["Puppeteer"]._startBrowser()`.
+     * @property [browser = chrome] - can be changed to `firefox` when using [puppeteer-firefox](https://codecept.io/helpers/Puppeteer-firefox).
+     * @property [chrome] - pass additional [Puppeteer run options](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#puppeteerlaunchoptions).
      */
     type PuppeteerConfig = {
-        /**
-         * base url of website to be tested
-         */
         url: string;
-        /**
-         * (optional) the basic authentication to pass to base url. Example: {username: 'username', password: 'password'}
-         */
         basicAuth?: any;
-        /**
-         * show Google Chrome window for debug.
-         */
         show?: boolean;
-        /**
-         * restart browser between tests.
-         * @defaultValue true
-         */
         restart?: boolean;
-        /**
-         * don't save screenshot on failure.
-         */
         disableScreenshots?: boolean;
-        /**
-         * make full page screenshots on failure.
-         */
         fullPageScreenshots?: boolean;
-        /**
-         * option to prevent screenshot override if you have scenarios with the same name in different suites.
-         */
         uniqueScreenshotNames?: boolean;
-        /**
-         * keep browser state between tests when `restart` is set to false.
-         */
         keepBrowserState?: boolean;
-        /**
-         * keep cookies between tests when `restart` is set to false.
-         */
         keepCookies?: boolean;
-        /**
-         * how long to wait after click, doubleClick or PressKey actions in ms. Default: 100.
-         * @defaultValue 100
-         */
         waitForAction?: number;
-        /**
-         * when to consider navigation succeeded. Possible options: `load`, `domcontentloaded`, `networkidle0`, `networkidle2`. See [Puppeteer API](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#pagewaitfornavigationoptions). Array values are accepted as well.
-         * @defaultValue load
-         */
         waitForNavigation?: string;
-        /**
-         * delay between key presses in ms. Used when calling Puppeteers page.type(...) in fillField/appendField
-         * @defaultValue 10
-         */
         pressKeyDelay?: number;
-        /**
-         * config option to set maximum navigation time in milliseconds. If the timeout is set to 0, then timeout will be disabled.
-         * @defaultValue 30000
-         */
         getPageTimeout?: number;
-        /**
-         * default wait* timeout in ms.
-         * @defaultValue 1000
-         */
         waitForTimeout?: number;
-        /**
-         * default window size. Set a dimension in format WIDTHxHEIGHT like `640x480`.
-         */
         windowSize?: string;
-        /**
-         * user-agent string.
-         */
         userAgent?: string;
-        /**
-         * do not start browser before a test, start it manually inside a helper with `this.helpers["Puppeteer"]._startBrowser()`.
-         */
         manualStart?: boolean;
-        /**
-         * can be changed to `firefox` when using [puppeteer-firefox](https://codecept.io/helpers/Puppeteer-firefox).
-         * @defaultValue chrome
-         */
         browser?: string;
-        /**
-         * pass additional [Puppeteer run options](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#puppeteerlaunchoptions).
-         */
         chrome?: any;
     };
     /**
@@ -7691,36 +7584,21 @@ declare namespace CodeceptJS {
     }
     /**
      * ## Configuration
+     * @property [endpoint] - API base URL
+     * @property [prettyPrintJson = false] - pretty print json for response/request on console logs
+     * @property [timeout = 1000] - timeout for requests in milliseconds. 10000ms by default
+     * @property [defaultHeaders] - a list of default headers
+     * @property [onRequest] - a async function which can update request object.
+     * @property [onResponse] - a async function which can update response object.
+     * @property [maxUploadFileSize] - set the max content file size in MB when performing api calls.
      */
     type RESTConfig = {
-        /**
-         * API base URL
-         */
         endpoint?: string;
-        /**
-         * pretty print json for response/request on console logs
-         */
         prettyPrintJson?: boolean;
-        /**
-         * timeout for requests in milliseconds. 10000ms by default
-         * @defaultValue 1000
-         */
         timeout?: number;
-        /**
-         * a list of default headers
-         */
         defaultHeaders?: any;
-        /**
-         * a async function which can update request object.
-         */
         onRequest?: (...params: any[]) => any;
-        /**
-         * a async function which can update response object.
-         */
         onResponse?: (...params: any[]) => any;
-        /**
-         * set the max content file size in MB when performing api calls.
-         */
         maxUploadFileSize?: number;
     };
     /**
@@ -8877,90 +8755,45 @@ declare namespace CodeceptJS {
      * ## Configuration
      *
      * This helper should be configured in codecept.conf.js
+     * @property url - base url of website to be tested.
+     * @property browser - browser in which to perform testing.
+     * @property [basicAuth] - (optional) the basic authentication to pass to base url. Example: {username: 'username', password: 'password'}
+     * @property [host = localhost] - WebDriver host to connect.
+     * @property [port = 4444] - WebDriver port to connect.
+     * @property [protocol = http] - protocol for WebDriver server.
+     * @property [path = /wd/hub] - path to WebDriver server.
+     * @property [restart = true] - restart browser between tests.
+     * @property [smartWait = false] - **enables [SmartWait](http://codecept.io/acceptance/#smartwait)**; wait for additional milliseconds for element to appear. Enable for 5 secs: "smartWait": 5000.
+     * @property [disableScreenshots = false] - don't save screenshots on failure.
+     * @property [fullPageScreenshots = false] - (optional - make full page screenshots on failure.
+     * @property [uniqueScreenshotNames = false] - option to prevent screenshot override if you have scenarios with the same name in different suites.
+     * @property [keepBrowserState = false] - keep browser state between tests when `restart` is set to false.
+     * @property [keepCookies = false] - keep cookies between tests when `restart` set to false.
+     * @property [windowSize = window] - default window size. Set to `maximize` or a dimension in the format `640x480`.
+     * @property [waitForTimeout = 1000] - sets default wait time in *ms* for all `wait*` functions.
+     * @property [desiredCapabilities] - Selenium's [desired capabilities](https://github.com/SeleniumHQ/selenium/wiki/DesiredCapabilities).
+     * @property [manualStart = false] - do not start browser before a test, start it manually inside a helper with `this.helpers["WebDriver"]._startBrowser()`.
+     * @property [timeouts] - [WebDriver timeouts](http://webdriver.io/docs/timeouts.html) defined as hash.
      */
     type WebDriverConfig = {
-        /**
-         * base url of website to be tested.
-         */
         url: string;
-        /**
-         * browser in which to perform testing.
-         */
         browser: string;
-        /**
-         * (optional) the basic authentication to pass to base url. Example: {username: 'username', password: 'password'}
-         */
         basicAuth?: string;
-        /**
-         * WebDriver host to connect.
-         * @defaultValue localhost
-         */
         host?: string;
-        /**
-         * WebDriver port to connect.
-         * @defaultValue 4444
-         */
         port?: number;
-        /**
-         * protocol for WebDriver server.
-         * @defaultValue http
-         */
         protocol?: string;
-        /**
-         * path to WebDriver server.
-         * @defaultValue /wd/hub
-         */
         path?: string;
-        /**
-         * restart browser between tests.
-         * @defaultValue true
-         */
         restart?: boolean;
-        /**
-         * **enables [SmartWait](http://codecept.io/acceptance/#smartwait)**; wait for additional milliseconds for element to appear. Enable for 5 secs: "smartWait": 5000.
-         */
         smartWait?: boolean | number;
-        /**
-         * don't save screenshots on failure.
-         */
         disableScreenshots?: boolean;
-        /**
-         * (optional - make full page screenshots on failure.
-         */
         fullPageScreenshots?: boolean;
-        /**
-         * option to prevent screenshot override if you have scenarios with the same name in different suites.
-         */
         uniqueScreenshotNames?: boolean;
-        /**
-         * keep browser state between tests when `restart` is set to false.
-         */
         keepBrowserState?: boolean;
-        /**
-         * keep cookies between tests when `restart` set to false.
-         */
         keepCookies?: boolean;
-        /**
-         * default window size. Set to `maximize` or a dimension in the format `640x480`.
-         * @defaultValue window
-         */
         windowSize?: string;
-        /**
-         * sets default wait time in *ms* for all `wait*` functions.
-         * @defaultValue 1000
-         */
         waitForTimeout?: number;
-        /**
-         * Selenium's [desired capabilities](https://github.com/SeleniumHQ/selenium/wiki/DesiredCapabilities).
-         */
         desiredCapabilities?: any;
-        /**
-         * do not start browser before a test, start it manually inside a helper with `this.helpers["WebDriver"]._startBrowser()`.
-         */
         manualStart?: boolean;
-        /**
-         * [WebDriver timeouts](http://webdriver.io/docs/timeouts.html) defined as hash.
-         */
         timeouts?: any;
     };
     /**
@@ -10825,7 +10658,7 @@ declare namespace CodeceptJS {
         /**
          * add print comment method`
          */
-        say(msg: string, color?: string): Promise<any> | undefined;
+        say(msg: string, color?: string): void;
         /**
          * set the maximum execution time for the next step
          * @param timeout - step timeout in seconds
@@ -11336,7 +11169,7 @@ declare namespace CodeceptJS {
     interface RecorderSession {
         running: boolean;
         start(name: string): void;
-        restore(name: string): void;
+        restore(name?: string): void;
         catch(fn: (...params: any[]) => any): void;
     }
     class Secret {