codeceptjs 4.0.0-rc.1 → 4.0.0-rc.11

package/docs/webapi/dontSeeCurrentPathEquals.mustache

@@ -0,0 +1,10 @@
+Checks that current URL path does NOT match the expected path.
+Query strings and URL fragments are ignored.
+
+```js
+I.dontSeeCurrentPathEquals('/form'); // fails for '/form', '/form?user=1', '/form#section'
+I.dontSeeCurrentPathEquals('/'); // fails for '/', '/?user=ok', '/#top'
+```
+
+@param {string} path value to check.
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/dontSeeElement.mustache

@@ -1,8 +1,12 @@
 Opposite to `seeElement`. Checks that element is not visible (or in DOM)
 
+The second parameter is a context (CSS or XPath locator) to narrow the search.
+
 ```js
 I.dontSeeElement('.modal'); // modal is not shown
+I.dontSeeElement('.modal', '#container');
 ```
 
 @param {CodeceptJS.LocatorOrString} locator located by CSS|XPath|Strict locator.
+@param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element located by CSS | XPath | strict locator.
 @returns {void} automatically synchronized promise through #recorder

package/docs/webapi/dontSeeInField.mustache

@@ -1,11 +1,16 @@
 Checks that value of input field or textarea doesn't equal to given value
 Opposite to `seeInField`.
 
+The third parameter is an optional context (CSS or XPath locator) to narrow the search.
+
 ```js
 I.dontSeeInField('email', 'user@user.com'); // field by name
 I.dontSeeInField({ css: 'form input.email' }, 'user@user.com'); // field by CSS
+// within a context
+I.dontSeeInField('Name', 'old_value', '.form-container');
 ```
 
 @param {CodeceptJS.LocatorOrString} field located by label|name|CSS|XPath|strict locator.
 @param {CodeceptJS.StringOrSecret} value value to check.
+@param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element located by CSS | XPath | strict locator.
 @returns {void} automatically synchronized promise through #recorder

package/docs/webapi/fillField.mustache

@@ -1,6 +1,8 @@
 Fills a text field or textarea, after clearing its value, with the given string.
 Field is located by name, label, CSS, or XPath.
 
+The third parameter is an optional context (CSS or XPath locator) to narrow the search.
+
 ```js
 // by label
 I.fillField('Email', 'hello@world.com');
@@ -10,7 +12,10 @@ I.fillField('password', secret('123456'));
 I.fillField('form#login input[name=username]', 'John');
 // or by strict locator
 I.fillField({css: 'form#login input[name=username]'}, 'John');
+// within a context
+I.fillField('Name', 'John', '#section2');
 ```
 @param {CodeceptJS.LocatorOrString} field located by label|name|CSS|XPath|strict locator.
 @param {CodeceptJS.StringOrSecret} value text value to fill.
+@param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element located by CSS | XPath | strict locator.
 @returns {void} automatically synchronized promise through #recorder

package/docs/webapi/moveCursorTo.mustache

@@ -1,12 +1,16 @@
 Moves cursor to element matched by locator.
 Extra shift can be set with offsetX and offsetY options.
 
+An optional `context` (as a second parameter) can be specified to narrow the search to an element within a parent.
+When the second argument is a non-number (string or locator object), it is treated as context.
+
 ```js
 I.moveCursorTo('.tooltip');
 I.moveCursorTo('#submit', 5,5);
+I.moveCursorTo('#submit', '.container');
 ```
 
 @param {CodeceptJS.LocatorOrString} locator located by CSS|XPath|strict locator.
-@param {number} [offsetX=0] (optional, `0` by default) X-axis offset.
+@param {number|CodeceptJS.LocatorOrString} [offsetX=0] (optional, `0` by default) X-axis offset or context locator.
 @param {number} [offsetY=0] (optional, `0` by default) Y-axis offset.
 @returns {void} automatically synchronized promise through #recorder

package/docs/webapi/seeCurrentPathEquals.mustache

