codeceptjs 4.0.0-rc.9 → 4.0.0

package/lib/config.js

@@ -15,8 +15,9 @@ const defaultConfig = {
   hooks: [],
   gherkin: {},
   plugins: {
-    screenshotOnFail: {
-      enabled: true, // will be disabled by default in 2.0
+    screenshot: {
+      enabled: true,
+      on: 'fail',
     },
   },
   stepTimeout: 0,
@@ -32,9 +33,27 @@ const defaultConfig = {
   ],
 }
 
+// Array<{ fn: (cfg) => void, ran: boolean, error?: Error }>
 let hooks = []
 let config = {}
 
+// Apply a single hook against `cfg`, swallowing errors so one broken hook
+// can't take down the whole run. The failure is logged through the
+// framework's own output module (when available) so it shows up in test
+// reports; the hook is still marked ran so it doesn't get retried.
+function applyHook(hook, cfg) {
+  try {
+    hook.fn(cfg)
+  } catch (err) {
+    hook.error = err
+    const out = globalThis.codeceptjs?.output
+    if (out && typeof out.error === 'function') out.error(`config hook failed: ${err.message}`)
+    else console.error('config hook failed:', err)
+  } finally {
+    hook.ran = true
+  }
+}
+
 const configFileNames = ['codecept.config.js', 'codecept.conf.js', 'codecept.js', 'codecept.config.cjs', 'codecept.conf.cjs', 'codecept.config.ts', 'codecept.conf.ts']
 
 /**
@@ -49,7 +68,11 @@ class Config {
    */
   static create(newConfig) {
     config = deepMerge(deepClone(defaultConfig), newConfig)
-    hooks.forEach(f => f(config))
+    // Re-apply every hook against the freshly built config; hooks added later
+    // (e.g. from plugin boot) stay pending until runPendingHooks. Array
+    // iterators re-check length on each step, so hooks pushed during a hook
+    // execution are visited in this same pass.
+    for (const hook of hooks) applyHook(hook, config)
     return config
   }
 
@@ -121,7 +144,48 @@ class Config {
   }
 
   static addHook(fn) {
-    hooks.push(fn)
+    hooks.push({ fn, ran: false })
+  }
+
+  /**
+   * Run every hook that hasn't been applied to the current config yet.
+   * Hooks added after `Config.create()` (e.g. from plugin boot code) stay
+   * pending until this is called; once it runs, they're marked applied so
+   * subsequent calls are no-ops. Hooks added while pending hooks are running
+   * are picked up in the same pass (the array iterator re-checks length).
+   *
+   * Failures are logged through `output.error` and don't abort the loop —
+   * a broken hook can't poison the run, but its error is visible.
+   *
+   * @param {Object<string, *>} [cfg] target config (defaults to the live singleton)
+   * @return {boolean} true if any hook ran
+   */
+  static runPendingHooks(cfg = config) {
+    let ran = false
+    for (const hook of hooks) {
+      if (hook.ran) continue
+      applyHook(hook, cfg)
+      ran = true
+    }
+    return ran
+  }
+
+  /**
+   * Number of registered config hooks. Useful for snapshotting before a phase
+   * (e.g. plugin loading) and re-running only the hooks added during it.
+   * @return {number}
+   */
+  static hooksCount() {
+    return hooks.length
+  }
+
+  /**
+   * Run hooks in `[fromIndex, end)` against the given config object, mutating it.
+   * @param {number} fromIndex
+   * @param {Object<string, *>} cfg
+   */
+  static runHooksFrom(fromIndex, cfg) {
+    for (let i = fromIndex; i < hooks.length; i++) hooks[i](cfg)
   }
 
   /**
@@ -150,6 +214,15 @@ async function loadConfigFile(configFile) {
   const require = createRequire(import.meta.url)
   const extensionName = path.extname(configFile)
 
+  // Populate the in-process registry that packages like @codeceptjs/configure
+  // look up at config-import time (their proxies throw if `globalThis.codeceptjs`
+  // is missing). initCodeceptGlobals sets this too, but only later during
+  // bootstrap — config files are imported here first.
+  if (!globalThis.codeceptjs) {
+    const indexModule = await import('./index.js')
+    globalThis.codeceptjs = indexModule.default || indexModule
+  }
+
   // .conf.js config file
   if (extensionName === '.js' || extensionName === '.ts' || extensionName === '.cjs') {
     let configModule

package/lib/container.js

@@ -15,9 +15,15 @@ import store from './store.js'
 import Result from './result.js'
 import ai from './ai.js'
 import actorFactory from './actor.js'
+import Config from './config.js'
 
 let asyncHelperPromise
 
+let beforeCalledSet = new Set()
+
+export function getBeforeCalledSet() { return beforeCalledSet }
+export function resetBeforeCalledSet() { beforeCalledSet = new Set() }
+
 let container = {
   helpers: {},
   support: {},
@@ -116,6 +122,18 @@ class Container {
     // Wait for all async helpers to finish loading and populate the actor
     await asyncHelperPromise
 
+    // Plugins may have registered Config hooks during their boot. Run anything
+    // that hasn't been applied yet and re-feed the mutated helper config to the
+    // already-instantiated helpers.
+    if (Config.runPendingHooks(config)) {
+      for (const name of Object.keys(container.helpers)) {
+        const helper = container.helpers[name]
+        if (helper && typeof helper._setConfig === 'function' && config.helpers && config.helpers[name]) {
+          helper._setConfig(config.helpers[name])
+        }
+      }
+    }
+
     if (opts && opts.ai) ai.enable(config.ai) // enable AI Assistant
     if (config.gherkin) await loadGherkinStepsAsync(config.gherkin.steps || [])
     if (opts && typeof opts.timeouts === 'boolean') store.timeouts = opts.timeouts
@@ -150,10 +168,23 @@ class Container {
     if (!name) {
       return container.proxySupport
     }
-    // Always return the proxy to ensure MetaStep creation works
+    if (typeof container.support[name] === 'function') {
+      return container.support[name]
+    }
     return container.proxySupport[name]
   }
 
+  /**
+   * Get raw (non-proxied) support objects for direct access.
+   * Used by listeners to call lifecycle hooks without MetaStep wrapping.
+   *
+   * @api
+   * @returns {object}
+   */
+  static supportObjects() {
+    return container.support
+  }
+
   /**
    * Get all helpers or get a helper by name
    *
@@ -183,7 +214,7 @@ class Container {
    * @api
    */
   static tsFileMapping() {
-    return container.tsFileMapping
+    return store.tsFileMapping
   }
 
   /**
@@ -426,11 +457,11 @@ async function requireHelperFromModule(helperName, config, HelperClass) {
         tempJsFile = allTempFiles
         fileMapping = mapping
         // Store file mapping in container for runtime error fixing (merge with existing)
-        if (!container.tsFileMapping) {
-          container.tsFileMapping = new Map()
+        if (!store.tsFileMapping) {
+          store.tsFileMapping = new Map()
         }
         for (const [key, value] of mapping.entries()) {
-          container.tsFileMapping.set(key, value)
+          store.tsFileMapping.set(key, value)
         }
       } catch (tsError) {
         throw new Error(`Failed to load TypeScript helper ${importPath}: ${tsError.message}. Make sure 'typescript' package is installed.`)
@@ -542,6 +573,19 @@ function createSupportObjects(config) {
           let currentValue = currentObject[prop]
 
           if (isFunction(currentValue) || isAsyncFunction(currentValue)) {
+            if (prop.toString().charAt(0) !== '_' && currentObject._before && !beforeCalledSet.has(name)) {
+              beforeCalledSet.add(name)
+              const originalValue = currentValue
+              const wrappedValue = async function (...args) {
+                await currentObject._before()
+                return originalValue.apply(currentObject, args)
+              }
+              const ms = new MetaStep(name, prop)
+              ms.setContext(currentObject)
+              debug(`metastep is created for ${name}.${prop.toString()}() (with _before)`)
+              return ms.run.bind(ms, asyncWrapper(wrappedValue))
+            }
+
             const ms = new MetaStep(name, prop)
             ms.setContext(currentObject)
             if (isAsyncFunction(currentValue)) currentValue = asyncWrapper(currentValue)
@@ -600,6 +644,8 @@ function createSupportObjects(config) {
         let value
         if (container.sharedKeys.has(prop) && prop in container.support) {
           value = container.support[prop]
+        } else if (prop in container.support && typeof container.support[prop] === 'function') {
+          value = container.support[prop]
         } else {
           value = lazyLoad(prop)
         }
@@ -614,6 +660,9 @@ function createSupportObjects(config) {
         if (container.sharedKeys.has(key) && key in container.support) {
           return container.support[key]
         }
+        if (key in container.support && typeof container.support[key] === 'function') {
+          return container.support[key]
+        }
         return lazyLoad(key)
       },
     },
@@ -654,14 +703,28 @@ async function loadPluginFallback(modulePath, config) {
 async function createPlugins(config, options = {}) {
   const plugins = {}
 
-  const enabledPluginsByOptions = (options.plugins || '').split(',')
+  const pluginOptionMap = new Map()
+  for (const token of (options.plugins || '').split(',').filter(Boolean)) {
+    const parts = token.split(':')
+    pluginOptionMap.set(parts[0], parts.slice(1))
+  }
+
+  for (const [name] of pluginOptionMap) {
+    if (!config[name]) config[name] = {}
+  }
+
   for (const pluginName in config) {
     if (!config[pluginName]) config[pluginName] = {}
     const pluginConfig = config[pluginName]
-    if (!pluginConfig.enabled && enabledPluginsByOptions.indexOf(pluginName) < 0) {
+    const enabledByCli = pluginOptionMap.has(pluginName)
+    if (!pluginConfig.enabled && !enabledByCli) {
       continue // plugin is disabled
     }
 
+    if (enabledByCli && pluginOptionMap.get(pluginName).length > 0) {
+      pluginConfig._args = pluginOptionMap.get(pluginName)
+    }
+
     // Generic workers gate:
     // - runInWorker / runInWorkers controls plugin execution inside worker threads.
     // - runInParent / runInMain can disable plugin in workers parent process.
@@ -672,7 +735,7 @@ async function createPlugins(config, options = {}) {
       continue
     }
 
-    if (!options.child && process.env.RUNS_WITH_WORKERS === 'true' && !runInParent) {
+    if (!options.child && store.workerMode && !runInParent) {
       continue
     }
     let module
@@ -681,7 +744,7 @@ async function createPlugins(config, options = {}) {
         module = pluginConfig.require
         if (module.startsWith('.')) {
           // local
-          module = path.resolve(global.codecept_dir, module) // custom plugin
+          module = path.resolve(store.codeceptDir, module) // custom plugin
         }
       } else {
         module = `./plugin/${pluginName}.js`
@@ -698,12 +761,24 @@ async function createPlugins(config, options = {}) {
 }
 
 async function loadGherkinStepsAsync(paths) {
+  // Import BDD module to access step file tracking functions and step DSL
+  const bddModule = await import('./mocha/bdd.js')
+
   global.Before = fn => event.dispatcher.on(event.test.started, fn)
   global.After = fn => event.dispatcher.on(event.test.finished, fn)
   global.Fail = fn => event.dispatcher.on(event.test.failed, fn)
 
-  // Import BDD module to access step file tracking functions
-  const bddModule = await import('./mocha/bdd.js')
+  // Scope-inject Given/When/Then/And while loading step files so they work
+  // with noGlobals: true. When noGlobals: false, globals.js has already set
+  // them as permanent globals — skip to avoid deleting them at the end.
+  const injectStepDsl = !!store.noGlobals
+  if (injectStepDsl) {
+    global.Given = bddModule.Given
+    global.When = bddModule.When
+    global.Then = bddModule.Then
+    global.And = bddModule.And
+    global.DefineParameterType = bddModule.defineParameterType
+  }
 
   // If gherkin.steps is string, then this will iterate through that folder and send all step def js files to loadSupportObject
   // If gherkin.steps is Array, it will go the old way
@@ -716,7 +791,7 @@ async function loadGherkinStepsAsync(paths) {
       bddModule.clearCurrentStepFile()
     }
   } else {
-    const folderPath = paths.startsWith('.') ? normalizeAndJoin(global.codecept_dir, paths) : ''
+    const folderPath = paths.startsWith('.') ? normalizeAndJoin(store.codeceptDir, paths) : ''
     if (folderPath !== '') {
       const files = globSync(folderPath)
       for (const file of files) {
@@ -731,6 +806,13 @@ async function loadGherkinStepsAsync(paths) {
   delete global.Before
   delete global.After
   delete global.Fail
+  if (injectStepDsl) {
+    delete global.Given
+    delete global.When
+    delete global.Then
+    delete global.And
+    delete global.DefineParameterType
+  }
 }
 
 function loadGherkinSteps(paths) {
@@ -764,7 +846,7 @@ async function loadSupportObject(modulePath, supportObjectName) {
     }
   }
   if (typeof modulePath === 'string' && modulePath.charAt(0) === '.') {
-    modulePath = path.join(global.codecept_dir, modulePath)
+    modulePath = path.join(store.codeceptDir, modulePath)
   }
   try {
     // Use dynamic import for both ESM and CJS modules
@@ -888,7 +970,7 @@ async function loadTranslation(locale, vocabularies) {
   const langs = await Translation.getLangs()
   if (langs[locale]) {
     translation = new Translation(langs[locale])
-  } else if (fileExists(path.join(global.codecept_dir, locale))) {
+  } else if (fileExists(path.join(store.codeceptDir, locale))) {
     // get from a provided file instead
     translation = Translation.createDefault()
     translation.loadVocabulary(locale)
@@ -905,7 +987,7 @@ function getHelperModuleName(helperName, config) {
   // classical require
   if (config[helperName].require) {
     if (config[helperName].require.startsWith('.')) {
-      let helperPath = path.resolve(global.codecept_dir, config[helperName].require)
+      let helperPath = path.resolve(store.codeceptDir, config[helperName].require)
       // Add .js extension if not present for ESM compatibility
       if (!path.extname(helperPath)) {
         helperPath += '.js'

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

@@ -82,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)
@@ -237,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
@@ -257,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 {
@@ -286,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))
@@ -358,6 +513,43 @@ class WebElement {
     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