codeceptjs 4.0.2-beta.9 → 4.0.2

package/lib/effects.js

@@ -4,6 +4,7 @@ import store from './store.js'
 import event from './event.js'
 import container from './container.js'
 import MetaStep from './step/meta.js'
+import { empty } from './assert/empty.js'
 import { isAsyncFunction } from './utils.js'
 
 /**
@@ -111,6 +112,11 @@ class WithinStep extends MetaStep {
  *
  * @throws Will handle errors that occur during the callback execution. Errors are logged and attached as notes to the test.
  */
+let hopeThatFailures = []
+event.dispatcher.on(event.test.before, () => {
+  hopeThatFailures = []
+})
+
 async function hopeThat(callback) {
   if (store.dryRun) return
   const sessionName = 'hopeThat'
@@ -131,6 +137,7 @@ async function hopeThat(callback) {
         result = false
         const msg = err.inspect ? err.inspect() : err.toString()
         output.debug(`Unsuccessful assertion > ${msg}`)
+        hopeThatFailures.push(msg)
         event.dispatcher.once(event.test.finished, test => {
           if (!test.notes) test.notes = []
           test.notes.push({ type: 'conditionalError', text: msg })
@@ -153,6 +160,16 @@ async function hopeThat(callback) {
   )
 }
 
+/**
+ * Asserts that no `hopeThat` soft assertion has failed in the current test.
+ * Call once at the end of a scenario to fail it when any soft assertion failed.
+ */
+hopeThat.noErrors = function () {
+  const failures = hopeThatFailures
+  hopeThatFailures = []
+  empty('soft assertions').assert(failures)
+}
+
 /**
  * A CodeceptJS utility function to retry a step or callback multiple times with a specified polling interval.
  *

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,16 +241,149 @@ 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}`)
     }
   }
 
+  /**
+   * Run a function in the browser with this element as the first argument.
+   * @param {Function} fn Browser-side function. Receives the element, then extra args.
+   * @param {...any} args Additional arguments passed to the function
+   * @returns {Promise<any>} Value returned by fn
+   */
+  async evaluate(fn, ...args) {
+    switch (this.helperType) {
+      case 'playwright':
+      case 'puppeteer':
+        return this.element.evaluate(fn, ...args)
+      case 'webdriver':
+        return this.helper.executeScript(fn, this.element, ...args)
+      default:
+        throw new Error(`Unsupported helper type: ${this.helperType}`)
+    }
+  }
+
+  /**
+   * Focus the element.
+   * @returns {Promise<void>}
+   */
+  async focus() {
+    switch (this.helperType) {
+      case 'playwright':
+        return this.element.focus()
+      case 'puppeteer':
+        if (this.element.focus) return this.element.focus()
+        return this.element.evaluate(el => el.focus())
+      case 'webdriver':
+        return this.helper.executeScript(el => el.focus(), this.element)
+      default:
+        throw new Error(`Unsupported helper type: ${this.helperType}`)
+    }
+  }
+
+  /**
+   * Type characters via the page/browser keyboard into the focused element.
+   * Unlike `type()`, this does not call `.fill()`/`.setValue()`, so it works
+   * with contenteditable nodes, iframe bodies, and editor-owned hidden textareas.
+   * @param {string} text Text to send
+   * @param {Object} [options] Options (e.g. `{ delay }`)
+   * @returns {Promise<void>}
+   */
+  async typeText(text, options = {}) {
+    const s = String(text)
+    switch (this.helperType) {
+      case 'playwright':
+      case 'puppeteer':
+        return this.helper.page.keyboard.type(s, options)
+      case 'webdriver': {
+        const ENTER = '\uE007'
+        const parts = s.split('\n')
+        for (let i = 0; i < parts.length; i++) {
+          if (parts[i]) await this.helper.browser.keys(parts[i])
+          if (i < parts.length - 1) await this.helper.browser.keys(ENTER)
+        }
+        return
+      }
+      default:
+        throw new Error(`Unsupported helper type: ${this.helperType}`)
+    }
+  }
+
+  /**
+   * Select all content in the focused field and delete it via keyboard input.
+   * Sends Ctrl+A and Meta+A (so it works across platforms) followed by Backspace.
+   * @returns {Promise<void>}
+   */
+  async selectAllAndDelete() {
+    switch (this.helperType) {
+      case 'playwright':
+        await this.helper.page.keyboard.press('Control+a').catch(() => {})
+        await this.helper.page.keyboard.press('Meta+a').catch(() => {})
+        await this.helper.page.keyboard.press('Backspace')
+        return
+      case 'puppeteer':
+        for (const mod of ['Control', 'Meta']) {
+          try {
+            await this.helper.page.keyboard.down(mod)
+            await this.helper.page.keyboard.press('KeyA')
+            await this.helper.page.keyboard.up(mod)
+          } catch (e) {}
+        }
+        await this.helper.page.keyboard.press('Backspace')
+        return
+      case 'webdriver': {
+        const b = this.helper.browser
+        await b.keys(['Control', 'a']).catch(() => {})
+        await b.keys(['Meta', 'a']).catch(() => {})
+        await b.keys(['Backspace'])
+        return
+      }
+      default:
+        throw new Error(`Unsupported helper type: ${this.helperType}`)
+    }
+  }
+
+  /**
+   * Treat this element as an iframe; invoke `fn` with a WebElement wrapping
+   * the iframe body. For WebDriver this switches the browser into the frame
+   * for the duration of the callback and switches back on exit.
+   * @param {(body: WebElement) => Promise<any>} fn
+   * @returns {Promise<any>} Return value of fn
+   */
+  async inIframe(fn) {
+    switch (this.helperType) {
+      case 'playwright':
+      case 'puppeteer': {
+        const frame = await this.element.contentFrame()
+        const body = await frame.$('body')
+        return fn(new WebElement(body, this.helper))
+      }
+      case 'webdriver': {
+        const browser = this.helper.browser
+        await browser.switchFrame(this.element)
+        try {
+          const body = await browser.$('body')
+          return await fn(new WebElement(body, this.helper))
+        } finally {
+          await browser.switchFrame(null)
+        }
+      }
+      default:
+        throw new Error(`Unsupported helper type: ${this.helperType}`)
+    }
+  }
+
   /**
    * Find first child element matching the locator
    * @param {string|Object} locator Element locator
@@ -256,7 +394,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 +434,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 +462,94 @@ 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)
+  }
+
+  /**
+   * Plain-object snapshot of the element — text, simplified HTML, visibility,
+   * enabled state, and a curated set of attributes. Each underlying call is
+   * isolated so a single failure (e.g. detached element) doesn't poison the
+   * rest. Suitable for JSON.stringify, log output, MCP tool responses.
+   *
+   * @param {object}   [opts]
+   * @param {number}   [opts.maxHtmlLength=300]   passed through to toSimplifiedHTML
+   * @param {string[]} [opts.attrs]               attribute names to surface
+   * @returns {Promise<{text?: string, html?: string, visible?: boolean, enabled?: boolean, attrs?: object}>}
+   */
+  async describe({ maxHtmlLength = 300, attrs = ['id', 'class', 'name', 'role', 'type', 'href', 'value', 'aria-label', 'placeholder', 'data-testid'] } = {}) {
+    const out = {}
+    await Promise.all([
+      this.toSimplifiedHTML(maxHtmlLength).then(v => { if (v) out.html = v }, () => {}),
+      this.getText().then(v => { const t = v?.trim(); if (t) out.text = t }, () => {}),
+      this.isVisible().then(v => { out.visible = v }, () => {}),
+      this.isEnabled().then(v => { out.enabled = v }, () => {}),
+    ])
+    const collected = {}
+    await Promise.all(attrs.map(async name => {
+      try {
+        const v = await this.getAttribute(name)
+        if (v != null && v !== '') collected[name] = v
+      } catch {}
+    }))
+    if (Object.keys(collected).length) out.attrs = collected
+    return out
+  }
+
+  // Make accidental JSON.stringify (e.g. returning a WebElement from MCP run_code)
+  // produce a usable hint instead of `{}` — the underlying handle isn't
+  // serializable. Use .describe() for the real plain-object snapshot.
+  toJSON() {
+    return `[WebElement ${this.helperType} — call .describe() for a plain-object snapshot or .toSimplifiedHTML() for HTML]`
+  }
+
   _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/globals.js

@@ -8,27 +8,47 @@ import fsPath from 'path'
 import ActorFactory from './actor.js'
 import output from './output.js'
 import locator from './locator.js'
+import store from './store.js'
 
 /**
  * Initialize CodeceptJS core globals
  * Called from Codecept.initGlobals()
  */
 export async function initCodeceptGlobals(dir, config, container) {
+  store.initialize({
+    codeceptDir: dir,
+    outputDir: fsPath.resolve(dir, config.output),
+  })
+
+  store.noGlobals = config.noGlobals || false
+  store.maskSensitiveData = config.maskSensitiveData || false
+
+  // Keep globals for backward compat with external plugins
   global.codecept_dir = dir
   global.output_dir = fsPath.resolve(dir, config.output)
 
-  if (config.noGlobals) return;
-    // Set up actor global - will use container when available
-  global.actor = global.codecept_actor = (obj) => {
-    return ActorFactory(obj, global.container || container)
-  }
-  global.Actor = global.actor
-
-  // Use dynamic imports for modules to avoid circular dependencies
+  // pause/inject/share stay global even under noGlobals — they're the everyday
+  // debugging/wiring entry points and have no useful import alternative for
+  // page-object code that runs before the container is available.
   global.pause = async (...args) => {
     const pauseModule = await import('./pause.js')
     return (pauseModule.default || pauseModule)(...args)
   }
+  global.inject = () => container.support()
+  global.share = container.share
+
+  if (config.noGlobals) return;
+
+  output.print(output.styles.debug('Global functions are deprecated. Use `import { Helper, within, session } from "codeceptjs"` instead. Set `noGlobals: true` in config to disable globals.'));
+
+  const HelperModule = await import('@codeceptjs/helper')
+  global.Helper = global.codecept_helper = HelperModule.default || HelperModule
+
+  // Set up actor global - will use container when available
+  global.actor = global.codecept_actor = (obj) => {
+    return ActorFactory(obj, container)
+  }
+  global.Actor = global.actor
 
   global.within = async (...args) => {
     return (await import('./effects.js')).within(...args)
@@ -46,14 +66,9 @@ export async function initCodeceptGlobals(dir, config, container) {
     return locator.build(locatorQuery)
   }
 
-  global.inject = () => container.support()
-  global.share = container.share
-
   const secretModule = await import('./secret.js')
   global.secret = secretModule.secret || (secretModule.default && secretModule.default.secret)
 
-  global.codecept_debug = output.debug
-
   const codeceptjsModule = await import('./index.js') // load all objects
   global.codeceptjs = codeceptjsModule.default || codeceptjsModule
 
@@ -65,9 +80,6 @@ export async function initCodeceptGlobals(dir, config, container) {
   global.Then = stepDefinitions.Then
   global.DefineParameterType = stepDefinitions.defineParameterType
 
-  // debug mode
-  global.debugMode = false
-
   // mask sensitive data
   global.maskSensitiveData = config.maskSensitiveData || false
 
@@ -78,6 +90,8 @@ export async function initCodeceptGlobals(dir, config, container) {
  * Called from mocha/ui.js pre-require event
  */
 export function initMochaGlobals(context) {
+  if (store.noGlobals) return;
+
   // Mocha test framework globals
   global.BeforeAll = context.BeforeAll
   global.AfterAll = context.AfterAll
@@ -106,6 +120,8 @@ export function getGlobalNames() {
   return [
     'codecept_dir',
     'output_dir',
+    'Helper',
+    'codecept_helper',
     'actor',
     'codecept_actor',
     'Actor',
@@ -117,13 +133,11 @@ export function getGlobalNames() {
     'inject',
     'share',
     'secret',
-    'codecept_debug',
     'codeceptjs',
     'Given',
     'When',
     'Then',
     'DefineParameterType',
-    'debugMode',
     'maskSensitiveData',
     'BeforeAll',
     'AfterAll',
@@ -136,6 +150,5 @@ export function getGlobalNames() {
     'After',
     'Scenario',
     'xScenario',
-    'container'
   ]
 }

package/lib/heal.js

@@ -4,6 +4,7 @@ import colors from 'chalk'
 import recorder from './recorder.js'
 import output from './output.js'
 import event from './event.js'
+import container from './container.js'
 
 /**
  * @class
@@ -48,12 +49,14 @@ class Heal {
   }
 
   hasCorrespondingRecipes(step) {
-    return matchRecipes(this.recipes, this.contextName).filter(r => !r.steps || r.steps.includes(step.name)).length > 0
+    return matchRecipes(this.recipes, this.contextName).filter(r => !r.steps || r.steps.includes(step.title)).length > 0
   }
 
   async getCodeSuggestions(context) {
     const suggestions = []
+    const stepName = context.step?.title
     const recipes = matchRecipes(this.recipes, this.contextName)
+      .filter(r => !r.steps || !stepName || r.steps.includes(stepName))
 
     debug('Recipes', recipes)
 
@@ -69,7 +72,7 @@ class Heal {
       if (!prepareFn) continue
 
       if (context[property]) continue
-      context[property] = await prepareFn(global.inject())
+      context[property] = await prepareFn(container.support())
     }
 
     output.level(currentOutputLevel)
@@ -116,10 +119,10 @@ class Heal {
           })
 
           if (typeof codeSnippet === 'string') {
-            const I = global.container.support('I')
+            const I = container.support('I')
             await eval(codeSnippet)
           } else if (typeof codeSnippet === 'function') {
-            await codeSnippet(global.container.support())
+            await codeSnippet(container.support())
           }
 
           this.fixes.push({

package/lib/helper/ApiDataFactory.js

@@ -1,6 +1,7 @@
 import path from 'path'
 import Helper from '@codeceptjs/helper'
 import REST from './REST.js'
+import store from '../store.js'
 
 /**
  * Helper for managing remote data using REST API.
@@ -324,7 +325,7 @@ class ApiDataFactory extends Helper {
         await import.meta.resolve(modulePath)
       } catch (e) {
         // If not found, try relative to codecept_dir
-        modulePath = path.join(global.codecept_dir, modulePath)
+        modulePath = path.join(store.codeceptDir, modulePath)
       }
       // check if the new syntax `export default new Factory()` is used and loads the builder, otherwise loads the module that used old syntax `module.exports = new Factory()`.
       const module = await import(modulePath)

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")
   }
 

package/lib/helper/FileSystem.js

@@ -4,6 +4,7 @@ import fs from 'fs'
 
 import Helper from '@codeceptjs/helper'
 import { fileExists } from '../utils.js'
+import store from '../store.js'
 import { fileIncludes } from '../assert/include.js'
 import { fileEquals } from '../assert/equal.js'
 
@@ -33,7 +34,7 @@ import { fileEquals } from '../assert/equal.js'
 class FileSystem extends Helper {
   constructor() {
     super()
-    this.dir = global.codecept_dir
+    this.dir = store.codeceptDir
     this.file = ''
   }
 
@@ -52,7 +53,7 @@ class FileSystem extends Helper {
    * @param {string} openPath
    */
   amInPath(openPath) {
-    this.dir = path.join(global.codecept_dir, openPath)
+    this.dir = path.join(store.codeceptDir, openPath)
     try {
       this.debugSection('Dir', this.dir)
     } catch (e) {

package/lib/helper/GraphQLDataFactory.js

@@ -2,6 +2,7 @@ import path from 'path'
 
 import HelperModule from '@codeceptjs/helper'
 import GraphQL from './GraphQL.js'
+import store from '../store.js'
 
 /**
  * Helper for managing remote data using GraphQL queries.
@@ -251,7 +252,7 @@ class GraphQLDataFactory extends Helper {
       try {
         require.resolve(modulePath)
       } catch (e) {
-        modulePath = path.join(global.codecept_dir, modulePath)
+        modulePath = path.join(store.codeceptDir, modulePath)
       }
       const builder = require(modulePath)
       return builder.build(data)