@@ -0,0 +1,10 @@
+Checks that current URL path matches the expected path.
+Query strings and URL fragments are ignored.
+
+```js
+I.seeCurrentPathEquals('/info'); // passes for '/info', '/info?user=1', '/info#section'
+I.seeCurrentPathEquals('/'); // passes for '/', '/?user=ok', '/#top'
+```
+
+@param {string} path value to check.
+@returns {void} automatically synchronized promise through #recorder

package/docs/webapi/seeElement.mustache

@@ -1,8 +1,12 @@
 Checks that a given Element is visible
 Element is located by CSS or XPath.
 
+The second parameter is a context (CSS or XPath locator) to narrow the search.
+
 ```js
 I.seeElement('#modal');
+I.seeElement('#modal', '#container');
 ```
 @param {CodeceptJS.LocatorOrString} locator located by CSS|XPath|strict locator.
+@param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element located by CSS | XPath | strict locator.
 @returns {void} automatically synchronized promise through #recorder

package/docs/webapi/seeInField.mustache

@@ -1,12 +1,17 @@
 Checks that the given input field or textarea equals to given value.
 For fuzzy locators, fields are matched by label text, the "name" attribute, CSS, and XPath.
 
+The third parameter is an optional context (CSS or XPath locator) to narrow the search.
+
 ```js
 I.seeInField('Username', 'davert');
 I.seeInField({css: 'form textarea'},'Type your comment here');
 I.seeInField('form input[type=hidden]','hidden_value');
 I.seeInField('#searchform input','Search');
+// within a context
+I.seeInField('Name', 'John', '.form-container');
 ```
 @param {CodeceptJS.LocatorOrString} field located by label|name|CSS|XPath|strict locator.
 @param {CodeceptJS.StringOrSecret} value value to check.
+@param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element located by CSS | XPath | strict locator.
 @returns {void} automatically synchronized promise through #recorder

package/docs/webapi/selectOption.mustache

@@ -2,6 +2,8 @@ Selects an option in a drop-down select.
 Field is searched by label | name | CSS | XPath.
 Option is selected by visible text or by value.
 
+The third parameter is an optional context (CSS or XPath locator) to narrow the search.
+
 ```js
 I.selectOption('Choose Plan', 'Monthly'); // select by label
 I.selectOption('subscription', 'Monthly'); // match option by text
@@ -9,6 +11,8 @@ I.selectOption('subscription', '0'); // or by value
 I.selectOption('//form/select[@name=account]','Premium');
 I.selectOption('form select[name=account]', 'Premium');
 I.selectOption({css: 'form select[name=account]'}, 'Premium');
+// within a context
+I.selectOption('age', '21-60', '#section2');
 ```
 
 Provide an array for the second argument to select multiple options.
@@ -18,4 +22,5 @@ I.selectOption('Which OS do you use?', ['Android', 'iOS']);
 ```
 @param {LocatorOrString} select field located by label|name|CSS|XPath|strict locator.
 @param {string|Array<*>} option visible text or value of option.
+@param {?CodeceptJS.LocatorOrString} [context=null] (optional, `null` by default) element located by CSS | XPath | strict locator.
 @returns {void} automatically synchronized promise through #recorder

package/docs/webapi/uncheckOption.mustache

@@ -1,7 +1,7 @@
 Unselects a checkbox or radio button.
 Element is located by label or name or CSS or XPath.
 
-The second parameter is a context (CSS or XPath locator) to narrow the search.
+The second parameter is an optional context (CSS or XPath locator) to narrow the search.
 
 ```js
 I.uncheckOption('#agree');

package/lib/codecept.js

