codeceptjs 3.1.3 → 3.2.0

package/docs/custom-helpers.md

@@ -108,7 +108,7 @@ If you need to get access to web elements, it is recommended to implement operat
 
 To get access for elements, connect to a corresponding helper and use `_locate` function to match web elements by CSS or XPath, like you usually do:
 
-### Acessing Elements in WebDriver
+### Accessing Elements in WebDriver
 
 ```js
 // inside a custom helper
@@ -304,38 +304,3 @@ class MyHelper extends Helper {
 
 module.exports = MyHelper;
 ```
-
-### Protractor Example
-
-Protractor example demonstrates usage of global `element` and `by` objects.
-However `browser` should be accessed from a helper instance via `this.helpers['Protractor']`;
-We also use `chai-as-promised` library to have nice assertions with promises.
-
-```js
-const Helper = require('@codeceptjs/helper');
-
-// use any assertion library you like
-const chai = require('chai');
-const chaiAsPromised = require('chai-as-promised');
-chai.use(chaiAsPromised);
-const expect = chai.expect;
-
-class MyHelper extends Helper {
-  /**
-   * checks that authentication cookie is set
-   */
-  seeInHistory(historyPosition, value) {
-    // access browser instance from Protractor helper
-    this.helpers['Protractor'].browser.refresh();
-
-    // you can use `element` as well as in protractor
-    const history = element.all(by.repeater('result in memory'));
-
-    // use chai as promised for better assertions
-    // end your method with `return` to handle promises
-    return expect(history.get(historyPosition).getText()).to.eventually.equal(value);
-  }
-}
-
-module.exports = MyHelper;
-```

package/docs/helpers/Appium.md

@@ -1315,7 +1315,7 @@ I.defineTimeout({ implicit: 10000, pageLoad: 10000, script: 5000 });
 
 #### Parameters
 
--   `timeouts` **WebdriverIO.Timeouts** WebDriver timeouts object.
+-   `timeouts` **any** WebDriver timeouts object.
 
 ### amOnPage
 

package/docs/helpers/FileSystem.md

@@ -101,7 +101,7 @@ I.seeFileNameMatching('.pdf');
 
 #### Parameters
 
--   `text`  
+-   `text` **[string][1]** 
 
 ### seeInThisFile
 

package/docs/helpers/Playwright.md

@@ -47,6 +47,7 @@ This helper should be configured in codecept.json or codecept.conf.js
 -   `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`:  - 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
@@ -162,6 +163,19 @@ const { devices } = require('playwright');
 }
 ```
 
+#### 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
@@ -1821,11 +1835,11 @@ I.waitForRequest(request => request.url() === 'http://example.com' && request.me
 
 ### waitForResponse
 
-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);
 ```
 
 #### Parameters
@@ -1919,22 +1933,6 @@ I.waitToHide('#popup');
 -   `locator` **([string][9] | [object][7])** element located by CSS|XPath|strict locator.
 -   `sec` **[number][10]** (optional, `1` by default) time in seconds to wait 
 
-### waitUntil
-
-Waits for a function to return true (waits for 1sec by default).
-
-```js
-I.waitUntil(() => window.requests == 0);
-I.waitUntil(() => window.requests == 0, 5);
-```
-
-#### Parameters
-
--   `fn` **([function][11] | [string][9])** function which is executed in browser context.
--   `sec` **[number][10]** (optional, `1` by default) time in seconds to wait 
--   `timeoutMsg` **[string][9]** message to show in case of timeout fail. 
--   `interval` **[number][10]?**  
-
 ### waitUrlEquals
 
 Waits for the entire URL to match the expected

package/docs/helpers/Puppeteer.md

@@ -1614,7 +1614,7 @@ I.seeTitleEquals('Test title.');
 
 #### Parameters
 
--   `text`  
+-   `text` **[string][8]** value to check.
 
 ### selectOption
 
@@ -1998,22 +1998,6 @@ I.waitToHide('#popup');
 -   `locator` **([string][8] | [object][6])** element located by CSS|XPath|strict locator.
 -   `sec` **[number][10]** (optional, `1` by default) time in seconds to wait 
 
