codeceptjs 3.7.5-beta.9 → 3.7.6-beta.1

package/lib/utils.js

@@ -203,7 +203,7 @@ module.exports.test = {
           if (fs.existsSync(dataFile)) {
             break
           }
-          
+
           // Use Node.js child_process.spawnSync with platform-specific sleep commands
           // This avoids busy waiting and allows other processes to run
           try {
@@ -221,7 +221,7 @@ module.exports.test = {
               // No-op loop - much lighter than previous approaches
             }
           }
-          
+
           // Exponential backoff: gradually increase polling interval to reduce resource usage
           pollInterval = Math.min(pollInterval * 1.2, maxPollInterval)
         }
@@ -476,8 +476,12 @@ module.exports.isNotSet = function (obj) {
   return false
 }
 
-module.exports.emptyFolder = async directoryPath => {
-  require('child_process').execSync(`rm -rf ${directoryPath}/*`)
+module.exports.emptyFolder = directoryPath => {
+  // Do not throw on non-existent directory, since it may be created later
+  if (!fs.existsSync(directoryPath)) return
+  for (const file of fs.readdirSync(directoryPath)) {
+    fs.rmSync(path.join(directoryPath, file), { recursive: true, force: true })
+  }
 }
 
 module.exports.printObjectProperties = obj => {
@@ -576,6 +580,52 @@ module.exports.humanizeString = function (string) {
   return _result.join(' ').trim()
 }
 
+/**
+ * Creates a circular-safe replacer function for JSON.stringify
+ * @param {string[]} keysToSkip - Keys to skip during serialization to break circular references
+ * @returns {Function} Replacer function for JSON.stringify
+ */
+function createCircularSafeReplacer(keysToSkip = []) {
+  const seen = new WeakSet()
+  const defaultSkipKeys = ['parent', 'tests', 'suite', 'root', 'runner', 'ctx']
+  const skipKeys = new Set([...defaultSkipKeys, ...keysToSkip])
+
+  return function (key, value) {
+    // Skip specific keys that commonly cause circular references
+    if (key && skipKeys.has(key)) {
+      return undefined
+    }
+
+    if (value === null || typeof value !== 'object') {
+      return value
+    }
+
+    // Handle circular references
+    if (seen.has(value)) {
+      return `[Circular Reference to ${value.constructor?.name || 'Object'}]`
+    }
+
+    seen.add(value)
+    return value
+  }
+}
+
+/**
+ * Safely stringify an object, handling circular references
+ * @param {any} obj - Object to stringify
+ * @param {string[]} keysToSkip - Additional keys to skip during serialization
+ * @param {number} space - Number of spaces for indentation (default: 0)
+ * @returns {string} JSON string representation
+ */
+module.exports.safeStringify = function (obj, keysToSkip = [], space = 0) {
+  try {
+    return JSON.stringify(obj, createCircularSafeReplacer(keysToSkip), space)
+  } catch (error) {
+    // Fallback for any remaining edge cases
+    return JSON.stringify({ error: `Failed to serialize: ${error.message}` }, null, space)
+  }
+}
+
 module.exports.serializeError = function (error) {
   if (error) {
     const { stack, uncaught, message, actual, expected } = error

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codeceptjs",
-  "version": "3.7.5-beta.9",
+  "version": "3.7.6-beta.1",
   "description": "Supercharged End 2 End Testing Framework for NodeJS",
   "keywords": [
     "acceptance",
@@ -29,14 +29,19 @@
     "docs/webapi/**"
   ],
   "main": "lib/index.js",
+  "module": "lib/index.js",
+  "types": "typings/index.d.ts",
   "exports": {
-    ".": "./lib/index.js",
+    ".": {
+      "import": "./lib/index.js",
+      "require": "./lib/index.js",
+      "types": "./typings/index.d.ts"
+    },
     "./lib/*": "./lib/*.js",
     "./els": "./lib/els.js",
     "./effects": "./lib/effects.js",
     "./steps": "./lib/steps.js"
   },
-  "types": "typings/index.d.ts",
   "bin": {
     "codeceptjs": "./bin/codecept.js"
   },
@@ -78,12 +83,12 @@
     "@codeceptjs/configure": "1.0.6",
     "@codeceptjs/helper": "2.0.4",
     "@cucumber/cucumber-expressions": "18",
-    "@cucumber/gherkin": "32.1.2",
-    "@cucumber/messages": "27.2.0",
+    "@cucumber/gherkin": "35.1.0",
+    "@cucumber/messages": "29.0.1",
     "@xmldom/xmldom": "0.9.8",
-    "acorn": "8.14.1",
+    "acorn": "8.15.0",
     "arrify": "3.0.0",
-    "axios": "1.11.0",
+    "axios": "1.12.2",
     "chalk": "4.1.2",
     "cheerio": "^1.0.0",
     "chokidar": "^4.0.3",
@@ -95,20 +100,20 @@
     "escape-string-regexp": "4.0.0",
     "figures": "3.2.0",
     "fn-args": "4.0.0",
-    "fs-extra": "11.3.0",
+    "fs-extra": "11.3.2",
     "fuse.js": "^7.0.0",
     "glob": ">=9.0.0 <12",
     "html-minifier-terser": "7.2.0",
     "inquirer": "^8.2.7",
     "invisi-data": "^1.0.0",
-    "joi": "17.13.3",
+    "joi": "18.0.1",
     "js-beautify": "1.15.4",
     "lodash.clonedeep": "4.5.0",
     "lodash.merge": "4.6.2",
     "lodash.shuffle": "4.2.0",
     "mkdirp": "3.0.1",
-    "mocha": "11.6.0",
-    "monocart-coverage-reports": "2.12.6",
+    "mocha": "11.7.2",
+    "monocart-coverage-reports": "2.12.9",
     "ms": "2.1.3",
     "multer": "^2.0.2",
     "ora-classic": "5.4.2",
@@ -120,35 +125,35 @@
     "uuid": "11.1.0"
   },
   "optionalDependencies": {
-    "@codeceptjs/detox-helper": "1.1.8"
+    "@codeceptjs/detox-helper": "1.1.13"
   },
   "devDependencies": {
-    "@apollo/server": "^4",
+    "@apollo/server": "^5",
     "@codeceptjs/expect-helper": "^1.0.2",
     "@codeceptjs/mock-request": "0.3.1",
     "@eslint/eslintrc": "3.3.1",
-    "@eslint/js": "9.34.0",
+    "@eslint/js": "9.36.0",
     "@faker-js/faker": "9.8.0",
     "@pollyjs/adapter-puppeteer": "6.0.6",
     "@pollyjs/core": "6.0.6",
     "@types/chai": "5.2.2",
-    "@types/inquirer": "9.0.7",
-    "@types/node": "24.0.10",
+    "@types/inquirer": "9.0.9",
+    "@types/node": "24.5.2",
     "@wdio/sauce-service": "9.12.5",
     "@wdio/selenium-standalone-service": "8.15.0",
-    "@wdio/utils": "9.15.0",
+    "@wdio/utils": "9.19.2",
     "@xmldom/xmldom": "0.9.8",
     "chai": "^4.0.0",
     "chai-as-promised": "7.1.2",
     "chai-subset": "1.6.0",
     "documentation": "14.0.3",
-    "electron": "37.2.3",
-    "eslint": "^9.24.0",
+    "electron": "38.1.2",
+    "eslint": "^9.36.0",
     "eslint-plugin-import": "2.32.0",
     "eslint-plugin-mocha": "11.1.0",
-    "expect": "30.0.5",
+    "expect": "30.1.2",
     "express": "^5.1.0",
-    "globals": "16.2.0",
+    "globals": "16.4.0",
     "graphql": "16.11.0",
     "graphql-tag": "^2.12.6",
     "husky": "9.1.7",
@@ -157,7 +162,7 @@
     "jsdoc-typeof-plugin": "1.0.0",
     "json-server": "0.17.4",
     "mochawesome": "^7.1.3",
-    "playwright": "1.54.1",
+    "playwright": "1.55.1",
     "prettier": "^3.3.2",
     "puppeteer": "24.15.0",
     "qrcode-terminal": "0.12.0",
@@ -171,8 +176,8 @@
     "ts-node": "10.9.2",
     "tsd": "^0.33.0",
     "tsd-jsdoc": "2.5.0",
-    "typedoc": "0.28.10",
-    "typedoc-plugin-markdown": "4.8.1",
+    "typedoc": "0.28.13",
+    "typedoc-plugin-markdown": "4.9.0",
     "typescript": "5.8.3",
     "wdio-docker-service": "3.2.1",
     "webdriverio": "9.12.5",
@@ -189,5 +194,8 @@
     "compilerOptions": {
       "strict": false
     }
+  },
+  "overrides": {
+    "tmp": "0.2.5"
   }
 }

package/typings/promiseBasedTypes.d.ts

@@ -2737,7 +2737,6 @@ declare namespace CodeceptJS {
      */
     // @ts-ignore
     // @ts-ignore
-    // @ts-ignore
     type PlaywrightConfig = {
         url?: string;
         browser?: 'chromium' | 'firefox' | 'webkit' | 'electron';
@@ -6117,7 +6116,6 @@ declare namespace CodeceptJS {
      */
     // @ts-ignore
     // @ts-ignore
-    // @ts-ignore
     type PuppeteerConfig = {
         url: string;
         basicAuth?: any;
@@ -6541,6 +6539,17 @@ declare namespace CodeceptJS {
          * {{ react }}
          */
         _locate(): Promise<any>;
+        /**
+         * Get single element by different locator types, including strict locator
+         * Should be used in custom helpers:
+         *
+         * ```js
+         * const element = await this.helpers['Puppeteer']._locateElement({name: 'password'});
+         * ```
+         *
+         * {{ react }}
+         */
+        _locateElement(): Promise<any>;
         /**
          * Find a checkbox by providing human-readable text:
          * NOTE: Assumes the checkable element exists
@@ -6577,6 +6586,17 @@ declare namespace CodeceptJS {
          * @returns WebElement of being used Web helper
          */
         grabWebElements(locator: CodeceptJS.LocatorOrString): Promise<any>;
+        /**
+         * 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 locator - element located by CSS|XPath|strict locator.
+         * @returns WebElement of being used Web helper
+         */
+        grabWebElement(locator: CodeceptJS.LocatorOrString): Promise<any>;
         /**
          * Switch focus to a particular tab by its number. It waits tabs loading and then switch tab
          *
@@ -7912,6 +7932,22 @@ declare namespace CodeceptJS {
          */
         flushWebSocketMessages(): Promise<any>;
     }
+    /**
+     * Find elements using Puppeteer's native element discovery methods
+     * Note: Unlike Playwright, Puppeteer's Locator API doesn't have .all() method for multiple elements
+     * @param matcher - Puppeteer context to search within
+     * @param locator - Locator specification
+     * @returns Array of ElementHandle objects
+     */
+    function findElements(matcher: any, locator: any | string): Promise<any[]>;
+    /**
+     * Find a single element using Puppeteer's native element discovery methods
+     * Note: Puppeteer Locator API doesn't have .first() method like Playwright
+     * @param matcher - Puppeteer context to search within
+     * @param locator - Locator specification
+     * @returns Single ElementHandle object
+     */
+    function findElement(matcher: any, locator: any | string): Promise<object>;
     /**
      * ## Configuration
      * @property [endpoint] - API base URL
@@ -7926,7 +7962,6 @@ declare namespace CodeceptJS {
      */
     // @ts-ignore
     // @ts-ignore
-    // @ts-ignore
     type RESTConfig = {
         endpoint?: string;
         prettyPrintJson?: boolean;
@@ -8052,6 +8087,16 @@ declare namespace CodeceptJS {
          * @returns response
          */
         sendGetRequest(url: any, headers?: any): Promise<any>;
+        /**
+         * Send HEAD request to REST API
+         *
+         * ```js
+         * I.sendHeadRequest('/api/users.json');
+         * ```
+         * @param [headers = {}] - the headers object to be sent. By default, it is sent as an empty object
+         * @returns response
+         */
+        sendHeadRequest(url: any, headers?: any): Promise<any>;
         /**
          * Sends POST request to API.
          *
@@ -9074,7 +9119,6 @@ declare namespace CodeceptJS {
      */
     // @ts-ignore
     // @ts-ignore
-    // @ts-ignore
     type WebDriverConfig = {
         url: string;
         browser: string;
@@ -9545,6 +9589,17 @@ declare namespace CodeceptJS {
          * @returns WebElement of being used Web helper
          */
         grabWebElements(locator: CodeceptJS.LocatorOrString): Promise<any>;
+        /**
+         * 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 locator - element located by CSS|XPath|strict locator.
+         * @returns WebElement of being used Web helper
+         */
+        grabWebElement(locator: CodeceptJS.LocatorOrString): Promise<any>;
         /**
          * Set [WebDriver timeouts](https://webdriver.io/docs/timeouts.html) in realtime.
          *

package/typings/types.d.ts

@@ -2827,7 +2827,6 @@ declare namespace CodeceptJS {
      */
     // @ts-ignore
     // @ts-ignore
-    // @ts-ignore
     type PlaywrightConfig = {
         url?: string;
         browser?: 'chromium' | 'firefox' | 'webkit' | 'electron';
@@ -6358,7 +6357,6 @@ declare namespace CodeceptJS {
      */
     // @ts-ignore
     // @ts-ignore
-    // @ts-ignore
     type PuppeteerConfig = {
         url: string;
         basicAuth?: any;
@@ -6798,6 +6796,17 @@ declare namespace CodeceptJS {
          * {{ react }}
          */
         _locate(): void;
+        /**
+         * Get single element by different locator types, including strict locator
+         * Should be used in custom helpers:
+         *
+         * ```js
+         * const element = await this.helpers['Puppeteer']._locateElement({name: 'password'});
+         * ```
+         *
+         * {{ react }}
+         */
+        _locateElement(): void;
         /**
          * Find a checkbox by providing human-readable text:
          * NOTE: Assumes the checkable element exists
@@ -6834,6 +6843,17 @@ declare namespace CodeceptJS {
          * @returns WebElement of being used Web helper
          */
         grabWebElements(locator: CodeceptJS.LocatorOrString): Promise<any>;
+        /**
+         * 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 locator - element located by CSS|XPath|strict locator.
+         * @returns WebElement of being used Web helper
+         */
+        grabWebElement(locator: CodeceptJS.LocatorOrString): Promise<any>;
         /**
          * Switch focus to a particular tab by its number. It waits tabs loading and then switch tab
          *
@@ -8289,6 +8309,22 @@ declare namespace CodeceptJS {
          */
         flushWebSocketMessages(): void;
     }
+    /**
+     * Find elements using Puppeteer's native element discovery methods
+     * Note: Unlike Playwright, Puppeteer's Locator API doesn't have .all() method for multiple elements
+     * @param matcher - Puppeteer context to search within
+     * @param locator - Locator specification
+     * @returns Array of ElementHandle objects
+     */
+    function findElements(matcher: any, locator: any | string): Promise<any[]>;
+    /**
+     * Find a single element using Puppeteer's native element discovery methods
+     * Note: Puppeteer Locator API doesn't have .first() method like Playwright
+     * @param matcher - Puppeteer context to search within
+     * @param locator - Locator specification
+     * @returns Single ElementHandle object
+     */
+    function findElement(matcher: any, locator: any | string): Promise<object>;
     /**
      * ## Configuration
      * @property [endpoint] - API base URL
@@ -8303,7 +8339,6 @@ declare namespace CodeceptJS {
      */
     // @ts-ignore
     // @ts-ignore
-    // @ts-ignore
     type RESTConfig = {
         endpoint?: string;
         prettyPrintJson?: boolean;
@@ -8429,6 +8464,16 @@ declare namespace CodeceptJS {
          * @returns response
          */
         sendGetRequest(url: any, headers?: any): Promise<any>;
+        /**
+         * Send HEAD request to REST API
+         *
+         * ```js
+         * I.sendHeadRequest('/api/users.json');
+         * ```
+         * @param [headers = {}] - the headers object to be sent. By default, it is sent as an empty object
+         * @returns response
+         */
+        sendHeadRequest(url: any, headers?: any): Promise<any>;
         /**
          * Sends POST request to API.
          *
@@ -9511,7 +9556,6 @@ declare namespace CodeceptJS {
      */
     // @ts-ignore
     // @ts-ignore
-    // @ts-ignore
     type WebDriverConfig = {
         url: string;
         browser: string;
@@ -9982,6 +10026,17 @@ declare namespace CodeceptJS {
          * @returns WebElement of being used Web helper
          */
         grabWebElements(locator: CodeceptJS.LocatorOrString): Promise<any>;
+        /**
+         * 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 locator - element located by CSS|XPath|strict locator.
+         * @returns WebElement of being used Web helper
+         */
+        grabWebElement(locator: CodeceptJS.LocatorOrString): Promise<any>;
         /**
          * Set [WebDriver timeouts](https://webdriver.io/docs/timeouts.html) in realtime.
          *
@@ -11526,6 +11581,13 @@ declare namespace CodeceptJS {
          * Loads tests by pattern or by config.tests
          */
         loadTests(pattern?: string): void;
+        /**
+         * Apply sharding to test files based on shard configuration
+         * @param testFiles - Array of test file paths
+         * @param shardConfig - Shard configuration in format "index/total" (e.g., "1/4")
+         * @returns - Filtered array of test files for this shard
+         */
+        _applySharding(testFiles: string[], shardConfig: string): string[];
         /**
          * Run a specific test or all loaded tests.
          */
@@ -11713,7 +11775,7 @@ declare namespace CodeceptJS {
      * - Logs errors and retries the callback until it either succeeds or the maximum number of attempts is reached.
      * - Restores the session state after each attempt, whether successful or not.
      * @example
-     * const { hopeThat } = require('codeceptjs/effects')
+     * const { retryTo } = require('codeceptjs/effects')
      * await retryTo((tries) => {
      *   if (tries < 3) {
      *     I.see('Non-existent element'); // Simulates a failure
@@ -12019,6 +12081,10 @@ declare namespace CodeceptJS {
          * Get a state of current queue and tasks
          */
         toString(): string;
+        /**
+         * Get current session ID
+         */
+        getCurrentSessionId(): string | null;
     }
     interface RecorderSession {
         running: boolean;