@@ -120,23 +120,26 @@ class Codecept {
    * Executes hooks.
    */
   async runHooks() {
-    // default hooks - dynamic imports for ESM
-    const listenerModules = [
-      './listener/store.js',
-      './listener/steps.js',
-      './listener/config.js',
-      './listener/result.js',
-      './listener/helpers.js',
-      './listener/globalTimeout.js',
-      './listener/globalRetry.js',
-      './listener/retryEnhancer.js',
-      './listener/exit.js',
-      './listener/emptyRun.js',
-    ]
-
-    for (const modulePath of listenerModules) {
-      const module = await import(modulePath)
-      runHook(module.default || module)
+    // For workers parent process we only need plugins/hooks.
+    // Core listeners are executed inside worker threads.
+    if (!this.opts?.skipDefaultListeners) {
+      const listenerModules = [
+        './listener/store.js',
+        './listener/steps.js',
+        './listener/config.js',
+        './listener/result.js',
+        './listener/helpers.js',
+        './listener/globalTimeout.js',
+        './listener/globalRetry.js',
+        './listener/retryEnhancer.js',
+        './listener/exit.js',
+        './listener/emptyRun.js',
+      ]
+
+      for (const modulePath of listenerModules) {
+        const module = await import(modulePath)
+        runHook(module.default || module)
+      }
     }
 
     // custom hooks (previous iteration of plugins)

package/lib/command/init.js

@@ -20,9 +20,6 @@ const defaultConfig = {
   helpers: {},
   include: {},
   plugins: {
-    htmlReporter: {
-      enabled: true,
-    },
   },
 }
 

package/lib/command/run-workers.js

@@ -41,6 +41,7 @@ export default async function (workerCount, selectedRuns, options) {
   output.print(`CodeceptJS v${Codecept.version()} ${output.standWithUkraine()}`)
   output.print(`Running tests in ${output.styles.bold(numberOfWorkers)} workers...`)
   store.hasWorkers = true
+  process.env.RUNS_WITH_WORKERS = 'true'
 
   const workers = new Workers(numberOfWorkers, config)
   workers.overrideConfig(overrideConfigs)

package/lib/container.js

@@ -657,13 +657,28 @@ async function createPlugins(config, options = {}) {
   const enabledPluginsByOptions = (options.plugins || '').split(',')
   for (const pluginName in config) {
     if (!config[pluginName]) config[pluginName] = {}
-    if (!config[pluginName].enabled && enabledPluginsByOptions.indexOf(pluginName) < 0) {
+    const pluginConfig = config[pluginName]
+    if (!pluginConfig.enabled && enabledPluginsByOptions.indexOf(pluginName) < 0) {
       continue // plugin is disabled
     }
+
+    // Generic workers gate:
+    // - runInWorker / runInWorkers controls plugin execution inside worker threads.
+    // - runInParent / runInMain can disable plugin in workers parent process.
+    const runInWorker = pluginConfig.runInWorker ?? pluginConfig.runInWorkers ?? (pluginName === 'testomatio' ? false : true)
+    const runInParent = pluginConfig.runInParent ?? pluginConfig.runInMain ?? true
+
+    if (options.child && !runInWorker) {
+      continue
+    }
+
+    if (!options.child && process.env.RUNS_WITH_WORKERS === 'true' && !runInParent) {
+      continue
+    }
     let module
     try {
-      if (config[pluginName].require) {
-        module = config[pluginName].require
+      if (pluginConfig.require) {
+        module = pluginConfig.require
         if (module.startsWith('.')) {
           // local
           module = path.resolve(global.codecept_dir, module) // custom plugin
@@ -673,7 +688,7 @@ async function createPlugins(config, options = {}) {
       }
 
       // Use async loading for all plugins (ESM and CJS)
-      plugins[pluginName] = await loadPluginAsync(module, config[pluginName])
+      plugins[pluginName] = await loadPluginAsync(module, pluginConfig)
       debug(`plugin ${pluginName} loaded via async import`)
     } catch (err) {
       throw new Error(`Could not load plugin ${pluginName} from module '${module}':\n${err.message}\n${err.stack}`)

package/lib/element/WebElement.js

@@ -1,4 +1,5 @@
 import assert from 'assert'
+import { simplifyHtmlElement } from '../html.js'
 
 /**
  * Unified WebElement class that wraps native element instances from different helpers
@@ -81,6 +82,10 @@ class WebElement {
   async getProperty(name) {
     switch (this.helperType) {
       case 'playwright':
+        // For Locator objects, use inputValue() for the 'value' property
+        if (name === 'value' && this.element.inputValue) {
+          return this.element.inputValue()
+        }
         return this.element.evaluate((el, propName) => el[propName], name)
       case 'webdriver':
         return this.element.getProperty(name)
@@ -236,10 +241,15 @@ class WebElement {
   async type(text, options = {}) {
     switch (this.helperType) {
       case 'playwright':
+        // Playwright Locator objects use fill() instead of type()
+        if (this.element.fill) {
+          return this.element.fill(text, options)
+        }
         return this.element.type(text, options)
       case 'webdriver':
         return this.element.setValue(text)
       case 'puppeteer':
+        await this.element.evaluate(el => { el.value = '' })
         return this.element.type(text, options)
       default:
         throw new Error(`Unsupported helper type: ${this.helperType}`)
@@ -256,7 +266,18 @@ class WebElement {
 
     switch (this.helperType) {
       case 'playwright':
-        childElement = await this.element.$(this._normalizeLocator(locator))
+        // Playwright Locator objects use locator() method
+        if (this.element.locator) {
+          const childLocator = this.element.locator(this._normalizeLocator(locator))
+          // Get the element handle from the locator
+          try {
+            childElement = await childLocator.elementHandle()
+          } catch (e) {
+            return null
+          }
+        } else {
+          childElement = await this.element.$(this._normalizeLocator(locator))
+        }
         break
       case 'webdriver':
         try {
@@ -285,7 +306,14 @@ class WebElement {
 
     switch (this.helperType) {
       case 'playwright':
-        childElements = await this.element.$$(this._normalizeLocator(locator))
+        // Playwright Locator objects use locator() method
+        if (this.element.locator) {
+          const childLocator = this.element.locator(this._normalizeLocator(locator))
+          // Get all element handles from the locator
+          childElements = await childLocator.elementHandles()
+        } else {
+          childElements = await this.element.$$(this._normalizeLocator(locator))
+        }
         break
       case 'webdriver':
         childElements = await this.element.$$(this._normalizeLocator(locator))
@@ -306,6 +334,57 @@ class WebElement {
    * @returns {string} Normalized CSS selector
    * @private
    */
+  async toAbsoluteXPath() {
+    const xpathFn = (el) => {
+      const parts = []
+      let current = el
+      while (current && current.nodeType === Node.ELEMENT_NODE) {
+        let index = 0
+        let sibling = current.previousSibling
+        while (sibling) {
+          if (sibling.nodeType === Node.ELEMENT_NODE && sibling.tagName === current.tagName) {
+            index++
+          }
+          sibling = sibling.previousSibling
+        }
+        const tagName = current.tagName.toLowerCase()
+        const pathIndex = index > 0 ? `[${index + 1}]` : ''
+        parts.unshift(`${tagName}${pathIndex}`)
+        current = current.parentElement
+      }
+      return '//' + parts.join('/')
+    }
+
+    switch (this.helperType) {
+      case 'playwright':
+        return this.element.evaluate(xpathFn)
+      case 'puppeteer':
+        return this.element.evaluate(xpathFn)
+      case 'webdriver':
+        return this.helper.browser.execute(xpathFn, this.element)
+      default:
+        throw new Error(`Unsupported helper type: ${this.helperType}`)
+    }
+  }
+
+  async toOuterHTML() {
+    switch (this.helperType) {
+      case 'playwright':
+        return this.element.evaluate(el => el.outerHTML)
+      case 'puppeteer':
+        return this.element.evaluate(el => el.outerHTML)
+      case 'webdriver':
+        return this.helper.browser.execute(el => el.outerHTML, this.element)
+      default:
+        throw new Error(`Unsupported helper type: ${this.helperType}`)
+    }
+  }
+
+  async toSimplifiedHTML(maxLength = 300) {
+    const outerHTML = await this.toOuterHTML()
+    return simplifyHtmlElement(outerHTML, maxLength)
+  }
+
   _normalizeLocator(locator) {
     if (typeof locator === 'string') {
       return locator

package/lib/els.js

@@ -6,10 +6,11 @@ import recordStep from './step/record.js'
 import FuncStep from './step/func.js'
 import { truth } from './assert/truth.js'
 import { isAsyncFunction, humanizeFunction } from './utils.js'
+import WebElement from './element/WebElement.js'
 
 function element(purpose, locator, fn) {
   let stepConfig
-  if (arguments[arguments.length - 1] instanceof StepConfig) {
+  if (StepConfig.isStepConfig(arguments[arguments.length - 1])) {
     stepConfig = arguments[arguments.length - 1]
   }
 
@@ -28,7 +29,8 @@ function element(purpose, locator, fn) {
       const els = await step.helper._locate(locator)
       output.debug(`Found ${els.length} elements, using first element`)
 
-      return fn(els[0])
+      const wrapped = new WebElement(els[0], step.helper)
+      return fn(wrapped)
     },
     stepConfig,
   )
@@ -52,7 +54,8 @@ function eachElement(purpose, locator, fn) {
     let i = 0
     for (const el of els) {
       try {
-        await fn(el, i)
+        const wrapped = new WebElement(el, step.helper)
+        await fn(wrapped, i)
       } catch (err) {
         output.error(`eachElement: failed operation on element #${i} ${el}`)
         errs.push(err)
@@ -74,7 +77,8 @@ function expectElement(locator, fn) {
     const els = await step.helper._locate(locator)
     output.debug(`Found ${els.length} elements, first will be used for assertion`)
 
-    const result = await fn(els[0])
+    const wrapped = new WebElement(els[0], step.helper)
+    const result = await fn(wrapped)
     const assertion = truth(`element (${locator})`, fn.toString())
     assertion.assert(result)
   })
@@ -92,7 +96,8 @@ function expectAnyElement(locator, fn) {
 
     let found = false
     for (const el of els) {
-      const result = await fn(el)
+      const wrapped = new WebElement(el, step.helper)
+      const result = await fn(wrapped)
       if (result) {
         found = true
         break
@@ -113,7 +118,8 @@ function expectAllElements(locator, fn) {
     let i = 1
     for (const el of els) {
       output.debug(`checking element #${i}: ${el}`)
-      const result = await fn(el)
+      const wrapped = new WebElement(el, step.helper)
+      const result = await fn(wrapped)
       const assertion = truth(`element #${i} of (${locator})`, humanizeFunction(fn))
       assertion.assert(result)
       i++

package/lib/helper/Appium.js

@@ -1543,8 +1543,8 @@ class Appium extends Webdriver {
   /**
    * {{> dontSeeElement }}
    */
-  async dontSeeElement(locator) {
-    if (this.isWeb) return super.dontSeeElement(locator)
+  async dontSeeElement(locator, context = null) {
+    if (this.isWeb) return super.dontSeeElement(locator, context)
 
     // For mobile native apps, use safe isDisplayed wrapper
     const parsedLocator = parseLocator.call(this, locator)
@@ -1589,9 +1589,9 @@ class Appium extends Webdriver {
    * {{> fillField }}
    *
    */
-  async fillField(field, value) {
+  async fillField(field, value, context = null) {
     value = value.toString()
-    if (this.isWeb) return super.fillField(field, value)
+    if (this.isWeb) return super.fillField(field, value, context)
     return super.fillField(parseLocator.call(this, field), value)
   }
 
@@ -1706,8 +1706,8 @@ class Appium extends Webdriver {
    * {{> seeElement }}
    *
    */
-  async seeElement(locator) {
-    if (this.isWeb) return super.seeElement(locator)
+  async seeElement(locator, context = null) {
+    if (this.isWeb) return super.seeElement(locator, context)
 
     // For mobile native apps, use safe isDisplayed wrapper
     const parsedLocator = parseLocator.call(this, locator)
@@ -1754,8 +1754,8 @@ class Appium extends Webdriver {
    *
    * Supported only for web testing
    */
-  async selectOption(select, option) {
-    if (this.isWeb) return super.selectOption(select, option)
+  async selectOption(select, option, context = null) {
+    if (this.isWeb) return super.selectOption(select, option, context)
     throw new Error("Should be used only in Web context. In native context use 'click' method instead")
   }