-### waitUntil
-
-Waits for a function to return true (waits for 1sec by default).
-
-```js
-I.waitUntil(() => window.requests == 0);
-I.waitUntil(() => window.requests == 0, 5);
-```
-
-#### Parameters
-
--   `fn` **([function][12] | [string][8])** function which is executed in browser context.
--   `sec` **[number][10]** (optional, `1` by default) time in seconds to wait 
--   `timeoutMsg` **[string][8]** message to show in case of timeout fail. 
--   `interval` **[number][10]?**  
-
 ### waitUrlEquals
 
 Waits for the entire URL to match the expected

package/docs/helpers/REST.md

@@ -168,7 +168,7 @@ I.setRequestTimeout(10000); // In milliseconds
 
 #### Parameters
 
--   `newTimeout`  
+-   `newTimeout` **[number][5]** timeout in milliseconds
 
 [1]: https://github.com/axios/axios
 
@@ -177,3 +177,5 @@ I.setRequestTimeout(10000); // In milliseconds
 [3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
 
 [4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
+
+[5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number

package/docs/helpers/WebDriver.md

@@ -599,7 +599,7 @@ I.defineTimeout({ implicit: 10000, pageLoad: 10000, script: 5000 });
 
 #### Parameters
 
--   `timeouts` **WebdriverIO.Timeouts** WebDriver timeouts object.
+-   `timeouts` **any** WebDriver timeouts object.
 
 ### dontSee
 
@@ -2155,22 +2155,6 @@ I.waitToHide('#popup');
 -   `locator` **([string][19] | [object][18])** element located by CSS|XPath|strict locator.
 -   `sec` **[number][22]** (optional, `1` by default) time in seconds to wait 
 
-### waitUntil
-
-Waits for a function to return true (waits for 1sec by default).
-
-```js
-I.waitUntil(() => window.requests == 0);
-I.waitUntil(() => window.requests == 0, 5);
-```
-
-#### Parameters
-
--   `fn` **([function][24] | [string][19])** function which is executed in browser context.
--   `sec` **[number][22]** (optional, `1` by default) time in seconds to wait 
--   `timeoutMsg` **[string][19]** message to show in case of timeout fail. 
--   `interval` **[number][22]?**  
-
 ### waitUrlEquals
 
 Waits for the entire URL to match the expected

package/docs/mobile-react-native-locators.md

@@ -1,6 +1,9 @@
 ## Automating React Native apps
 
 ### Problem
+
+> ⚠️ **NOTE**: This problem is not actual starting from `react-native@0.65.x` [CHANGELOG](https://github.com/react-native-community/releases/blob/master/CHANGELOG.md#android-specific-9), [#381fb3](https://github.com/facebook/react-native/commit/381fb395ad9d2d48717a5d082aaedbecdd804554)
+
 Let's say we have a React Native app with component defined like this
 ```html
 <Button testID='someButton'>My button</Button>

package/docs/plugins.md

@@ -626,6 +626,75 @@ Scenario('scenario tite', () => {
 
 -   `config`  
 
+## retryTo
+
+Adds global `retryTo` which retries steps a few times before failing.
+
+Enable this plugin in `codecept.conf.js` (enabled by default for new setups):
+
+```js
+plugins: {
+  retryTo: {
+    enabled: true
+  }
+}
+```
+
+Use it in your tests:
+
+```js
+// retry these steps 5 times before failing
+await retryTo((tryNum) => {
+  I.switchTo('#editor frame');
+  I.click('Open');
+  I.see('Opened')
+}, 5);
+```
+
+Set polling interval as 3rd argument (200ms by default):
+
+```js
+// retry these steps 5 times before failing
+await retryTo((tryNum) => {
+  I.switchTo('#editor frame');
+  I.click('Open');
+  I.see('Opened')
+}, 5, 100);
+```
+
+Default polling interval can be changed in a config:
+
+```js
+plugins: {
+  retryTo: {
+    enabled: true,
+    pollInterval: 500,
+  }
+}
+```
+
+Disables retryFailedStep plugin for steps inside a block;
+
+Use this plugin if:
+
+-   you need repeat a set of actions in flaky tests
+-   iframe was not rendered and you need to retry switching to it
+
+#### Configuration
+
+-   `pollInterval` - default interval between retries in ms. 200 by default.
+-   `registerGlobal` - to register `retryTo` function globally, true by default
+
+If `registerGlobal` is false you can use retryTo from the plugin:
+
+```js
+const retryTo = codeceptjs.container.plugins('retryTo');
+```
+
+### Parameters
+
+-   `config`  
+
 ## screenshotOnFail
 
 Creates screenshot on failure. Screenshot is saved into `output` directory.
@@ -802,11 +871,67 @@ Possible config options:
 -   `fullPageScreenshots`: should full page screenshots be used. Default: false.
 -   `output`: a directory where reports should be stored. Default: `output`.
 -   `screenshotsForAllureReport`: If Allure plugin is enabled this plugin attaches each saved screenshot to allure report. Default: false.
+-   \`disableScreenshotOnFail : Disables the capturing of screeshots after the failed step. Default: true.
 
 ### Parameters
 
 -   `config` **any** 
 
+## stepTimeout
+
+Set timeout for test steps globally.
+
+Add this plugin to config file:
+
+```js
+plugins: {
+    stepTimeout: {
+       enabled: true
+    }
+}
+```
+
+Run tests with plugin enabled:
+
+    npx codeceptjs run --plugins stepTimeout
+
+#### Configuration:
+
+-   `timeout` - global step timeout, default 150 seconds
+-   `force` - whether to use timeouts set in plugin config to override step timeouts set in code with I.limitTime(x).action(...), default false
+-   `noTimeoutSteps` - an array of steps with no timeout. Default:
+
+    -   `amOnPage`
+    -   `wait*`
+
+    you could set your own noTimeoutSteps which would replace the default one.
+
+-   `customTimeoutSteps` - an array of step actions with custom timeout. Use it to override or extend noTimeoutSteps.
+    You can use step names or step prefixes ending with `*`. As such, `wait*` will match all steps starting with `wait`.
+
+#### Example
+
+```js
+plugins: {
+    stepTimeout: {
+        enabled: true,
+        force: true,
+        noTimeoutSteps: [
+          'scroll*', // ignore all scroll steps
+          /Cookie/, // ignore all steps with a Cookie in it (by regexp)
+        ],
+        customTimeoutSteps: [
+          ['myFlakyStep*', 1],
+          ['scrollWhichRequiresTimeout', 5],
+        ]
+    }
+}
+```
+
+### Parameters
+
+-   `config`  
+
 ## subtitles
 
 Automatically captures steps as subtitle, and saves it as an artifact when a video is found for a failed test

package/docs/reports.md

@@ -33,8 +33,8 @@ GitHub --
   Run with --verbose flag to see NodeJS stacktrace
 
 ```
-npx codeceptjs run --stepsutput add `--steps` option to `run` command:
-```
+
+output steps use `--steps` option:
 ```
 npx codeceptjs run --steps
 ```

package/lib/actor.js

@@ -26,6 +26,24 @@ class Actor {
     });
   }
 
+  /**
+   * set the maximum execution time for the next step
+   * @function
+   * @param {number} timeout - step timeout in seconds
+   * @return {this}
+   * @inner
+   */
+  limitTime(timeout) {
+    if (!store.timeouts) return this;
+
+    event.dispatcher.prependOnceListener(event.step.before, (step) => {
+      output.log(`Timeout to ${step}: ${timeout}s`);
+      step.totalTimeout = timeout * 1000;
+    });
+
+    return this;
+  }
+
   /**
    * @function
    * @param {*} [opts]
@@ -114,7 +132,7 @@ function recordStep(step, args) {
       step.startTime = Date.now();
     }
     return val = step.run(...args);
-  });
+  }, false, undefined, step.totalTimeout);
 
   event.emit(event.step.after, step);
 

package/lib/codecept.js

@@ -77,6 +77,7 @@ class Codecept {
       global.inject = container.support;
       global.share = container.share;
       global.secret = require('./secret').secret;
+      global.codecept_debug = output.debug;
       global.codeceptjs = require('./index'); // load all objects
 
       // BDD
@@ -95,6 +96,7 @@ class Codecept {
     runHook(require('./listener/steps'));
     runHook(require('./listener/config'));
     runHook(require('./listener/helpers'));
+    runHook(require('./listener/timeout'));
     runHook(require('./listener/exit'));
 
     // custom hooks

package/lib/command/info.js

@@ -32,7 +32,7 @@ module.exports = async function (path) {
     }
   }
   output.print('***************************************');
-  output.print('If you have questions ask them in our Slack: shorturl.at/cuKU8');
+  output.print('If you have questions ask them in our Slack: http://bit.ly/chat-codeceptjs');
   output.print('Or ask them on our discussion board: https://codecept.discourse.group/');
   output.print('Please copy environment info when you report issues on GitHub: https://github.com/Codeception/CodeceptJS/issues');
   output.print('***************************************');

package/lib/config.js

@@ -13,6 +13,7 @@ const defaultConfig = {
   include: {},
   mocha: {},
   bootstrap: null,
+  timeout: null,
   teardown: null,
   hooks: [],
   gherkin: {},
@@ -21,6 +22,17 @@ const defaultConfig = {
       enabled: true, // will be disabled by default in 2.0
     },
   },
+  stepTimeout: 0,
+  stepTimeoutOverride: [
+    {
+      pattern: 'wait.*',
+      timeout: 0,
+    },
+    {
+      pattern: 'amOnPage',
+      timeout: 0,
+    },
+  ],
 };
 
 let hooks = [];

package/lib/container.js

@@ -7,6 +7,7 @@ const MochaFactory = require('./mochaFactory');
 const recorder = require('./recorder');
 const event = require('./event');
 const WorkerStorage = require('./workerStorage');
+const store = require('./store');
 
 let container = {
   helpers: {},
@@ -45,6 +46,7 @@ class Container {
     container.support = createSupportObjects(config.include || {});
     container.plugins = createPlugins(config.plugins || {}, opts);
     if (config.gherkin) loadGherkinSteps(config.gherkin.steps || []);
+    if (opts && typeof opts.timeouts === 'boolean') store.timeouts = opts.timeouts;
   }
 
   /**
@@ -233,7 +235,7 @@ function createSupportObjects(config) {
     const currentObject = objects[object];
     Object.keys(currentObject).forEach((method) => {
       const currentMethod = currentObject[method];
-      if (currentMethod[Symbol.toStringTag] === 'AsyncFunction') {
+      if (currentMethod && currentMethod[Symbol.toStringTag] === 'AsyncFunction') {
         objects[object][method] = asyncWrapper(currentMethod);
       }
     });

package/lib/helper/FileSystem.js

@@ -91,6 +91,7 @@ class FileSystem extends Helper {
   * I.amInPath('output/downloads');
   * I.seeFileNameMatching('.pdf');
   * ```
+  * @param {string} text
   */
   seeFileNameMatching(text) {
     assert.ok(

package/lib/helper/Playwright.js

@@ -80,6 +80,7 @@ const { createValueEngine, createDisabledEngine } = require('./extras/Playwright
  * * `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
@@ -197,6 +198,19 @@ const { createValueEngine, createDisabledEngine } = require('./extras/Playwright
  * }
  * ```
  *
+ * #### 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
@@ -371,6 +385,8 @@ class Playwright extends Helper {
       }
       if (this.options.recordVideo) contextOptions.recordVideo = this.options.recordVideo;
       if (this.storageState) contextOptions.storageState = this.storageState;
+      if (this.options.userAgent) contextOptions.userAgent = this.options.userAgent;
+      if (this.options.locale) contextOptions.locale = this.options.locale;
       this.browserContext = await this.browser.newContext(contextOptions); // Adding the HTTPSError ignore in the context so that we can ignore those errors
     }
 
@@ -2146,11 +2162,11 @@ class Playwright extends Helper {
   }
 
   /**
-   * 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 {string|function} urlOrPredicate
@@ -2236,16 +2252,6 @@ class Playwright extends Helper {
     return this.page.waitForNavigation(opts);
   }
 
-  /**
-   * {{> waitUntil }}
-   */
-  async waitUntil(fn, sec = null) {
-    console.log('This method will remove in CodeceptJS 1.4; use `waitForFunction` instead!');
-    const waitTimeout = sec ? sec * 1000 : this.options.waitForTimeout;
-    const context = await this._getContext();
-    return context.waitForFunction(fn, { timeout: waitTimeout });
-  }
-
   async waitUntilExists(locator, sec) {
     console.log(`waitUntilExists deprecated:
     * use 'waitForElement' to wait for element to be attached
@@ -2662,13 +2668,10 @@ async function targetCreatedHandler(page) {
       });
   });
   page.on('console', (msg) => {
-    this.debugSection(`Browser:${ucfirst(msg.type())}`, (msg._text || '') + msg.args().join(' '));
+    this.debugSection(`Browser:${ucfirst(msg.type())}`, (msg.text && msg.text() || msg._text || '') + msg.args().join(' '));
     consoleLogStore.add(msg);
   });
 
-  if (this.options.userAgent) {
-    await page.setUserAgent(this.options.userAgent);
-  }
   if (this.options.windowSize && this.options.windowSize.indexOf('x') > 0 && this._getType() === 'Browser') {
     await page.setViewportSize(parseWindowSize(this.options.windowSize));
   }

package/lib/helper/Protractor.js

@@ -838,11 +838,7 @@ class Protractor extends Helper {
   }
 
   /**
-   * Checks that title is equal to provided one.
-   *
-   * ```js
-   * I.seeTitleEquals('Test title.');
-   * ```
+   * {{> seeTitleEquals }}
    */
   async seeTitleEquals(text) {
     const title = await this.browser.getTitle();
@@ -1018,7 +1014,7 @@ class Protractor extends Helper {
   }
 
   /**
-     * {{> seeInCurrentUrl }}
+   * {{> seeInCurrentUrl }}
    */
   async seeInCurrentUrl(url) {
     return this.browser.getCurrentUrl().then(currentUrl => stringIncludes('url').assert(url, currentUrl));
@@ -1498,14 +1494,6 @@ class Protractor extends Helper {
     return this.browser.wait(() => this.browser.executeScript.call(this.browser, fn, ...args), aSec * 1000);
   }
 
-  /**
-   * {{> waitUntil }}
-   */
-  async waitUntil(fn, sec = null, timeoutMsg = null) {
-    const aSec = sec || this.options.waitForTimeout;
-    return this.browser.wait(fn, aSec * 1000, timeoutMsg);
-  }
-
   /**
    * {{> waitInUrl }}
    */

package/lib/helper/Puppeteer.js

@@ -554,10 +554,9 @@ class Puppeteer extends Helper {
     this.context = null;
     popupStore.clear();
     this.isAuthenticated = false;
+    await this.browser.close();
     if (this.isRemoteBrowser) {
       await this.browser.disconnect();
-    } else {
-      await this.browser.close();
     }
   }
 
@@ -774,11 +773,7 @@ class Puppeteer extends Helper {
   }
 
   /**
-   * Checks that title is equal to provided one.
-   *
-   * ```js
-   * I.seeTitleEquals('Test title.');
-   * ```
+   * {{> seeTitleEquals }}
    */
   async seeTitleEquals(text) {
     const title = await this.page.title();
@@ -2220,16 +2215,6 @@ class Puppeteer extends Helper {
     return this.page.waitForNavigation(opts);
   }
 
-  /**
-   * {{> waitUntil }}
-   */
-  async waitUntil(fn, sec = null) {
-    console.log('This method will remove in CodeceptJS 1.4; use `waitForFunction` instead!');
-    const waitTimeout = sec ? sec * 1000 : this.options.waitForTimeout;
-    const context = await this._getContext();
-    return context.waitForFunction(fn, { timeout: waitTimeout });
-  }
-
   async waitUntilExists(locator, sec) {
     console.log(`waitUntilExists deprecated:
     * use 'waitForElement' to wait for element to be attached

package/lib/helper/REST.js

@@ -131,6 +131,7 @@ class REST extends Helper {
    * I.setRequestTimeout(10000); // In milliseconds
    * ```
    *
+   * @param {number} newTimeout - timeout in milliseconds
    */
   setRequestTimeout(newTimeout) {
     this.options.timeout = newTimeout;