codeceptjs 3.7.3 → 3.7.5-beta.1

package/lib/helper/Puppeteer.js

@@ -38,6 +38,7 @@ const { highlightElement } = require('./scripts/highlightElement')
 const { blurElement } = require('./scripts/blurElement')
 const { dontSeeElementError, seeElementError, dontSeeElementInDOMError, seeElementInDOMError } = require('./errors/ElementAssertion')
 const { dontSeeTraffic, seeTraffic, grabRecordedNetworkTraffics, stopRecordingTraffic, flushNetworkTraffics } = require('./network/actions')
+const WebElement = require('../element/WebElement')
 
 let puppeteer
 let perfTiming
@@ -633,9 +634,11 @@ class Puppeteer extends Helper {
       return
     }
 
-    const els = await this._locate(locator)
-    assertElementExists(els, locator)
-    this.context = els[0]
+    const el = await this._locateElement(locator)
+    if (!el) {
+      throw new ElementNotFound(locator, 'Element for within context')
+    }
+    this.context = el
 
     this.withinLocator = new Locator(locator)
   }
@@ -729,11 +732,13 @@ class Puppeteer extends Helper {
    * {{ react }}
    */
   async moveCursorTo(locator, offsetX = 0, offsetY = 0) {
-    const els = await this._locate(locator)
-    assertElementExists(els, locator)
+    const el = await this._locateElement(locator)
+    if (!el) {
+      throw new ElementNotFound(locator, 'Element to move cursor to')
+    }
 
     // Use manual mouse.move instead of .hover() so the offset can be added to the coordinates
-    const { x, y } = await getClickablePoint(els[0])
+    const { x, y } = await getClickablePoint(el)
     await this.page.mouse.move(x + offsetX, y + offsetY)
     return this._waitForAction()
   }
@@ -743,9 +748,10 @@ class Puppeteer extends Helper {
    *
    */
   async focus(locator) {
-    const els = await this._locate(locator)
-    assertElementExists(els, locator, 'Element to focus')
-    const el = els[0]
+    const el = await this._locateElement(locator)
+    if (!el) {
+      throw new ElementNotFound(locator, 'Element to focus')
+    }
 
     await el.click()
     await el.focus()
@@ -757,10 +763,12 @@ class Puppeteer extends Helper {
    *
    */
   async blur(locator) {
-    const els = await this._locate(locator)
-    assertElementExists(els, locator, 'Element to blur')
+    const el = await this._locateElement(locator)
+    if (!el) {
+      throw new ElementNotFound(locator, 'Element to blur')
+    }
 
-    await blurElement(els[0], this.page)
+    await blurElement(el, this.page)
     return this._waitForAction()
   }
 
@@ -809,11 +817,12 @@ class Puppeteer extends Helper {
     }
 
     if (locator) {
-      const els = await this._locate(locator)
-      assertElementExists(els, locator, 'Element')
-      const el = els[0]
+      const el = await this._locateElement(locator)
+      if (!el) {
+        throw new ElementNotFound(locator, 'Element to scroll into view')
+      }
       await el.evaluate(el => el.scrollIntoView())
-      const elementCoordinates = await getClickablePoint(els[0])
+      const elementCoordinates = await getClickablePoint(el)
       await this.executeScript((x, y) => window.scrollBy(x, y), elementCoordinates.x + offsetX, elementCoordinates.y + offsetY)
     } else {
       await this.executeScript((x, y) => window.scrollTo(x, y), offsetX, offsetY)
@@ -881,6 +890,21 @@ class Puppeteer extends Helper {
     return findElements.call(this, context, locator)
   }
 
+  /**
+   * 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 }}
+   */
+  async _locateElement(locator) {
+    const context = await this.context
+    return findElement.call(this, context, locator)
+  }
+
   /**
    * Find a checkbox by providing human-readable text:
    * NOTE: Assumes the checkable element exists
@@ -892,7 +916,9 @@ class Puppeteer extends Helper {
   async _locateCheckable(locator, providedContext = null) {
     const context = providedContext || (await this._getContext())
     const els = await findCheckable.call(this, locator, context)
-    assertElementExists(els[0], locator, 'Checkbox or radio')
+    if (!els || els.length === 0) {
+      throw new ElementNotFound(locator, 'Checkbox or radio')
+    }
     return els[0]
   }
 
@@ -924,7 +950,20 @@ class Puppeteer extends Helper {
    *
    */
   async grabWebElements(locator) {
-    return this._locate(locator)
+    const elements = await this._locate(locator)
+    return elements.map(element => new WebElement(element, this))
+  }
+
+  /**
+   * {{> grabWebElement }}
+   *
+   */
+  async grabWebElement(locator) {
+    const elements = await this._locate(locator)
+    if (elements.length === 0) {
+      throw new ElementNotFound(locator, 'Element')
+    }
+    return new WebElement(elements[0], this)
   }
 
   /**
@@ -2110,10 +2149,12 @@ class Puppeteer extends Helper {
    * {{> waitForClickable }}
    */
   async waitForClickable(locator, waitTimeout) {
-    const els = await this._locate(locator)
-    assertElementExists(els, locator)
+    const el = await this._locateElement(locator)
+    if (!el) {
+      throw new ElementNotFound(locator, 'Element to wait for clickable')
+    }
 
-    return this.waitForFunction(isElementClickable, [els[0]], waitTimeout).catch(async e => {
+    return this.waitForFunction(isElementClickable, [el], waitTimeout).catch(async e => {
       if (/Waiting failed/i.test(e.message) || /failed: timeout/i.test(e.message)) {
         throw new Error(`element ${new Locator(locator).toString()} still not clickable after ${waitTimeout || this.options.waitForTimeout / 1000} sec`)
       } else {
@@ -2687,9 +2728,18 @@ class Puppeteer extends Helper {
 
 module.exports = Puppeteer
 
+/**
+ * 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 {Object} matcher - Puppeteer context to search within
+ * @param {Object|string} locator - Locator specification
+ * @returns {Promise<Array>} Array of ElementHandle objects
+ */
 async function findElements(matcher, locator) {
   if (locator.react) return findReactElements.call(this, locator)
   locator = new Locator(locator, 'css')
+
+  // Use proven legacy approach - Puppeteer Locator API doesn't have .all() method
   if (!locator.isXPath()) return matcher.$$(locator.simplify())
   // puppeteer version < 19.4.0 is no longer supported. This one is backward support.
   if (puppeteer.default?.defaultBrowserRevision) {
@@ -2698,6 +2748,31 @@ async function findElements(matcher, locator) {
   return matcher.$x(locator.value)
 }
 
+/**
+ * Find a single element using Puppeteer's native element discovery methods
+ * Note: Puppeteer Locator API doesn't have .first() method like Playwright
+ * @param {Object} matcher - Puppeteer context to search within
+ * @param {Object|string} locator - Locator specification
+ * @returns {Promise<Object>} Single ElementHandle object
+ */
+async function findElement(matcher, locator) {
+  if (locator.react) return findReactElements.call(this, locator)
+  locator = new Locator(locator, 'css')
+
+  // Use proven legacy approach - Puppeteer Locator API doesn't have .first() method
+  if (!locator.isXPath()) {
+    const elements = await matcher.$$(locator.simplify())
+    return elements[0]
+  }
+  // puppeteer version < 19.4.0 is no longer supported. This one is backward support.
+  if (puppeteer.default?.defaultBrowserRevision) {
+    const elements = await matcher.$$(`xpath/${locator.value}`)
+    return elements[0]
+  }
+  const elements = await matcher.$x(locator.value)
+  return elements[0]
+}
+
 async function proceedClick(locator, context = null, options = {}) {
   let matcher = await this.context
   if (context) {
@@ -2843,15 +2918,19 @@ async function findFields(locator) {
 }
 
 async function proceedDragAndDrop(sourceLocator, destinationLocator) {
-  const src = await this._locate(sourceLocator)
-  assertElementExists(src, sourceLocator, 'Source Element')
+  const src = await this._locateElement(sourceLocator)
+  if (!src) {
+    throw new ElementNotFound(sourceLocator, 'Source Element')
+  }
 
-  const dst = await this._locate(destinationLocator)
-  assertElementExists(dst, destinationLocator, 'Destination Element')
+  const dst = await this._locateElement(destinationLocator)
+  if (!dst) {
+    throw new ElementNotFound(destinationLocator, 'Destination Element')
+  }
 
-  // Note: Using public api .getClickablePoint becaues the .BoundingBox does not take into account iframe offsets
-  const dragSource = await getClickablePoint(src[0])
-  const dragDestination = await getClickablePoint(dst[0])
+  // Note: Using public api .getClickablePoint because the .BoundingBox does not take into account iframe offsets
+  const dragSource = await getClickablePoint(src)
+  const dragDestination = await getClickablePoint(dst)
 
   // Drag start point
   await this.page.mouse.move(dragSource.x, dragSource.y, { steps: 5 })

package/lib/helper/WebDriver.js

@@ -21,6 +21,7 @@ const { focusElement } = require('./scripts/focusElement')
 const { blurElement } = require('./scripts/blurElement')
 const { dontSeeElementError, seeElementError, seeElementInDOMError, dontSeeElementInDOMError } = require('./errors/ElementAssertion')
 const { dontSeeTraffic, seeTraffic, grabRecordedNetworkTraffics, stopRecordingTraffic, flushNetworkTraffics } = require('./network/actions')
+const WebElement = require('../element/WebElement')
 
 const SHADOW = 'shadow'
 const webRoot = 'body'
@@ -936,7 +937,20 @@ class WebDriver extends Helper {
    *
    */
   async grabWebElements(locator) {
-    return this._locate(locator)
+    const elements = await this._locate(locator)
+    return elements.map(element => new WebElement(element, this))
+  }
+
+  /**
+   * {{> grabWebElement }}
+   *
+   */
+  async grabWebElement(locator) {
+    const elements = await this._locate(locator)
+    if (elements.length === 0) {
+      throw new ElementNotFound(locator, 'Element')
+    }
+    return new WebElement(elements[0], this)
   }
 
   /**
@@ -981,7 +995,7 @@ class WebDriver extends Helper {
    * {{ react }}
    */
   async click(locator, context = null) {
-    const clickMethod = this.browser.isMobile && !this.browser.isW3C ? 'touchClick' : 'elementClick'
+  const clickMethod = this.browser.isMobile && this.browser.capabilities.platformName !== 'android' ? 'touchClick' : 'elementClick'
     const locateFn = prepareLocateFn.call(this, context)
 
     const res = await findClickable.call(this, locator, locateFn)
@@ -1200,7 +1214,7 @@ class WebDriver extends Helper {
    * {{> checkOption }}
    */
   async checkOption(field, context = null) {
-    const clickMethod = this.browser.isMobile && !this.browser.isW3C ? 'touchClick' : 'elementClick'
+  const clickMethod = this.browser.isMobile && this.browser.capabilities.platformName !== 'android' ? 'touchClick' : 'elementClick'
     const locateFn = prepareLocateFn.call(this, context)
 
     const res = await findCheckable.call(this, field, locateFn)
@@ -1220,7 +1234,7 @@ class WebDriver extends Helper {
    * {{> uncheckOption }}
    */
   async uncheckOption(field, context = null) {
-    const clickMethod = this.browser.isMobile && !this.browser.isW3C ? 'touchClick' : 'elementClick'
+  const clickMethod = this.browser.isMobile && this.browser.capabilities.platformName !== 'android' ? 'touchClick' : 'elementClick'
     const locateFn = prepareLocateFn.call(this, context)
 
     const res = await findCheckable.call(this, field, locateFn)

package/lib/listener/retryEnhancer.js

@@ -0,0 +1,85 @@
+const event = require('../event')
+const { enhanceMochaTest } = require('../mocha/test')
+
+/**
+ * Enhance retried tests by copying CodeceptJS-specific properties from the original test
+ * This fixes the issue where Mocha's shallow clone during retries loses CodeceptJS properties
+ */
+module.exports = function () {
+  event.dispatcher.on(event.test.before, test => {
+    // Check if this test is a retry (has a reference to the original test)
+    const originalTest = test.retriedTest && test.retriedTest()
+
+    if (originalTest) {
+      // This is a retried test - copy CodeceptJS-specific properties from the original
+      copyCodeceptJSProperties(originalTest, test)
+
+      // Ensure the test is enhanced with CodeceptJS functionality
+      enhanceMochaTest(test)
+    }
+  })
+}
+
+/**
+ * Copy CodeceptJS-specific properties from the original test to the retried test
+ * @param {CodeceptJS.Test} originalTest - The original test object
+ * @param {CodeceptJS.Test} retriedTest - The retried test object
+ */
+function copyCodeceptJSProperties(originalTest, retriedTest) {
+  // Copy CodeceptJS-specific properties
+  if (originalTest.opts !== undefined) {
+    retriedTest.opts = originalTest.opts ? { ...originalTest.opts } : {}
+  }
+
+  if (originalTest.tags !== undefined) {
+    retriedTest.tags = originalTest.tags ? [...originalTest.tags] : []
+  }
+
+  if (originalTest.notes !== undefined) {
+    retriedTest.notes = originalTest.notes ? [...originalTest.notes] : []
+  }
+
+  if (originalTest.meta !== undefined) {
+    retriedTest.meta = originalTest.meta ? { ...originalTest.meta } : {}
+  }
+
+  if (originalTest.artifacts !== undefined) {
+    retriedTest.artifacts = originalTest.artifacts ? [...originalTest.artifacts] : []
+  }
+
+  if (originalTest.steps !== undefined) {
+    retriedTest.steps = originalTest.steps ? [...originalTest.steps] : []
+  }
+
+  if (originalTest.config !== undefined) {
+    retriedTest.config = originalTest.config ? { ...originalTest.config } : {}
+  }
+
+  if (originalTest.inject !== undefined) {
+    retriedTest.inject = originalTest.inject ? { ...originalTest.inject } : {}
+  }
+
+  // Copy methods that might be missing
+  if (originalTest.addNote && !retriedTest.addNote) {
+    retriedTest.addNote = function (type, note) {
+      this.notes = this.notes || []
+      this.notes.push({ type, text: note })
+    }
+  }
+
+  if (originalTest.applyOptions && !retriedTest.applyOptions) {
+    retriedTest.applyOptions = originalTest.applyOptions.bind(retriedTest)
+  }
+
+  if (originalTest.simplify && !retriedTest.simplify) {
+    retriedTest.simplify = originalTest.simplify.bind(retriedTest)
+  }
+
+  // Preserve the uid if it exists
+  if (originalTest.uid !== undefined) {
+    retriedTest.uid = originalTest.uid
+  }
+
+  // Mark as enhanced
+  retriedTest.codeceptjs = true
+}

package/lib/listener/steps.js

@@ -3,10 +3,14 @@ const event = require('../event')
 const store = require('../store')
 const output = require('../output')
 const { BeforeHook, AfterHook, BeforeSuiteHook, AfterSuiteHook } = require('../mocha/hooks')
+const recorder = require('../recorder')
 
 let currentTest
 let currentHook
 
+// Session names that should not contribute steps to the main test trace
+const EXCLUDED_SESSIONS = ['tryTo', 'hopeThat']
+
 /**
  * Register steps inside tests
  */
@@ -75,6 +79,14 @@ module.exports = function () {
       return currentHook.steps.push(step)
     }
     if (!currentTest || !currentTest.steps) return
+    
+    // Check if we're in a session that should be excluded from main test steps
+    const currentSessionId = recorder.getCurrentSessionId()
+    if (currentSessionId && EXCLUDED_SESSIONS.includes(currentSessionId)) {
+      // Skip adding this step to the main test steps
+      return
+    }
+    
     currentTest.steps.push(step)
   })
 

package/lib/mocha/asyncWrapper.js

@@ -121,9 +121,19 @@ module.exports.injected = function (fn, suite, hookName) {
     const errHandler = err => {
       recorder.session.start('teardown')
       recorder.cleanAsyncErr()
-      if (hookName == 'before' || hookName == 'beforeSuite') suiteTestFailedHookError(suite, err, hookName)
-      if (hookName === 'after') suite.eachTest(test => event.emit(event.test.after, test))
-      if (hookName === 'afterSuite') event.emit(event.suite.after, suite)
+      if (['before', 'beforeSuite'].includes(hookName)) {
+        suiteTestFailedHookError(suite, err, hookName)
+      }
+      if (hookName === 'after') {
+        suiteTestFailedHookError(suite, err, hookName)
+        suite.eachTest(test => {
+          event.emit(event.test.after, test)
+        })
+      }
+      if (hookName === 'afterSuite') {
+        suiteTestFailedHookError(suite, err, hookName)
+        event.emit(event.suite.after, suite)
+      }
       recorder.add(() => doneFn(err))
     }
 

package/lib/mocha/cli.js

@@ -200,7 +200,7 @@ class Cli extends Base {
 
         // explicitly show file with error
         if (test.file) {
-          log += `\n${output.styles.basic(figures.circle)} ${output.styles.section('File:')} ${output.styles.basic(test.file)}\n`
+          log += `\n${output.styles.basic(figures.circle)} ${output.styles.section('File:')} file://${test.file}\n`
         }
 
         const steps = test.steps || (test.ctx && test.ctx.test.steps)

package/lib/mocha/gherkin.js

@@ -107,7 +107,7 @@ module.exports = (text, file) => {
       )
       continue
     }
-    if (child.scenario && (currentLanguage ? currentLanguage.contexts.ScenarioOutline.includes(child.scenario.keyword) : child.scenario.keyword === 'Scenario Outline')) {
+    if (child.scenario && (currentLanguage ? currentLanguage.contexts.ScenarioOutline === child.scenario.keyword : child.scenario.keyword === 'Scenario Outline')) {
       for (const examples of child.scenario.examples) {
         const fields = examples.tableHeader.cells.map(c => c.value)
         for (const example of examples.tableBody) {

package/lib/mocha/test.js

@@ -77,6 +77,12 @@ function deserializeTest(test) {
   test.parent = Object.assign(new Suite(test.parent?.title || 'Suite'), test.parent)
   enhanceMochaSuite(test.parent)
   if (test.steps) test.steps = test.steps.map(step => Object.assign(new Step(step.title), step))
+
+  // Restore the custom fullTitle function to maintain consistency with original test
+  if (test.parent) {
+    test.fullTitle = () => `${test.parent.title}: ${test.title}`
+  }
+
   return test
 }
 
@@ -135,9 +141,19 @@ function cloneTest(test) {
   return deserializeTest(serializeTest(test))
 }
 
-function testToFileName(test, suffix = '') {
+/**
+ * Get a filename from the test object
+ * @param {CodeceptJS.Test} test
+ * @param {Object}  options
+ * @param {string}  options.suffix Add a suffix to the filename
+ * @param {boolean} options.unique Add a unique suffix to the file
+ *
+ * @returns {string} the filename
+ */
+function testToFileName(test, { suffix = '', unique = false } = {}) {
   let fileName = test.title
 
+  if (unique) fileName = `${fileName}_${test?.uid || Math.floor(new Date().getTime() / 1000)}`
   if (suffix) fileName = `${fileName}_${suffix}`
   // remove tags with empty string (disable for now)
   // fileName = fileName.replace(/\@\w+/g, '')
@@ -151,6 +167,7 @@ function testToFileName(test, suffix = '') {
   //   fileName = `${clearString(test.parent.title)}_${fileName}`
   // }
   fileName = clearString(fileName).slice(0, 100)
+
   return fileName
 }
 

package/lib/mocha/ui.js

@@ -103,6 +103,19 @@ module.exports = function (suite) {
       return new FeatureConfig(suite)
     }
 
+    /**
+     * Exclusive test suite - runs only this feature.
+     * @global
+     * @kind constant
+     * @type {CodeceptJS.IFeature}
+     */
+    context.Feature.only = function (title, opts) {
+      const reString = `^${escapeRe(`${title}:`)}`
+      mocha.grep(new RegExp(reString))
+      process.env.FEATURE_ONLY = true
+      return context.Feature(title, opts)
+    }
+
     /**
      * Pending test suite.
      * @global

package/lib/output.js

@@ -1,6 +1,6 @@
 const colors = require('chalk')
 const figures = require('figures')
-const { maskSensitiveData } = require('invisi-data')
+const { maskData, shouldMaskData, getMaskConfig } = require('./utils/mask_data')
 
 const styles = {
   error: colors.bgRed.white.bold,
@@ -59,7 +59,7 @@ module.exports = {
    * @param {string} msg
    */
   debug(msg) {
-    const _msg = isMaskedData() ? maskSensitiveData(msg) : msg
+    const _msg = shouldMaskData() ? maskData(msg, getMaskConfig()) : msg
     if (outputLevel >= 2) {
       print(' '.repeat(this.stepShift), styles.debug(`${figures.pointerSmall} ${_msg}`))
     }
@@ -70,7 +70,7 @@ module.exports = {
    * @param {string} msg
    */
   log(msg) {
-    const _msg = isMaskedData() ? maskSensitiveData(msg) : msg
+    const _msg = shouldMaskData() ? maskData(msg, getMaskConfig()) : msg
     if (outputLevel >= 3) {
       print(' '.repeat(this.stepShift), styles.log(truncate(`   ${_msg}`, this.spaceShift)))
     }
@@ -81,7 +81,8 @@ module.exports = {
    * @param {string} msg
    */
   error(msg) {
-    print(styles.error(msg))
+    const _msg = shouldMaskData() ? maskData(msg, getMaskConfig()) : msg
+    print(styles.error(_msg))
   },
 
   /**
@@ -89,7 +90,8 @@ module.exports = {
    * @param {string} msg
    */
   success(msg) {
-    print(styles.success(msg))
+    const _msg = shouldMaskData() ? maskData(msg, getMaskConfig()) : msg
+    print(styles.success(_msg))
   },
 
   /**
@@ -124,7 +126,7 @@ module.exports = {
       stepLine += colors.grey(step.comment.split('\n').join('\n' + ' '.repeat(4)))
     }
 
-    const _stepLine = isMaskedData() ? maskSensitiveData(stepLine) : stepLine
+    const _stepLine = shouldMaskData() ? maskData(stepLine, getMaskConfig()) : stepLine
     print(' '.repeat(this.stepShift), truncate(_stepLine, this.spaceShift))
   },
 
@@ -278,7 +280,3 @@ function truncate(msg, gap = 0) {
   }
   return msg
 }
-
-function isMaskedData() {
-  return global.maskSensitiveData === true || false
-}

package/lib/pause.js

@@ -175,7 +175,12 @@ async function parseInput(cmd) {
       output.print(output.styles.success('  OK  '), cmd)
     }
     if (cmd?.startsWith('I.grab')) {
-      output.print(output.styles.debug(val))
+      try {
+        output.print(output.styles.debug(JSON.stringify(val, null, 2)))
+      } catch (err) {
+        output.print(output.styles.error(' ERROR '), 'Failed to stringify result:', err.message)
+        output.print(output.styles.error(' RAW VALUE '), String(val))
+      }
     }
 
     history.push(cmd) // add command to history when successful

package/lib/plugin/commentStep.js

@@ -7,7 +7,7 @@ let currentCommentStep
 const defaultGlobalName = '__'
 
 /**
- * @deprecated
+ * This plugin is **deprecated**, use `Section` instead.
  *
  * Add descriptive nested steps for your tests:
  *