codeceptjs 3.1.1 → 3.2.1

package/lib/step.js

@@ -38,6 +38,9 @@ class Step {
     this.metaStep = undefined;
     /** @member {string} */
     this.stack = '';
+    /** @member {number} */
+    this.totalTimeout = undefined;
+
     this.setTrace();
   }
 
@@ -212,16 +215,18 @@ class MetaStep extends Step {
       step.metaStep = this;
     };
     event.dispatcher.prependListener(event.step.before, registerStep);
+    let rethrownError = null;
     try {
       this.startTime = Date.now();
       result = fn.apply(this.context, this.args);
     } catch (error) {
-      this.status = 'failed';
+      this.setStatus('failed');
+      rethrownError = error;
     } finally {
       this.endTime = Date.now();
-
       event.dispatcher.removeListener(event.step.before, registerStep);
     }
+    if (rethrownError) { throw rethrownError; }
     return result;
   }
 }

package/lib/store.js

@@ -5,6 +5,8 @@
 const store = {
   /** @type {boolean} */
   debugMode: false,
+  /** @type {boolean} */
+  timeouts: true,
 };
 
 module.exports = store;

package/lib/ui.js

@@ -65,7 +65,7 @@ module.exports = function (suite) {
 
       suite.addTest(scenario.test(test));
       if (opts.retries) test.retries(opts.retries);
-      if (opts.timeout) test.timeout(opts.timeout);
+      if (opts.timeout) test.totalTimeout = opts.timeout;
       test.opts = opts;
 
       return new ScenarioConfig(test);
@@ -103,7 +103,7 @@ module.exports = function (suite) {
       suite.timeout(0);
 
       if (opts.retries) suite.retries(opts.retries);
-      if (opts.timeout) suite.timeout(opts.timeout);
+      if (opts.timeout) suite.totalTimeout = opts.timeout;
 
       suite.tags = title.match(/(\@[a-zA-Z0-9-_]+)/g) || []; // match tags from title
       suite.file = file;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codeceptjs",
-  "version": "3.1.1",
+  "version": "3.2.1",
   "description": "Supercharged End 2 End Testing Framework for NodeJS",
   "keywords": [
     "acceptance",
@@ -10,7 +10,6 @@
     "webdriver",
     "testcafe",
     "playwright",
-    "protractor",
     "bdd",
     "tdd",
     "testing"
@@ -84,7 +83,8 @@
     "promise-retry": "^1.1.1",
     "requireg": "^0.2.2",
     "resq": "^1.10.0",
-    "sprintf-js": "^1.1.1"
+    "sprintf-js": "^1.1.1",
+    "uuid": "^8.3.2"
   },
   "devDependencies": {
     "@codeceptjs/detox-helper": "^1.0.2",
@@ -102,7 +102,7 @@
     "chai-subset": "^1.6.0",
     "contributor-faces": "^1.0.3",
     "documentation": "^12.3.0",
-    "dtslint": "^3.6.12",
+    "dtslint": "^4.1.6",
     "electron": "^12.0.0",
     "eslint": "^6.8.0",
     "eslint-config-airbnb-base": "^14.2.1",
@@ -121,7 +121,6 @@
     "nightmare": "^3.0.2",
     "nodemon": "^1.19.4",
     "playwright": "^1.9.1",
-    "protractor": "^5.4.4",
     "puppeteer": "^10.0.0",
     "qrcode-terminal": "^0.12.0",
     "rosie": "^1.6.0",
@@ -132,9 +131,9 @@
     "testcafe": "^1.9.4",
     "ts-morph": "^3.1.3",
     "tsd-jsdoc": "^2.5.0",
-    "typescript": "^3.7.5",
+    "typescript": "^4.4.3",
     "wdio-docker-service": "^1.5.0",
-    "webdriverio": "^6.10.7",
+    "webdriverio": "^7.14.1",
     "xml2js": "^0.4.23",
     "xmldom": "^0.1.31",
     "xpath": "0.0.27"

package/typings/index.d.ts

@@ -66,7 +66,7 @@ declare namespace CodeceptJS {
   type StringOrSecret = string | CodeceptJS.Secret;
 
   interface HookCallback {
-    (args: SupportObject): void;
+    (args: SupportObject): void | Promise<void>;
   }
   interface Scenario extends IScenario {
     only: IScenario;
@@ -111,6 +111,7 @@ declare const pause: typeof CodeceptJS.pause;
 declare const within: typeof CodeceptJS.within;
 declare const session: typeof CodeceptJS.session;
 declare const DataTable: typeof CodeceptJS.DataTable;
+declare const DataTableArgument: typeof CodeceptJS.DataTableArgument;
 declare const codeceptjs: typeof CodeceptJS.index;
 declare const locate: typeof CodeceptJS.Locator.build;
 declare function inject(): CodeceptJS.SupportObject;
@@ -160,6 +161,7 @@ declare namespace NodeJS {
     within: typeof within;
     session: typeof session;
     DataTable: typeof DataTable;
+    DataTableArgument: typeof DataTableArgument;
     locate: typeof locate;
     inject: typeof inject;
     secret: typeof secret;
@@ -193,6 +195,7 @@ declare namespace Mocha {
   }
 
   interface Test extends Runnable {
+    artifacts: [],
     tags: any[];
   }
 }
@@ -200,3 +203,7 @@ declare namespace Mocha {
 declare module "codeceptjs" {
   export = codeceptjs;
 }
+
+declare module "@codeceptjs/helper" {
+  export = CodeceptJS.Helper;
+}

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.
          *
@@ -948,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.
          *
@@ -1135,7 +1147,7 @@ declare namespace CodeceptJS {
          * I.seeFileNameMatching('.pdf');
          * ```
          */
-        seeFileNameMatching(): void;
+        seeFileNameMatching(text: string): void;
         /**
          * Checks that file found by `seeFile` includes a text.
          */
@@ -2421,6 +2433,7 @@ 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
@@ -2538,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
@@ -3848,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
          */
@@ -3891,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.
@@ -4610,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.
          *
@@ -5144,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.
          *
@@ -5374,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
      *
@@ -5388,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
      *
@@ -5606,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.
          *
@@ -6819,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.
@@ -6943,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
          *
@@ -8394,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.
@@ -9614,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.
          *
@@ -9777,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.
@@ -9921,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: {
@@ -10017,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;
     }
@@ -10123,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;
@@ -10217,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>;
@@ -10280,6 +10311,7 @@ declare namespace CodeceptJS {
         args: any[];
         metaStep: MetaStep;
         stack: string;
+        totalTimeout: number;
         setTrace(): void;
         setArguments(args: any[]): void;
         run(...args: any[]): any;
@@ -10301,6 +10333,7 @@ declare namespace CodeceptJS {
      */
     namespace store {
         var debugMode: boolean;
+        var timeouts: boolean;
     }
     /**
      * Describe a "suite" with the given `title`