codeceptjs 3.5.11 → 3.5.12-beta.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codeceptjs",
-  "version": "3.5.11",
+  "version": "3.5.12-beta.1",
   "description": "Supercharged End 2 End Testing Framework for NodeJS",
   "keywords": [
     "acceptance",
@@ -23,7 +23,6 @@
   },
   "files": [
     "bin",
-    "docs",
     "lib",
     "translations",
     "typings/**/*.d.ts"
@@ -52,8 +51,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,7 +69,7 @@
     "@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",
@@ -81,8 +83,9 @@
     "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",
@@ -117,10 +120,11 @@
     "@pollyjs/core": "5.1.0",
     "@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 +134,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 +147,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 +155,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;
 

package/typings/promiseBasedTypes.d.ts

@@ -4347,6 +4347,16 @@ declare namespace CodeceptJS {
          * @param [sec = 1] - (optional, `1` by default) time in seconds to wait
          */
         waitToHide(locator: CodeceptJS.LocatorOrString, sec?: number): Promise<any>;
+        /**
+         * Waits for number of tabs.
+         *
+         * ```js
+         * I.waitForNumberOfTabs(2);
+         * ```
+         * @param expectedTabs - expecting the number of tabs.
+         * @param sec - number of secs to wait.
+         */
+        waitForNumberOfTabs(expectedTabs: number, sec: number): Promise<any>;
         /**
          * Waiting for the part of the URL to match the expected. Useful for SPA to understand that page was changed.
          *
@@ -7454,6 +7464,16 @@ declare namespace CodeceptJS {
          * @param [sec = 1] - (optional, `1` by default) time in seconds to wait
          */
         waitToHide(locator: CodeceptJS.LocatorOrString, sec?: number): Promise<any>;
+        /**
+         * Waits for number of tabs.
+         *
+         * ```js
+         * I.waitForNumberOfTabs(2);
+         * ```
+         * @param expectedTabs - expecting the number of tabs.
+         * @param sec - number of secs to wait.
+         */
+        waitForNumberOfTabs(expectedTabs: number, sec: number): Promise<any>;
         /**
          * Waiting for the part of the URL to match the expected. Useful for SPA to understand that page was changed.
          *
@@ -8667,6 +8687,13 @@ declare namespace CodeceptJS {
      *
      * 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:
@@ -8688,6 +8715,28 @@ declare namespace CodeceptJS {
      * }
      * ```
      *
+     * 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
      * {
@@ -8728,6 +8777,25 @@ declare namespace CodeceptJS {
      * }
      * ```
      *
+     * ### 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)
@@ -10295,6 +10363,16 @@ 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): Promise<any>;
+        /**
+         * Waits for number of tabs.
+         *
+         * ```js
+         * I.waitForNumberOfTabs(2);
+         * ```
+         * @param expectedTabs - expecting the number of tabs.
+         * @param sec - number of secs to wait.
+         */
+        waitForNumberOfTabs(expectedTabs: number, sec: number): Promise<any>;
         /**
          * Switches frame or in case of null locator reverts to parent.
          *
@@ -10388,6 +10466,9 @@ declare namespace CodeceptJS {
          */
         grabPageScrollPosition(): Promise<PageScrollPosition>;
         /**
+         * This method is **deprecated**.
+         *
+         *
          * Set the current geo location
          *
          *
@@ -10397,10 +10478,12 @@ declare namespace CodeceptJS {
          * ```
          * @param latitude - to set.
          * @param longitude - to set
-         * @param [altitude = null] - (optional, null by default) to set
+         * @param [altitude] - (optional, null by default) to set
          */
         setGeoLocation(latitude: number, longitude: number, altitude?: number): Promise<any>;
         /**
+         * This method is **deprecated**.
+         *
          * Return the current geo location
          * Resumes test execution, so **should be used inside async function with `await`** operator.
          *

package/typings/types.d.ts

@@ -4583,6 +4583,17 @@ declare namespace CodeceptJS {
          * @returns automatically synchronized promise through #recorder
          */
         waitToHide(locator: CodeceptJS.LocatorOrString, sec?: number): void;
+        /**
+         * Waits for number of tabs.
+         *
+         * ```js
+         * I.waitForNumberOfTabs(2);
+         * ```
+         * @param expectedTabs - expecting the number of tabs.
+         * @param sec - number of secs to wait.
+         * @returns automatically synchronized promise through #recorder
+         */
+        waitForNumberOfTabs(expectedTabs: number, sec: number): void;
         /**
          * Waiting for the part of the URL to match the expected. Useful for SPA to understand that page was changed.
          *
@@ -7938,6 +7949,17 @@ declare namespace CodeceptJS {
          * @returns automatically synchronized promise through #recorder
          */
         waitToHide(locator: CodeceptJS.LocatorOrString, sec?: number): void;
+        /**
+         * Waits for number of tabs.
+         *
+         * ```js
+         * I.waitForNumberOfTabs(2);
+         * ```
+         * @param expectedTabs - expecting the number of tabs.
+         * @param sec - number of secs to wait.
+         * @returns automatically synchronized promise through #recorder
+         */
+        waitForNumberOfTabs(expectedTabs: number, sec: number): void;
         /**
          * Waiting for the part of the URL to match the expected. Useful for SPA to understand that page was changed.
          *
@@ -9255,6 +9277,8 @@ declare namespace CodeceptJS {
      * @property [manualStart = false] - do not start browser before a test, start it manually inside a helper with `this.helpers["WebDriver"]._startBrowser()`.
      * @property [timeouts] - [WebDriver timeouts](http://webdriver.io/docs/timeouts.html) defined as hash.
      * @property [highlightElement] - highlight the interacting elements. Default: false. Note: only activate under verbose mode (--verbose).
+     * @property [logLevel = silent] - level of logging verbosity. Default: silent. Options: trace | debug | info | warn | error | silent. More info: https://webdriver.io/docs/configuration/#loglevel
+     * @property [devtoolsProtocol = false] - enable devtools protocol. Default: false. More info: https://webdriver.io/docs/automationProtocols/#devtools-protocol.
      */
     type WebDriverConfig = {
         url: string;
@@ -9277,6 +9301,8 @@ declare namespace CodeceptJS {
         manualStart?: boolean;
         timeouts?: any;
         highlightElement?: boolean;
+        logLevel?: string;
+        devtoolsProtocol?: boolean;
     };
     /**
      * WebDriver helper which wraps [webdriverio](http://webdriver.io/) library to
@@ -9284,6 +9310,13 @@ declare namespace CodeceptJS {
      *
      * 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:
@@ -9305,6 +9338,28 @@ declare namespace CodeceptJS {
      * }
      * ```
      *
+     * 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
      * {
@@ -9345,6 +9400,25 @@ declare namespace CodeceptJS {
      * }
      * ```
      *
+     * ### 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)
@@ -11016,6 +11090,17 @@ declare namespace CodeceptJS {
          * @returns automatically synchronized promise through #recorder
          */
         waitForFunction(fn: string | ((...params: any[]) => any), argsOrSec?: any[] | number, sec?: number): void;
+        /**
+         * Waits for number of tabs.
+         *
+         * ```js
+         * I.waitForNumberOfTabs(2);
+         * ```
+         * @param expectedTabs - expecting the number of tabs.
+         * @param sec - number of secs to wait.
+         * @returns automatically synchronized promise through #recorder
+         */
+        waitForNumberOfTabs(expectedTabs: number, sec: number): void;
         /**
          * Switches frame or in case of null locator reverts to parent.
          *
@@ -11117,6 +11202,9 @@ declare namespace CodeceptJS {
          */
         grabPageScrollPosition(): Promise<PageScrollPosition>;
         /**
+         * This method is **deprecated**.
+         *
+         *
          * Set the current geo location
          *
          *
@@ -11126,11 +11214,13 @@ declare namespace CodeceptJS {
          * ```
          * @param latitude - to set.
          * @param longitude - to set
-         * @param [altitude = null] - (optional, null by default) to set
+         * @param [altitude] - (optional, null by default) to set
          * @returns automatically synchronized promise through #recorder
          */
         setGeoLocation(latitude: number, longitude: number, altitude?: number): void;
         /**
+         * This method is **deprecated**.
+         *
          * Return the current geo location
          * Resumes test execution, so **should be used inside async function with `await`** operator.
          *
@@ -11513,7 +11603,10 @@ declare namespace CodeceptJS {
         isStrict(): boolean;
         isAccessibilityId(): boolean;
         isBasic(): boolean;
-        toXPath(): string;
+        /**
+         * @param [pseudoSelector] - CSS to XPath extension pseudo: https://www.npmjs.com/package/csstoxpath?activeTab=explore#extension-pseudos
+         */
+        toXPath(pseudoSelector?: string): string;
         or(locator: CodeceptJS.LocatorOrString): Locator;
         find(locator: CodeceptJS.LocatorOrString): Locator;
         withChild(locator: CodeceptJS.LocatorOrString): Locator;
@@ -11521,7 +11614,14 @@ declare namespace CodeceptJS {
         at(position: number): Locator;
         first(): Locator;
         last(): Locator;
+        /**
+         * Find an element containing a text
+         */
         withText(text: string): Locator;
+        /**
+         * Find an element with exact text
+         */
+        withTextEquals(text: string): Locator;
         withAttr(attributes: {
             [key: string]: string;
         }): Locator;