codeceptjs 3.5.9 → 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;
@@ -368,7 +368,7 @@ class Appium extends Webdriver {
       if (context.web) return this.switchToWeb(context.web);
       if (context.webview) return this.switchToWeb(context.webview);
     }
-    return this._switchToContext(context);
+    return this.switchToContext(context);
   }
 
   _withinEnd() {
@@ -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();
   }
 
@@ -834,7 +834,7 @@ class Appium extends Webdriver {
    *
    * @param {*} context the context to switch to
    */
-  async _switchToContext(context) {
+  async switchToContext(context) {
     return this.browser.switchContext(context);
   }
 
@@ -858,11 +858,11 @@ class Appium extends Webdriver {
     this.isWeb = true;
     this.defaultContext = 'body';
 
-    if (context) return this._switchToContext(context);
+    if (context) return this.switchToContext(context);
     const contexts = await this.grabAllContexts();
     this.debugSection('Contexts', contexts.toString());
     for (const idx in contexts) {
-      if (contexts[idx].match(/^WEBVIEW/)) return this._switchToContext(contexts[idx]);
+      if (contexts[idx].match(/^WEBVIEW/)) return this.switchToContext(contexts[idx]);
     }
 
     throw new Error('No WEBVIEW could be guessed, please specify one in params');
@@ -885,8 +885,8 @@ class Appium extends Webdriver {
     this.isWeb = false;
     this.defaultContext = '//*';
 
-    if (context) return this._switchToContext(context);
-    return this._switchToContext('NATIVE_APP');
+    if (context) return this.switchToContext(context);
+    return this.switchToContext('NATIVE_APP');
   }
 
   /**
@@ -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

@@ -94,6 +94,7 @@ const pathSeparator = path.sep;
  * @prop {boolean} [ignoreHTTPSErrors] - Allows access to untrustworthy pages, e.g. to a page with an expired certificate. Default value is `false`
  * @prop {boolean} [bypassCSP] - bypass Content Security Policy or CSP
  * @prop {boolean} [highlightElement] - highlight the interacting elements. Default: false. Note: only activate under verbose mode (--verbose).
+ * @prop {object} [recordHar] - record HAR and will be saved to `output/har`. See more of [HAR options](https://playwright.dev/docs/api/class-browser#browser-new-context-option-record-har).
  */
 const config = {};
 
@@ -141,6 +142,21 @@ const config = {};
  * * `trace`: enables trace recording for failed tests; trace are saved into `output/trace` folder
  * * `keepTraceForPassedTests`: - save trace for passed tests
  *
+ * #### HAR Recording Customization
+ *
+ * A HAR file is an HTTP Archive file that contains a record of all the network requests that are made when a page is loaded.
+ * It contains information about the request and response headers, cookies, content, timings, and more. You can use HAR files to mock network requests in your tests.
+ * HAR will be saved to `output/har`. More info could be found here https://playwright.dev/docs/api/class-browser#browser-new-context-option-record-har.
+ *
+ * ```
+ * ...
+ * recordHar: {
+ *     mode: 'minimal', // possible values: 'minimal'|'full'.
+ *     content: 'embed' // possible values:  "omit"|"embed"|"attach".
+ * }
+ * ...
+ *```
+ *
  * #### Example #1: Wait for 0 network connections.
  *
  * ```js
@@ -346,7 +362,7 @@ class Playwright extends Helper {
       ignoreLog: ['warning', 'log'],
       uniqueScreenshotNames: false,
       manualStart: false,
-      getPageTimeout: 0,
+      getPageTimeout: 30000,
       waitForNavigation: 'load',
       restart: false,
       keepCookies: false,
@@ -455,9 +471,10 @@ class Playwright extends Helper {
     }
   }
 
-  async _before() {
+  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;
@@ -487,6 +504,15 @@ class Playwright extends Helper {
       }
       if (this.options.bypassCSP) contextOptions.bypassCSP = this.options.bypassCSP;
       if (this.options.recordVideo) contextOptions.recordVideo = this.options.recordVideo;
+      if (this.options.recordHar) {
+        const harExt = this.options.recordHar.content && this.options.recordHar.content === 'attach' ? 'zip' : 'har';
+        const fileName = `${`${global.output_dir}${path.sep}har${path.sep}${uuidv4()}_${clearString(this.currentRunningTest.title)}`.slice(0, 245)}.${harExt}`;
+        const dir = path.dirname(fileName);
+        if (!fileExists(dir)) fs.mkdirSync(dir);
+        this.options.recordHar.path = fileName;
+        this.currentRunningTest.artifacts.har = fileName;
+        contextOptions.recordHar = this.options.recordHar;
+      }
       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;
@@ -842,6 +868,7 @@ class Playwright extends Helper {
     this.context = null;
     this.frame = null;
     popupStore.clear();
+    if (this.options.recordHar) await this.browserContext.close();
     await this.browser.close();
   }
 
@@ -1172,6 +1199,33 @@ class Playwright extends Helper {
     return this.page.reload({ timeout: this.options.getPageTimeout, waitUntil: this.options.waitForNavigation });
   }
 
+  /**
+   * Replaying from HAR
+   *
+   * ```js
+   *  // Replay API requests from HAR.
+   *  // Either use a matching response from the HAR,
+   *  // or abort the request if nothing matches.
+   *    I.replayFromHar('./output/har/something.har', { url: "*\/**\/api/v1/fruits" });
+   *    I.amOnPage('https://demo.playwright.dev/api-mocking');
+   *    I.see('CodeceptJS');
+   * ```
+   *
+   * @param {string} harFilePath Path to recorded HAR file
+   * @param {object} [opts] [Options for replaying from HAR](https://playwright.dev/docs/api/class-page#page-route-from-har)
+   *
+   * @returns Promise<void>
+   */
+  async replayFromHar(harFilePath, opts) {
+    const file = path.join(global.codecept_dir, harFilePath);
+
+    if (!fileExists(file)) {
+      throw new Error(`File at ${file} cannot be found on local system`);
+    }
+
+    await this.page.routeFromHAR(harFilePath, opts);
+  }
+
   /**
    * Scroll page to the top.
    * 
@@ -1396,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
    *
@@ -2211,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();
@@ -2802,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]);
@@ -2822,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;
     });
@@ -2860,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;
     });
@@ -3083,6 +3177,10 @@ class Playwright extends Helper {
         test.artifacts[`trace_${sessionName}`] = await saveTraceForContext(this.sessionPages[sessionName].context, `${test.title}_${sessionName}.failed`);
       }
     }
+
+    if (this.options.recordHar) {
+      test.artifacts.har = this.currentRunningTest.artifacts.har;
+    }
   }
 
   async _passed(test) {
@@ -3110,6 +3208,10 @@ class Playwright extends Helper {
         await this.browserContext.tracing.stop();
       }
     }
+
+    if (this.options.recordHar) {
+      test.artifacts.har = this.currentRunningTest.artifacts.har;
+    }
   }
 
   /**
@@ -3520,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

@@ -440,7 +440,7 @@ let settings = await I.grabSettings();
 
 Returns **[Promise][6]<[string][5]>** Appium: support Android and iOS
 
-### \_switchToContext
+### switchToContext
 
 Switch to the specified context.
 
@@ -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