codeceptjs 3.5.11 → 3.5.12-beta.2

package/lib/helper/WebDriver.js

@@ -63,6 +63,8 @@ const webRoot = 'body';
  * @prop {boolean} [manualStart=false] - do not start browser before a test, start it manually inside a helper with `this.helpers["WebDriver"]._startBrowser()`.
  * @prop {object} [timeouts] [WebDriver timeouts](http://webdriver.io/docs/timeouts.html) defined as hash.
  * @prop {boolean} [highlightElement] - highlight the interacting elements. Default: false. Note: only activate under verbose mode (--verbose).
+ * @prop {string} [logLevel=silent] - level of logging verbosity. Default: silent. Options: trace | debug | info | warn | error | silent. More info: https://webdriver.io/docs/configuration/#loglevel
+ * @prop {boolean} [devtoolsProtocol=false] - enable devtools protocol. Default: false. More info: https://webdriver.io/docs/automationProtocols/#devtools-protocol.
  */
 const config = {};
 
@@ -72,6 +74,13 @@ const config = {};
  *
  * WebDriver requires Selenium Server and ChromeDriver/GeckoDriver to be installed. Those tools can be easily installed via NPM. Please check [Testing with WebDriver](https://codecept.io/webdriver/#testing-with-webdriver) for more details.
  *
+ * With the release of WebdriverIO version v8.14.0, and onwards, all driver management hassles are now a thing of the past 🙌. Read more [here](https://webdriver.io/blog/2023/07/31/driver-management/).
+ * One of the significant advantages of this update is that you can now get rid of any driver services you previously had to manage, such as
+ * `wdio-chromedriver-service`, `wdio-geckodriver-service`, `wdio-edgedriver-service`, `wdio-safaridriver-service`, and even `@wdio/selenium-standalone-service`.
+ *
+ * For those who require custom driver options, fear not; WebDriver Helper allows you to pass in driver options through custom WebDriver configuration.
+ * If you have a custom grid, use a cloud service, or prefer to run your own driver, there's no need to worry since WebDriver Helper will only start a driver when there are no other connection information settings like hostname or port specified.
+ *
  * <!-- configuration -->
  *
  * Example:
@@ -93,6 +102,28 @@ const config = {};
  * }
  * ```
  *
+ * Testing Chrome locally is now more convenient than ever. You can define a browser channel, and WebDriver Helper will take care of downloading the specified browser version for you.
+ * For example:
+ *
+ * ```js
+ * {
+ *    helpers: {
+ *      WebDriver : {
+ *        smartWait: 5000,
+ *        browser: "chrome",
+ *        browserVersion: '116.0.5793.0', // or 'stable', 'beta', 'dev' or 'canary'
+ *        restart: false,
+ *        windowSize: "maximize",
+ *        timeouts: {
+ *          "script": 60000,
+ *          "page load": 10000
+ *        }
+ *      }
+ *    }
+ * }
+ * ```
+ *
+ *
  * Example with basic authentication
  * ```js
  * {
@@ -133,6 +164,25 @@ const config = {};
  * }
  * ```
  *
+ * ### Running with devtools protocol
+ *
+ * ```js
+ * {
+ *    helpers: {
+ *      WebDriver : {
+ *        url: "http://localhost",
+ *        browser: "chrome",
+ *        devtoolsProtocol: true,
+ *        desiredCapabilities: {
+ *          chromeOptions: {
+ *            args: [ "--headless", "--disable-gpu", "--no-sandbox" ]
+ *          }
+ *        }
+ *      }
+ *    }
+ * }
+ * ```
+ *
  * ### Internet Explorer
  *
  * Additional configuration params can be used from [IE options](https://seleniumhq.github.io/selenium/docs/api/rb/Selenium/WebDriver/IE/Options.html)
@@ -415,7 +465,6 @@ class WebDriver extends Helper {
   _validateConfig(config) {
     const defaults = {
       logLevel: 'silent',
-      path: '/wd/hub',
       // codeceptjs
       remoteFileUpload: true,
       smartWait: 0,
@@ -435,12 +484,17 @@ class WebDriver extends Helper {
     // override defaults with config
     config = Object.assign(defaults, config);
 
-    if (typeof config.host !== 'undefined') config.hostname = config.host; // webdriverio spec
+    if (config.host) {
+      // webdriverio spec
+      config.hostname = config.host;
+      config.path = '/wd/hub';
+    }
     config.baseUrl = config.url || config.baseUrl;
     if (config.desiredCapabilities && Object.keys(config.desiredCapabilities).length) {
       config.capabilities = config.desiredCapabilities;
     }
     config.capabilities.browserName = config.browser || config.capabilities.browserName;
+    config.capabilities.browserVersion = config.browserVersion || config.capabilities.browserVersion;
     if (config.capabilities.chromeOptions) {
       config.capabilities['goog:chromeOptions'] = config.capabilities.chromeOptions;
       delete config.capabilities.chromeOptions;
@@ -542,6 +596,10 @@ class WebDriver extends Helper {
         delete this.options.capabilities.hostname;
         delete this.options.capabilities.port;
         delete this.options.capabilities.path;
+        if (this.options.devtoolsProtocol) {
+          if (!['chrome', 'chromium'].includes(this.options.browser.toLowerCase())) throw Error('The devtools protocol is only working with Chrome or Chromium');
+          this.options.automationProtocol = 'devtools';
+        }
         this.browser = await webdriverio.remote(this.options);
       }
     } catch (err) {
@@ -1043,7 +1101,8 @@ class WebDriver extends Helper {
     assertElementExists(res, field, 'Field');
     const elem = usingFirstElement(res);
     highlightActiveElement.call(this, elem);
-    return elem.setValue(value.toString());
+    await elem.clearValue();
+    await elem.setValue(value.toString());
   }
 
   /**
@@ -1055,6 +1114,10 @@ class WebDriver extends Helper {
     assertElementExists(res, field, 'Field');
     const elem = usingFirstElement(res);
     highlightActiveElement.call(this, elem);
+    if (this.options.automationProtocol) {
+      const curentValue = await elem.getValue();
+      return elem.setValue(curentValue + value.toString());
+    }
     return elem.addValue(value.toString());
   }
 
@@ -1067,6 +1130,9 @@ class WebDriver extends Helper {
     assertElementExists(res, field, 'Field');
     const elem = usingFirstElement(res);
     highlightActiveElement.call(this, elem);
+    if (this.options.automationProtocol) {
+      return elem.setValue('');
+    }
     return elem.clearValue(getElementId(elem));
   }
 
@@ -1120,7 +1186,7 @@ class WebDriver extends Helper {
     const el = usingFirstElement(res);
 
     // Remote Upload (when running Selenium Server)
-    if (this.options.remoteFileUpload) {
+    if (this.options.remoteFileUpload && !this.options.automationProtocol) {
       try {
         this.debugSection('File', 'Uploading file to remote server');
         file = await this.browser.uploadFile(file);
@@ -1498,35 +1564,33 @@ class WebDriver extends Helper {
   async seeCssPropertiesOnElements(locator, cssProperties) {
     const res = await this._locate(locator);
     assertElementExists(res, locator);
+
+    const cssPropertiesCamelCase = convertCssPropertiesToCamelCase(cssProperties);
     const elemAmount = res.length;
+    let props = [];
 
-    let props = await forEachAsync(res, async (el) => {
-      return forEachAsync(Object.keys(cssProperties), async (prop) => {
-        const propValue = await this.browser.getElementCSSValue(getElementId(el), prop);
-        if (isColorProperty(prop) && propValue && propValue.value) {
-          return convertColorToRGBA(propValue.value);
+    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);
         }
-        return propValue;
-      });
-    });
-
-    const cssPropertiesCamelCase = convertCssPropertiesToCamelCase(cssProperties);
+      }
+    }
 
     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) {
-        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;
+        // eslint-disable-next-line eqeqeq
+        if (val[i] != values[i]) return false;
       }
       return true;
     });
-    return assert.ok(
-      chunked.length === elemAmount,
-      `expected all elements (${(new Locator(locator))}) to have CSS property ${JSON.stringify(cssProperties)}`,
-    );
+    return equals(`all elements (${(new Locator(locator))}) to have CSS property ${JSON.stringify(cssProperties)}`).assert(chunked.length, elemAmount);
   }
 
   /**
@@ -1546,9 +1610,9 @@ class WebDriver extends Helper {
     let chunked = chunkArray(attrs, values.length);
     chunked = chunked.filter((val) => {
       for (let i = 0; i < val.length; ++i) {
-        const _acutal = Number.isNaN(val[i]) || (typeof values[i]) === 'string' ? val[i] : Number.parseInt(val[i], 10);
+        const _actual = 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;
+        if (_actual !== _expected) return false;
       }
       return true;
     });
@@ -1672,7 +1736,11 @@ class WebDriver extends Helper {
     const res = await this._locate(withStrictLocator(locator), true);
     assertElementExists(res, locator);
     const elem = usingFirstElement(res);
-    return elem.moveTo({ xOffset, yOffset });
+    try {
+      await elem.moveTo({ xOffset, yOffset });
+    } catch (e) {
+      debug(e.message);
+    }
   }
 
   /**
@@ -1925,7 +1993,7 @@ class WebDriver extends Helper {
    * {{> resizeWindow }}
    */
   async resizeWindow(width, height) {
-    return this._resizeBrowserWindow(this.browser, width, height);
+    return this.browser.setWindowSize(width, height);
   }
 
   async _resizeBrowserWindow(browser, width, height) {
@@ -2306,12 +2374,33 @@ class WebDriver extends Helper {
     return this.browser.waitUntil(async () => this.browser.execute(fn, ...args), { timeout: aSec * 1000, timeoutMsg: '' });
   }
 
+  /**
+   * {{> waitForNumberOfTabs }}
+   */
+  async waitForNumberOfTabs(expectedTabs, sec) {
+    const waitTimeout = sec ? sec * 1000 : this.options.waitForTimeoutInSeconds;
+    let currentTabs;
+    let count = 0;
+
+    do {
+      currentTabs = await this.grabNumberOfOpenTabs();
+      await this.wait(1);
+      count += 1000;
+      if (currentTabs >= expectedTabs) return;
+    } while (count <= waitTimeout);
+
+    throw new Error(`Expected ${expectedTabs} tabs are not met after ${waitTimeout / 1000} sec.`);
+  }
+
   /**
    * {{> switchTo }}
    */
   async switchTo(locator) {
     this.browser.isInsideFrame = true;
     if (Number.isInteger(locator)) {
+      if (this.options.automationProtocol) {
+        return this.browser.switchToFrame(locator + 1);
+      }
       return this.browser.switchToFrame(locator);
     }
     if (!locator) {
@@ -2448,21 +2537,41 @@ class WebDriver extends Helper {
   }
 
   /**
+   * This method is **deprecated**.
+   *
+   *
    * {{> setGeoLocation }}
    */
-  async setGeoLocation(latitude, longitude, altitude = null) {
-    if (altitude) {
-      return this.browser.setGeoLocation({ latitude, longitude });
+  async setGeoLocation(latitude, longitude) {
+    if (!this.options.automationProtocol) {
+      console.log(`setGeoLocation deprecated:
+    * This command is deprecated due to using deprecated JSON Wire Protocol command. More info: https://webdriver.io/docs/api/jsonwp/#setgeolocation
+    * Switch to devtools protocol to use this command by setting devtoolsProtocol: true in the configuration`);
+      return;
     }
-    return this.browser.setGeoLocation({ latitude, longitude, altitude });
+    this.geoLocation = { latitude, longitude };
+    const puppeteerBrowser = await this.browser.getPuppeteer();
+    await this.browser.call(async () => {
+      const pages = await puppeteerBrowser.pages();
+      await pages[0].setGeolocation({ latitude, longitude });
+    });
   }
 
   /**
+   * This method is **deprecated**.
+   *
    * {{> grabGeoLocation }}
    *
    */
   async grabGeoLocation() {
-    return this.browser.getGeoLocation();
+    if (!this.options.automationProtocol) {
+      console.log(`grabGeoLocation deprecated:
+    * This command is deprecated due to using deprecated JSON Wire Protocol command. More info: https://webdriver.io/docs/api/jsonwp/#getgeolocation
+    * Switch to devtools protocol to use this command by setting devtoolsProtocol: true in the configuration`);
+      return;
+    }
+    if (!this.geoLocation) return 'No GeoLocation is set!';
+    return this.geoLocation;
   }
 
   /**
@@ -2658,7 +2767,7 @@ async function proceedSeeField(assertType, field, value) {
     }
   };
 
-  const proceedSingle = el => this.browser.getElementAttribute(getElementId(el), 'value').then((res) => {
+  const proceedSingle = el => el.getValue().then((res) => {
     if (res === null) {
       throw new Error(`Element ${el.selector} has no value attribute`);
     }

package/lib/locator.js

@@ -1,4 +1,4 @@
-const cssToXPath = require('convert-cssxpath');
+let cssToXPath;
 const { sprintf } = require('sprintf-js');
 
 const { xpathLocator } = require('./utils');
@@ -158,11 +158,26 @@ class Locator {
   }
 
   /**
+   * @param {string} [pseudoSelector] CSS to XPath extension pseudo: https://www.npmjs.com/package/csstoxpath?activeTab=explore#extension-pseudos
    * @returns {string}
    */
-  toXPath() {
+  toXPath(pseudoSelector = '') {
+    const limitation = [':nth-of-type', ':first-of-type', ':last-of-type', ':nth-last-child', ':nth-last-of-type', ':checked', ':disabled', ':enabled', ':required', ':lang'];
+
+    if (pseudoSelector.includes(':text-')) {
+      cssToXPath = require('csstoxpath');
+    } else if (this.value.includes('-')) {
+      if (!limitation.some(item => this.value.includes(item))) {
+        cssToXPath = require('csstoxpath');
+      }
+    } else if (limitation.some(item => this.value.includes(item))) {
+      cssToXPath = require('./css2xpath/js/css_to_xpath');
+    } else {
+      cssToXPath = require('./css2xpath/js/css_to_xpath');
+    }
+
     if (this.isXPath()) return this.value;
-    if (this.isCSS()) return cssToXPath.convert(this.value);
+    if (this.isCSS()) return cssToXPath(`${this.value}${pseudoSelector}`);
 
     throw new Error('Can\'t be converted to XPath');
   }
@@ -243,12 +258,24 @@ class Locator {
   }
 
   /**
+   * Find an element containing a text
    * @param {string} text
    * @returns {Locator}
    */
   withText(text) {
     text = xpathLocator.literal(text);
-    const xpath = sprintf('%s[%s]', this.toXPath(), `contains(., ${text})`);
+    const xpath = this.toXPath(`:text-contains-case(${text})`);
+    return new Locator({ xpath });
+  }
+
+  /**
+   * Find an element with exact text
+   * @param {string} text
+   * @returns {Locator}
+   */
+  withTextEquals(text) {
+    text = xpathLocator.literal(text);
+    const xpath = this.toXPath(`:text-case(${text})`);
     return new Locator({ xpath });
   }
 

package/lib/plugin/retryFailedStep.js

@@ -1,6 +1,7 @@
 const event = require('../event');
 const recorder = require('../recorder');
 const container = require('../container');
+const { log } = require('../output');
 
 const defaultConfig = {
   retries: 3,
@@ -99,7 +100,10 @@ module.exports = (config) => {
   config.when = when;
 
   event.dispatcher.on(event.step.started, (step) => {
-    if (process.env.TRY_TO) return;
+    if (process.env.TRY_TO === 'true') {
+      log('Info: RetryFailedStep plugin is disabled inside tryTo block');
+      return;
+    }
 
     // if a step is ignored - return
     for (const ignored of config.ignoredSteps) {

package/lib/plugin/retryTo.js

@@ -89,9 +89,9 @@ module.exports = function (config) {
     let err = null;
 
     return new Promise((done) => {
-      const tryBlock = () => {
+      const tryBlock = async () => {
         recorder.session.start(`retryTo ${tries}`);
-        callback(tries);
+        await callback(tries);
         recorder.add(() => {
           recorder.session.restore(`retryTo ${tries}`);
           done(null);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codeceptjs",
-  "version": "3.5.11",
+  "version": "3.5.12-beta.02",
   "description": "Supercharged End 2 End Testing Framework for NodeJS",
   "keywords": [
     "acceptance",
@@ -52,8 +52,11 @@
     "test:unit:webbapi:playwright": "mocha test/helper/Playwright_test.js",
     "test:unit:webbapi:puppeteer": "mocha test/helper/Puppeteer_test.js",
     "test:unit:webbapi:webDriver": "mocha test/helper/WebDriver_test.js",
+    "test:unit:webbapi:webDriver:noSeleniumServer": "mocha test/helper/WebDriver.noSeleniumServer_test.js",
+    "test:unit:webbapi:webDriver:devtools": "mocha test/helper/WebDriver_devtools_test.js --exit",
     "test:unit:webbapi:testCafe": "mocha test/helper/TestCafe_test.js",
     "test:unit:expect": "mocha test/helper/Expect_test.js",
+    "test:plugin": "mocha test/plugin/plugin_test.js",
     "def": "./runok.js def",
     "dev:graphql": "node test/data/graphql/index.js",
     "publish:site": "./runok.js publish:site",
@@ -67,29 +70,31 @@
     "@codeceptjs/helper": "2.0.1",
     "@cucumber/cucumber-expressions": "17",
     "@cucumber/gherkin": "26",
-    "@cucumber/messages": "22.0.0",
+    "@cucumber/messages": "24.0.1",
     "@xmldom/xmldom": "0.8.10",
     "acorn": "8.11.2",
     "arrify": "2.0.1",
     "axios": "1.6.3",
+    "bo-selector": "0.0.10",
     "chai": "4.3.8",
     "chai-deep-match": "1.2.1",
-    "chai-exclude": "^2.1.0",
-    "chai-json-schema": "^1.5.1",
-    "chai-json-schema-ajv": "^5.2.4",
-    "chai-match-pattern": "^1.3.0",
-    "chai-string": "^1.5.0",
+    "chai-exclude": "2.1.0",
+    "chai-json-schema": "1.5.1",
+    "chai-json-schema-ajv": "5.2.4",
+    "chai-match-pattern": "1.3.0",
+    "chai-string": "1.5.0",
     "chalk": "4.1.2",
     "commander": "11.1.0",
-    "convert-cssxpath": "1.0.2",
     "cross-spawn": "7.0.3",
+    "csstoxpath": "1.6.0",
+    "devtools": "8.27.2",
     "envinfo": "7.11.0",
     "escape-string-regexp": "4.0.0",
     "figures": "3.2.0",
     "fn-args": "4.0.0",
     "fs-extra": "11.2.0",
     "glob": "6.0.1",
-    "html-minifier-terser": "^7.2.0",
+    "html-minifier-terser": "7.2.0",
     "inquirer": "6.5.2",
     "joi": "17.11.0",
     "js-beautify": "1.14.11",
@@ -105,7 +110,8 @@
     "promise-retry": "1.1.1",
     "resq": "1.11.0",
     "sprintf-js": "1.1.1",
-    "uuid": "9.0"
+    "uuid": "9.0",
+    "xpath-builder": "0.0.7"
   },
   "optionalDependencies": {
     "@codeceptjs/detox-helper": "1.0.2"
@@ -115,12 +121,13 @@
     "@faker-js/faker": "7.6.0",
     "@pollyjs/adapter-puppeteer": "6.0.6",
     "@pollyjs/core": "5.1.0",
-    "@types/chai": "^4.3.7",
+    "@types/chai": "4.3.7",
     "@types/inquirer": "9.0.3",
-    "@types/node": "20.4.4",
+    "@types/node": "20.10.7",
     "@wdio/sauce-service": "8.27.0",
     "@wdio/selenium-standalone-service": "8.3.2",
-    "@wdio/utils": "8.27.0",
+    "@wdio/utils": "8.27.2",
+    "@xmldom/xmldom": "0.8.10",
     "apollo-server-express": "2.25.3",
     "chai-as-promised": "7.1.1",
     "chai-subset": "1.6.0",
@@ -130,7 +137,7 @@
     "electron": "28.0.0",
     "eslint": "8.56.0",
     "eslint-config-airbnb-base": "15.0.0",
-    "eslint-plugin-import": "2.29.0",
+    "eslint-plugin-import": "2.29.1",
     "eslint-plugin-mocha": "6.3.0",
     "expect": "29.7.0",
     "express": "4.18.2",
@@ -143,7 +150,7 @@
     "playwright": "1.40.1",
     "puppeteer": "21.1.1",
     "qrcode-terminal": "0.12.0",
-    "rosie": "2.1.0",
+    "rosie": "2.1.1",
     "runok": "0.9.3",
     "sinon": "17.0.1",
     "sinon-chai": "3.7.0",
@@ -151,13 +158,12 @@
     "ts-morph": "21.0.1",
     "ts-node": "10.9.2",
     "tsd-jsdoc": "2.5.0",
-    "typedoc": "0.25.4",
+    "typedoc": "0.25.7",
     "typedoc-plugin-markdown": "3.17.1",
     "typescript": "5.3.3",
     "wdio-docker-service": "1.5.0",
-    "webdriverio": "8.3.8",
+    "webdriverio": "8.27.2",
     "xml2js": "0.6.2",
-    "@xmldom/xmldom": "0.8.10",
     "xpath": "0.0.34"
   },
   "engines": {

package/typings/index.d.ts

@@ -97,7 +97,7 @@ declare namespace CodeceptJS {
      *   }
      * }
      * ```
-    */
+     */
     helpers?: {
       /**
        * Run web tests controlling browsers via Playwright engine.
@@ -289,7 +289,7 @@ declare namespace CodeceptJS {
      * ```js
      * bootstrap: 'bootstrap.js',
      * ```
-    */
+     */
     bootstrap?: (() => Promise<void>) | boolean | string;
     /**
      * [Execute code after tests](https://codecept.io/bootstrap/) finished.
@@ -303,7 +303,7 @@ declare namespace CodeceptJS {
      * ```js
      * teardown: 'teardown.js',
      * ```
-    */
+     */
     teardown?: (() => Promise<void>) | boolean | string;
     /**
      * [Execute code before launching tests in parallel mode](https://codecept.io/bootstrap/#bootstrapall-teardownall)
@@ -312,7 +312,7 @@ declare namespace CodeceptJS {
     bootstrapAll?: (() => Promise<void>) | boolean | string;
     /**
      * [Execute JS code after finishing tests in parallel mode](https://codecept.io/bootstrap/#bootstrapall-teardownall)
-    */
+     */
     teardownAll?: (() => Promise<void>) | boolean | string;
 
     /** Enable [localized test commands](https://codecept.io/translation/) */
@@ -328,7 +328,7 @@ declare namespace CodeceptJS {
      * ```
      * require: ["should"]
      * ```
-    */
+     */
     require?: Array<string>;
 
     /**
@@ -423,15 +423,18 @@ declare namespace CodeceptJS {
     | { ios: string }
     | { android: string; ios: string }
     | { react: string }
+    | { vue: string }
     | { shadow: string[] }
     | { custom: string };
 
   interface CustomLocators {}
+  interface OtherLocators { props?: object }
   type LocatorOrString =
     | string
     | ILocator
     | Locator
-    | CustomLocators;
+    | OtherLocators
+    | CustomLocators[keyof CustomLocators];
 
   type StringOrSecret = string | CodeceptJS.Secret;