codeceptjs 3.5.9-beta.2 → 3.5.10

package/README.md

@@ -24,7 +24,7 @@ Reference: [Helpers API](https://github.com/codeceptjs/CodeceptJS/tree/master/do
 ## Supercharged E2E Testing
 
 CodeceptJS is a new testing framework for end-to-end testing with WebDriver (or others).
-It abstracts browser interaction to simple steps that are written from a user perspective.
+It abstracts browser interaction to simple steps that are written from a user's perspective.
 A simple test that verifies the "Welcome" text is present on a main page of a site will look like:
 
 ```js
@@ -57,27 +57,27 @@ And more to come...
 
 CodeceptJS is a successor of [Codeception](http://codeception.com), a popular full-stack testing framework for PHP.
 With CodeceptJS your scenario-driven functional and acceptance tests will be as simple and clean as they can be.
-You don't need to worry about asynchronous nature of NodeJS or about various APIs of Selenium, Puppeteer, TestCafe, etc. as CodeceptJS unifies them and makes them work as they are synchronous.
+You don't need to worry about asynchronous nature of NodeJS or about various APIs of Playwright, Selenium, Puppeteer, TestCafe, etc. as CodeceptJS unifies them and makes them work as they are synchronous.
 
 
 ## Features
  
-* 🪄 **AI-powered** with GPT features to assist and heal failing tests
-* Based on [Mocha](https://mochajs.org/) testing framework.
-* Designed for scenario driven acceptance testing in BDD-style
-* Uses ES6 natively without transpiler.
+* 🪄 **AI-powered** with GPT features to assist and heal failing tests.
+* ☕ Based on [Mocha](https://mochajs.org/) testing framework.
+* 💼 Designed for scenario driven acceptance testing in BDD-style.
+* 💻 Uses ES6 natively without transpiler.
 * Also plays nice with TypeScript.
-* Smart locators: use names, labels, matching text, CSS or XPath to locate elements.
-* Interactive debugging shell: pause test at any point and try different commands in a browser.
+* </> Smart locators: use names, labels, matching text, CSS or XPath to locate elements.
+* 🌐 Interactive debugging shell: pause test at any point and try different commands in a browser.
 * Easily create tests, pageobjects, stepobjects with CLI generators.
 
-## Install
+## Installation
 
 ```sh
 npm i codeceptjs --save
 ```
 
-Move to directory where you'd like to have your tests (and codeceptjs config) stored, and execute
+Move to directory where you'd like to have your tests (and CodeceptJS config) stored, and execute:
 
 ```sh
 npx codeceptjs init
@@ -131,8 +131,8 @@ Scenario('test some forms', ({ I }) => {
 });
 ```
 
-All actions are performed by I object; assertions functions start with `see` function.
-In this examples all methods of `I` are taken from WebDriver helper, see [reference](https://github.com/codeceptjs/CodeceptJS/blob/master/docs/helpers/WebDriver.md) to learn how to use them.
+All actions are performed by `I` object; assertions functions start with `see` function.
+In these examples all methods of `I` are taken from WebDriver helper, see [reference](https://github.com/codeceptjs/CodeceptJS/blob/master/docs/helpers/WebDriver.md) to learn how to use them.
 
 Let's execute this test with `run` command. Additional option `--steps` will show us the running process. We recommend use `--steps` or `--debug` during development.
 
@@ -198,17 +198,15 @@ In this case 'User is valid' string will be searched only inside elements locate
 ### Grabbers
 
 In case you need to return a value from a webpage and use it directly in test, you should use methods with `grab` prefix.
-They are expected to be used inside async/await functions, and their results will be available in test:
+They are expected to be used inside `async/await` functions, and their results will be available in test:
 
 ```js
-const assert = require('assert');
-
 Feature('CodeceptJS Demonstration');
 
 Scenario('test page title', async ({ I }) => {
   I.amOnPage('http://simple-form-bootstrap.plataformatec.com.br/documentation');
   const title = await I.grabTitle();
-  assert.equal(title, 'Example application with SimpleForm and Twitter Bootstrap');
+  I.expectEqual(title, 'Example application with SimpleForm and Twitter Bootstrap'); // Avaiable with Expect helper. -> https://codecept.io/helpers/Expect/
 });
 ```
 

package/docs/build/Appium.js

@@ -276,7 +276,7 @@ class Appium extends Webdriver {
     const _convertedCaps = {};
     for (const [key, value] of Object.entries(capabilities)) {
       if (!key.startsWith(vendorPrefix.appium)) {
-        if (key !== 'platformName') {
+        if (key !== 'platformName' && key !== 'bstack:options') {
           _convertedCaps[`${vendorPrefix.appium}:${key}`] = value;
         } else {
           _convertedCaps[`${key}`] = value;
@@ -423,8 +423,8 @@ class Appium extends Webdriver {
   async runOnIOS(caps, fn) {
     if (this.platform !== 'ios') return;
     recorder.session.start('iOS-only actions');
-    this._runWithCaps(caps, fn);
-    recorder.add('restore from iOS session', () => recorder.session.restore());
+    await this._runWithCaps(caps, fn);
+    await recorder.add('restore from iOS session', () => recorder.session.restore());
     return recorder.promise();
   }
 
@@ -465,8 +465,8 @@ class Appium extends Webdriver {
   async runOnAndroid(caps, fn) {
     if (this.platform !== 'android') return;
     recorder.session.start('Android-only actions');
-    this._runWithCaps(caps, fn);
-    recorder.add('restore from Android session', () => recorder.session.restore());
+    await this._runWithCaps(caps, fn);
+    await recorder.add('restore from Android session', () => recorder.session.restore());
     return recorder.promise();
   }
 
@@ -1424,10 +1424,10 @@ class Appium extends Webdriver {
    *
    * @return {Promise<void>}
    *
-   * Appium: support only iOS
+   * Appium: support both Android and iOS
    */
   async closeApp() {
-    onlyForApps.call(this, 'iOS');
+    onlyForApps.call(this);
     return this.browser.closeApp();
   }
 

package/docs/build/Playwright.js

@@ -362,7 +362,7 @@ class Playwright extends Helper {
       ignoreLog: ['warning', 'log'],
       uniqueScreenshotNames: false,
       manualStart: false,
-      getPageTimeout: 0,
+      getPageTimeout: 30000,
       waitForNavigation: 'load',
       restart: false,
       keepCookies: false,
@@ -474,7 +474,7 @@ class Playwright extends Helper {
   async _before(test) {
     this.currentRunningTest = test;
     recorder.retry({
-      retries: 5,
+      retries: process.env.FAILED_STEP_RETRIES || 3,
       when: err => {
         if (!err || typeof (err.message) !== 'string') {
           return false;
@@ -1450,6 +1450,40 @@ class Playwright extends Helper {
     return findFields.call(this, locator);
   }
 
+  /**
+   * Grab WebElements for given locator
+   * Resumes test execution, so **should be used inside an async function with `await`** operator.
+   * 
+   * ```js
+   * const webElements = await I.grabWebElements('#button');
+   * ```
+   * 
+   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+   * @returns {Promise<*>} WebElement of being used Web helper
+   * 
+   *
+   */
+  async grabWebElements(locator) {
+    return this._locate(locator);
+  }
+
+  /**
+   * Grab WebElement for given locator
+   * Resumes test execution, so **should be used inside an async function with `await`** operator.
+   * 
+   * ```js
+   * const webElement = await I.grabWebElement('#button');
+   * ```
+   * 
+   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+   * @returns {Promise<*>} WebElement of being used Web helper
+   * 
+   *
+   */
+  async grabWebElement(locator) {
+    return this._locateElement(locator);
+  }
+
   /**
    * Switch focus to a particular tab by its number. It waits tabs loading and then switch tab
    *
@@ -2265,8 +2299,15 @@ class Playwright extends Helper {
     const el = els[0];
 
     await highlightActiveElement.call(this, el);
+    let optionToSelect = '';
 
-    if (!Array.isArray(option)) option = [option];
+    try {
+      optionToSelect = await el.locator('option', { hasText: option }).textContent();
+    } catch (e) {
+      optionToSelect = option;
+    }
+
+    if (!Array.isArray(option)) option = [optionToSelect];
 
     await el.selectOption(option);
     return this._waitForAction();
@@ -2856,19 +2897,17 @@ class Playwright extends Helper {
 
     const cssPropertiesCamelCase = convertCssPropertiesToCamelCase(cssProperties);
     const elemAmount = res.length;
-    const commands = [];
     let props = [];
 
     for (const element of res) {
-      const cssProperties = await element.evaluate((el) => getComputedStyle(el));
-
-      Object.keys(cssPropertiesCamelCase).forEach(prop => {
+      for (const prop of Object.keys(cssProperties)) {
+        const cssProp = await this.grabCssPropertyFrom(locator, prop);
         if (isColorProperty(prop)) {
-          props.push(convertColorToRGBA(cssProperties[prop]));
+          props.push(convertColorToRGBA(cssProp));
         } else {
-          props.push(cssProperties[prop]);
+          props.push(cssProp);
         }
-      });
+      }
     }
 
     const values = Object.keys(cssPropertiesCamelCase).map(key => cssPropertiesCamelCase[key]);
@@ -2876,7 +2915,8 @@ class Playwright extends Helper {
     let chunked = chunkArray(props, values.length);
     chunked = chunked.filter((val) => {
       for (let i = 0; i < val.length; ++i) {
-        if (val[i] !== values[i]) return false;
+        // eslint-disable-next-line eqeqeq
+        if (val[i] != values[i]) return false;
       }
       return true;
     });
@@ -2914,7 +2954,7 @@ class Playwright extends Helper {
     let chunked = chunkArray(attrs, values.length);
     chunked = chunked.filter((val) => {
       for (let i = 0; i < val.length; ++i) {
-        if (val[i] !== values[i]) return false;
+        if (!val[i].includes(values[i])) return false;
       }
       return true;
     });
@@ -3582,7 +3622,7 @@ class Playwright extends Helper {
       const _contextObject = this.frame ? this.frame : contextObject;
       let count = 0;
       do {
-        waiter = await _contextObject.locator(`:has-text('${text}')`).first().isVisible();
+        waiter = await _contextObject.locator(`:has-text("${text}")`).first().isVisible();
         if (waiter) break;
         await this.wait(1);
         count += 1000;

package/docs/build/Puppeteer.js

@@ -297,7 +297,7 @@ class Puppeteer extends Helper {
     this.sessionPages = {};
     this.currentRunningTest = test;
     recorder.retry({
-      retries: 3,
+      retries: process.env.FAILED_STEP_RETRIES || 3,
       when: err => {
         if (!err || typeof (err.message) !== 'string') {
           return false;
@@ -1063,6 +1063,23 @@ class Puppeteer extends Helper {
     return findFields.call(this, locator);
   }
 
+  /**
+   * Grab WebElements for given locator
+   * Resumes test execution, so **should be used inside an async function with `await`** operator.
+   * 
+   * ```js
+   * const webElements = await I.grabWebElements('#button');
+   * ```
+   * 
+   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+   * @returns {Promise<*>} WebElement of being used Web helper
+   * 
+   *
+   */
+  async grabWebElements(locator) {
+    return this._locate(locator);
+  }
+
   /**
    * Switch focus to a particular tab by its number. It waits tabs loading and then switch tab
    *
@@ -2589,29 +2606,26 @@ class Puppeteer extends Helper {
 
     const cssPropertiesCamelCase = convertCssPropertiesToCamelCase(cssProperties);
     const elemAmount = res.length;
-    const commands = [];
-    res.forEach((el) => {
-      Object.keys(cssPropertiesCamelCase).forEach((prop) => {
-        commands.push(el.executionContext()
-          .evaluate((el) => {
-            const style = window.getComputedStyle ? getComputedStyle(el) : el.currentStyle;
-            return JSON.parse(JSON.stringify(style));
-          }, el)
-          .then((props) => {
-            if (isColorProperty(prop)) {
-              return convertColorToRGBA(props[prop]);
-            }
-            return props[prop];
-          }));
-      });
-    });
-    let props = await Promise.all(commands);
+    let props = [];
+
+    for (const element of res) {
+      for (const prop of Object.keys(cssProperties)) {
+        const cssProp = await this.grabCssPropertyFrom(locator, prop);
+        if (isColorProperty(prop)) {
+          props.push(convertColorToRGBA(cssProp));
+        } else {
+          props.push(cssProp);
+        }
+      }
+    }
+
     const values = Object.keys(cssPropertiesCamelCase).map(key => cssPropertiesCamelCase[key]);
     if (!Array.isArray(props)) props = [props];
     let chunked = chunkArray(props, values.length);
     chunked = chunked.filter((val) => {
       for (let i = 0; i < val.length; ++i) {
-        if (val[i] !== values[i]) return false;
+        // eslint-disable-next-line eqeqeq
+        if (val[i] != values[i]) return false;
       }
       return true;
     });
@@ -2651,7 +2665,9 @@ class Puppeteer extends Helper {
     let chunked = chunkArray(attrs, values.length);
     chunked = chunked.filter((val) => {
       for (let i = 0; i < val.length; ++i) {
-        if (val[i] !== values[i]) return false;
+        const _actual = Number.isNaN(val[i]) || (typeof values[i]) === 'string' ? val[i] : Number.parseInt(values[i], 10);
+        const _expected = Number.isNaN(values[i]) || (typeof values[i]) === 'string' ? values[i] : Number.parseInt(values[i], 10);
+        if (!_actual.includes(_expected)) return false;
       }
       return true;
     });

package/docs/build/WebDriver.js

@@ -869,6 +869,23 @@ class WebDriver extends Helper {
     return findFields.call(this, locator).then(res => res);
   }
 
+  /**
+   * Grab WebElements for given locator
+   * Resumes test execution, so **should be used inside an async function with `await`** operator.
+   * 
+   * ```js
+   * const webElements = await I.grabWebElements('#button');
+   * ```
+   * 
+   * @param {CodeceptJS.LocatorOrString} locator element located by CSS|XPath|strict locator.
+   * @returns {Promise<*>} WebElement of being used Web helper
+   * 
+   *
+   */
+  async grabWebElements(locator) {
+    return this._locate(locator);
+  }
+
   /**
    * Set [WebDriver timeouts](https://webdriver.io/docs/timeouts.html) in realtime.
    *
@@ -2013,7 +2030,9 @@ class WebDriver extends Helper {
     let chunked = chunkArray(props, values.length);
     chunked = chunked.filter((val) => {
       for (let i = 0; i < val.length; ++i) {
-        if (val[i] !== values[i]) return false;
+        const _acutal = Number.isNaN(val[i]) || (typeof values[i]) === 'string' ? val[i] : Number.parseInt(val[i], 10);
+        const _expected = Number.isNaN(values[i]) || (typeof values[i]) === 'string' ? values[i] : Number.parseInt(values[i], 10);
+        if (_acutal !== _expected) return false;
       }
       return true;
     });
@@ -2049,7 +2068,9 @@ class WebDriver extends Helper {
     let chunked = chunkArray(attrs, values.length);
     chunked = chunked.filter((val) => {
       for (let i = 0; i < val.length; ++i) {
-        if (val[i] !== values[i]) return false;
+        const _acutal = Number.isNaN(val[i]) || (typeof values[i]) === 'string' ? val[i] : Number.parseInt(val[i], 10);
+        const _expected = Number.isNaN(values[i]) || (typeof values[i]) === 'string' ? values[i] : Number.parseInt(values[i], 10);
+        if (_acutal !== _expected) return false;
       }
       return true;
     });

package/docs/helpers/Appium.md

@@ -871,7 +871,7 @@ Close the given application.
 I.closeApp();
 ```
 
-Returns **[Promise][6]<void>** Appium: support only iOS
+Returns **[Promise][6]<void>** Appium: support both Android and iOS
 
 ### appendField
 

package/docs/helpers/Playwright.md

@@ -1389,6 +1389,36 @@ let inputs = await I.grabValueFromAll('//form/input');
 
 Returns **[Promise][22]<[Array][10]<[string][9]>>** attribute value
 
+### grabWebElement
+
+Grab WebElement for given locator
+Resumes test execution, so **should be used inside an async function with `await`** operator.
+
+```js
+const webElement = await I.grabWebElement('#button');
+```
+
+#### Parameters
+
+-   `locator` **([string][9] | [object][6])** element located by CSS|XPath|strict locator.
+
+Returns **[Promise][22]<any>** WebElement of being used Web helper
+
+### grabWebElements
+
+Grab WebElements for given locator
+Resumes test execution, so **should be used inside an async function with `await`** operator.
+
+```js
+const webElements = await I.grabWebElements('#button');
+```
+
+#### Parameters
+
+-   `locator` **([string][9] | [object][6])** element located by CSS|XPath|strict locator.
+
+Returns **[Promise][22]<any>** WebElement of being used Web helper
+
 ### grabWebSocketMessages
 
 Grab the recording WS messages

package/docs/helpers/Puppeteer.md

@@ -1216,6 +1216,21 @@ let inputs = await I.grabValueFromAll('//form/input');
 
 Returns **[Promise][13]<[Array][15]<[string][6]>>** attribute value
 
+### grabWebElements
+
+Grab WebElements for given locator
+Resumes test execution, so **should be used inside an async function with `await`** operator.
+
+```js
+const webElements = await I.grabWebElements('#button');
+```
+
+#### Parameters
+
+-   `locator` **([string][6] | [object][4])** element located by CSS|XPath|strict locator.
+
+Returns **[Promise][13]<any>** WebElement of being used Web helper
+
 ### handleDownloads
 
 Sets a directory to where save files. Allows to test file downloads.

package/docs/helpers/WebDriver.md

@@ -1367,6 +1367,21 @@ let inputs = await I.grabValueFromAll('//form/input');
 
 Returns **[Promise][25]<[Array][28]<[string][17]>>** attribute value
 
+### grabWebElements
+
+Grab WebElements for given locator
+Resumes test execution, so **should be used inside an async function with `await`** operator.
+
+```js
+const webElements = await I.grabWebElements('#button');
+```
+
+#### Parameters
+
+-   `locator` **([string][17] | [object][16])** element located by CSS|XPath|strict locator.
+
+Returns **[Promise][25]<any>** WebElement of being used Web helper
+
 ### moveCursorTo
 
 Moves cursor to element matched by locator.

package/docs/internal-api.md

@@ -96,117 +96,7 @@ module.exports = function() {
   });
 }
 ```
-You could get test stats when running with workers
 
-```js
-const { event } = require('codeceptjs');
-
-module.exports = function() {
-
-  event.dispatcher.on(event.workers.result, function (result) {
-
-    console.log(result);
-
-  });
-}
-
-// in console log
-FAIL  | 7 passed, 1 failed, 1 skipped   // 2s
-{
-  "tests": {
-  "passed": [
-    {
-      "type": "test",
-      "title": "Assert @C3",
-      "body": "() => { }",
-      "async": 0,
-      "sync": true,
-      "_timeout": 2000,
-      "_slow": 75,
-      "_retries": -1,
-      "timedOut": false,
-      "_currentRetry": 0,
-      "pending": false,
-      "opts": {},
-      "tags": [
-        "@C3"
-      ],
-      "uid": "xe4q1HdqpRrZG5dPe0JG+A",
-      "workerIndex": 3,
-      "retries": -1,
-      "duration": 493,
-      "err": null,
-      "parent": {
-        "title": "My",
-        "ctx": {},
-        "suites": [],
-        "tests": [],
-        "root": false,
-        "pending": false,
-        "_retries": -1,
-        "_beforeEach": [],
-        "_beforeAll": [],
-        "_afterEach": [],
-        "_afterAll": [],
-        "_timeout": 2000,
-        "_slow": 75,
-        "_bail": false,
-        "_onlyTests": [],
-        "_onlySuites": [],
-        "delayed": false
-      },
-      "steps": [
-        {
-          "actor": "I",
-          "name": "amOnPage",
-          "status": "success",
-          "agrs": [
-            "https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST"
-          ],
-          "startedAt": 1698760652610,
-          "startTime": 1698760652611,
-          "endTime": 1698760653098,
-          "finishedAt": 1698760653098,
-          "duration": 488
-        },
-        {
-          "actor": "I",
-          "name": "grabCurrentUrl",
-          "status": "success",
-          "agrs": [],
-          "startedAt": 1698760653098,
-          "startTime": 1698760653098,
-          "endTime": 1698760653099,
-          "finishedAt": 1698760653099,
-          "duration": 1
-        }
-      ]
-    }
-  ],
-    "failed": [],
-    "skipped": []
-}
-}
-```
-
-CodeceptJS also exposes the env var `process.env.RUNS_WITH_WORKERS` when running tests with `run-workers` command so that you could handle the events better in your plugins/helpers
-
-```js
-const { event } = require('codeceptjs');
-
-module.exports = function() {
-    // this event would trigger the  `_publishResultsToTestrail` when running `run-workers` command
-  event.dispatcher.on(event.workers.result, async () => {
-    await _publishResultsToTestrail();
-  });
-  
-  // this event would not trigger the  `_publishResultsToTestrail` multiple times when running `run-workers` command
-  event.dispatcher.on(event.all.result, async () => {
-      // when running `run` command, this env var is undefined
-    if (!process.env.RUNS_WITH_WORKERS) await _publishResultsToTestrail();
-  });
-}
-```
 Available events:
 
 * `event.test.before(test)` - *async* when `Before` hooks from helpers and from test is executed