codeceptjs 4.0.0-rc.17 → 4.0.0-rc.19

package/lib/command/list.js

@@ -1,3 +1,7 @@
+import fs from 'fs'
+import path from 'path'
+import { fileURLToPath } from 'url'
+import * as acorn from 'acorn'
 import { getConfig, getTestRoot } from './utils.js'
 import Codecept from '../codecept.js'
 import container from '../container.js'
@@ -5,33 +9,169 @@ import { getParamsToString } from '../parser.js'
 import { methodsOfObject } from '../utils.js'
 import output from '../output.js'
 
-export default async function (path) {
-  const testsPath = getTestRoot(path)
-  const config = await getConfig(testsPath)
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const helperDir = path.resolve(__dirname, '..', 'helper')
+const webapiDir = path.resolve(__dirname, '..', '..', 'docs', 'webapi')
+
+let partialsCache = null
+
+function loadWebApiPartials() {
+  if (partialsCache) return partialsCache
+  const map = new Map()
+  if (fs.existsSync(webapiDir)) {
+    for (const file of fs.readdirSync(webapiDir)) {
+      if (path.extname(file) !== '.mustache') continue
+      const name = path.basename(file, '.mustache')
+      map.set(name, fs.readFileSync(path.join(webapiDir, file), 'utf8'))
+    }
+  }
+  partialsCache = map
+  return map
+}
+
+function resolveHelperSource(helper, helperName, config, testsPath) {
+  const builtin = path.join(helperDir, `${helper.constructor.name}.js`)
+  if (fs.existsSync(builtin)) return builtin
+  const requirePath = config?.helpers?.[helperName]?.require
+  if (requirePath) {
+    const resolved = path.isAbsolute(requirePath) ? requirePath : path.resolve(testsPath, requirePath)
+    if (fs.existsSync(resolved)) return resolved
+  }
+  return null
+}
+
+function findClassNode(ast) {
+  for (const node of ast.body) {
+    if (node.type === 'ClassDeclaration') return node
+    if (node.type === 'ExportNamedDeclaration' && node.declaration?.type === 'ClassDeclaration') return node.declaration
+    if (node.type === 'ExportDefaultDeclaration' && node.declaration?.type === 'ClassDeclaration') return node.declaration
+  }
+  return null
+}
+
+function stripJsDoc(value) {
+  return value
+    .split('\n')
+    .map(line => line.replace(/^\s*\* ?/, ''))
+    .join('\n')
+    .trim()
+}
+
+function resolvePartials(text, partials) {
+  return text.replace(/\{\{>\s*([\w-]+)\s*\}\}/g, (match, name) => {
+    return partials.has(name) ? partials.get(name) : match
+  })
+}
+
+function extractMethodDocs(helper, helperName, config, testsPath, partials) {
+  const result = new Map()
+  const sourceFile = resolveHelperSource(helper, helperName, config, testsPath)
+  if (!sourceFile) return result
+
+  let source
+  try {
+    source = fs.readFileSync(sourceFile, 'utf8')
+  } catch {
+    return result
+  }
+
+  const comments = []
+  let ast
+  try {
+    ast = acorn.parse(source, {
+      ecmaVersion: 'latest',
+      sourceType: 'module',
+      locations: true,
+      onComment: comments,
+    })
+  } catch {
+    return result
+  }
+
+  const classNode = findClassNode(ast)
+  if (!classNode) return result
+
+  const blockComments = comments
+    .filter(c => c.type === 'Block' && c.value.startsWith('*'))
+    .sort((a, b) => a.start - b.start)
+
+  let cursor = 0
+  for (const member of classNode.body.body) {
+    if (member.type !== 'MethodDefinition') continue
+    if (member.kind === 'constructor' || member.static) continue
+    const name = member.key?.name
+    if (!name || name.startsWith('_')) continue
+
+    let attached = null
+    let attachedIdx = -1
+    for (let i = cursor; i < blockComments.length; i++) {
+      const c = blockComments[i]
+      if (c.end > member.start) break
+      attached = c
+      attachedIdx = i
+    }
+    if (attached) {
+      cursor = attachedIdx + 1
+      const stripped = stripJsDoc(attached.value)
+      const resolved = resolvePartials(stripped, partials)
+      result.set(name, resolved)
+    }
+  }
+
+  return result
+}
+
+function printDocBlock(doc) {
+  if (!doc) return
+  for (const line of doc.split('\n')) {
+    output.print(`    ${line}`)
+  }
+  output.print('')
+}
+
+export default async function (path, options = {}) {
+  const configFile = options.config
+  const testsPath = getTestRoot(configFile || path)
+  const config = await getConfig(configFile || testsPath)
   const codecept = new Codecept(config, {})
   await codecept.init(testsPath)
   await container.started()
 
-  output.print('List of test actions: -- ')
+  const filter = options.action ? options.action.replace(/^I\./, '') : null
+  const showDocs = !!(options.docs || filter)
+  const partials = showDocs ? loadWebApiPartials() : null
+
+  if (!filter) output.print('List of test actions: -- ')
   const helpers = container.helpers()
   const supportI = container.support('I')
   const actions = []
+  let matched = false
   for (const name in helpers) {
     const helper = helpers[name]
+    const docs = showDocs ? extractMethodDocs(helper, name, config, testsPath, partials) : null
     methodsOfObject(helper).forEach(action => {
-      const params = getParamsToString(helper[action])
       actions[action] = 1
+      if (filter && action !== filter) return
+      const params = getParamsToString(helper[action])
       output.print(` ${output.colors.grey(name)} I.${output.colors.bold(action)}(${params})`)
+      if (docs && docs.has(action)) printDocBlock(docs.get(action))
+      matched = true
     })
   }
   for (const name in supportI) {
-    if (actions[name]) {
-      continue
-    }
+    if (actions[name]) continue
+    if (filter && name !== filter) continue
     const actor = supportI[name]
     const params = getParamsToString(actor)
     output.print(` I.${output.colors.bold(name)}(${params})`)
+    matched = true
+  }
+  if (filter && !matched) {
+    output.print(`No action named ${output.colors.bold(filter)} found in enabled helpers or support objects.`)
+    return
+  }
+  if (!filter) {
+    output.print('PS: Actions are retrieved from enabled helpers. ')
+    output.print('Implement custom actions in your helper classes.')
   }
-  output.print('PS: Actions are retrieved from enabled helpers. ')
-  output.print('Implement custom actions in your helper classes.')
 }

package/lib/command/query.js

@@ -0,0 +1,218 @@
+import fs from 'fs'
+import * as parse5 from 'parse5'
+import { DOMImplementation, XMLSerializer } from '@xmldom/xmldom'
+import xpath from 'xpath'
+import Locator from '../locator.js'
+import { xpathLocator } from '../utils.js'
+
+export default async function query(locator, context, options = {}) {
+  const html = options.file ? fs.readFileSync(options.file, 'utf8') : await readStdin()
+
+  if (!html || !html.trim()) {
+    console.error('codeceptq: no HTML input. Pipe HTML via stdin or use --file <path>.')
+    process.exitCode = 2
+    return
+  }
+
+  let xpathExpr
+  let contextExpr = null
+  try {
+    xpathExpr = buildXPath(locator, options)
+    if (context) contextExpr = buildXPath(context, {})
+  } catch (err) {
+    console.error(`codeceptq: cannot build XPath: ${err.message}`)
+    process.exitCode = 2
+    return
+  }
+
+  const { doc, source } = htmlToDoc(html)
+
+  let nodes
+  try {
+    if (contextExpr) {
+      const ctxNodes = toArray(xpath.select(contextExpr, doc))
+      const seen = new Set()
+      nodes = []
+      for (const ctx of ctxNodes) {
+        for (const m of toArray(xpath.select(xpathExpr, ctx))) {
+          if (!seen.has(m)) {
+            seen.add(m)
+            nodes.push(m)
+          }
+        }
+      }
+    } else {
+      nodes = toArray(xpath.select(xpathExpr, doc))
+    }
+  } catch (err) {
+    console.error(`codeceptq: XPath evaluation failed for "${xpathExpr}": ${err.message}`)
+    process.exitCode = 2
+    return
+  }
+
+  const limit = parseInt(options.limit, 10) || 20
+  const snippetLen = parseInt(options.snippet, 10) || 500
+  const truncated = nodes.slice(0, limit)
+  const where = options.file || 'stdin'
+
+  if (options.json) {
+    process.stdout.write(
+      JSON.stringify(
+        {
+          locator,
+          context: context || null,
+          xpath: xpathExpr,
+          contextXPath: contextExpr,
+          source: where,
+          total: nodes.length,
+          shown: truncated.length,
+          matches: truncated.map(n => ({
+            line: n.__line ?? null,
+            snippet: renderSnippet(n, source, snippetLen, options.full),
+          })),
+        },
+        null,
+        2,
+      ) + '\n',
+    )
+  } else {
+    if (nodes.length === 0) {
+      console.log(`No matches for ${quote(locator)}${context ? ` within ${quote(context)}` : ''} in ${where}`)
+      console.log(`(xpath: ${xpathExpr})`)
+    } else {
+      const noun = nodes.length === 1 ? 'match' : 'matches'
+      const more = nodes.length > truncated.length ? ` (showing first ${truncated.length})` : ''
+      console.log(`${nodes.length} ${noun} for ${quote(locator)}${context ? ` within ${quote(context)}` : ''} in ${where}${more}`)
+      console.log()
+      truncated.forEach((node, i) => {
+        const line = node.__line ?? '?'
+        console.log(`${i + 1}. Line ${line}`)
+        const snippet = renderSnippet(node, source, snippetLen, options.full)
+        snippet.split('\n').forEach(l => console.log('   ' + l))
+        console.log()
+      })
+    }
+  }
+
+  if (nodes.length === 0) process.exitCode = 1
+}
+
+function buildXPath(input, options) {
+  const literal = xpathLocator.literal(input)
+  if (options.field) return Locator.field.byText(literal)
+  if (options.click || options.clickable) return Locator.clickable.wide(literal)
+  if (options.checkable) return Locator.checkable.byText(literal)
+  if (options.select) {
+    return Locator.select.byVisibleText(literal).replace(/\.\/(option|optgroup)/g, './/$1')
+  }
+
+  if (options.xpath) return new Locator({ xpath: input }).toXPath()
+  if (options.css) return new Locator({ css: input }).toXPath()
+
+  const loc = new Locator(input)
+  if (loc.type === 'fuzzy') {
+    return xpathLocator.combine([Locator.clickable.wide(literal), Locator.field.byText(literal)])
+  }
+  return loc.toXPath()
+}
+
+function htmlToDoc(html) {
+  const p5doc = parse5.parse(html, { sourceCodeLocationInfo: true })
+  const impl = new DOMImplementation()
+  const doc = impl.createDocument(null, null, null)
+  walkParse5(p5doc, doc, doc)
+  return { doc, source: html }
+}
+
+function walkParse5(p5node, xmlParent, xmlDoc) {
+  for (const child of p5node.childNodes || []) {
+    const name = child.nodeName
+    if (name === '#text') {
+      if (child.value != null) {
+        const t = xmlDoc.createTextNode(child.value)
+        if (child.sourceCodeLocation) t.__line = child.sourceCodeLocation.startLine
+        xmlParent.appendChild(t)
+      }
+    } else if (name === '#comment') {
+      try {
+        xmlParent.appendChild(xmlDoc.createComment(child.data || ''))
+      } catch {
+        // ignore comments xmldom rejects
+      }
+    } else if (name === '#documentType') {
+      // skip doctype
+    } else {
+      const tagName = child.tagName || name
+      let el
+      try {
+        el = xmlDoc.createElement(tagName)
+      } catch {
+        continue
+      }
+      for (const attr of child.attrs || []) {
+        try {
+          el.setAttribute(attr.name, attr.value)
+        } catch {
+          // ignore attrs xmldom rejects (namespaces, invalid names)
+        }
+      }
+      const loc = child.sourceCodeLocation
+      if (loc) {
+        el.__line = loc.startLine
+        el.__startOffset = loc.startOffset
+        el.__endOffset = loc.endOffset
+        el.__startTagEndOffset = loc.startTag ? loc.startTag.endOffset : loc.endOffset
+      }
+      xmlParent.appendChild(el)
+      walkParse5(child, el, xmlDoc)
+    }
+  }
+}
+
+function renderSnippet(node, source, snippetLen, full) {
+  if (typeof node.__startOffset !== 'number') {
+    try {
+      return new XMLSerializer().serializeToString(node)
+    } catch {
+      return `<${node.nodeName || '?'}>`
+    }
+  }
+  const start = node.__startOffset
+  const end = node.__endOffset ?? start
+  if (full) return source.slice(start, end)
+
+  const tagEnd = node.__startTagEndOffset ?? end
+  const openingTag = source.slice(start, tagEnd)
+  if (end <= tagEnd) return openingTag
+
+  const totalLen = end - start
+  if (totalLen <= snippetLen) return source.slice(start, end)
+
+  const remaining = Math.max(0, snippetLen - openingTag.length)
+  if (remaining < 20) return openingTag + ' …'
+  return openingTag + source.slice(tagEnd, tagEnd + remaining) + ' …'
+}
+
+function readStdin() {
+  return new Promise((resolve, reject) => {
+    if (process.stdin.isTTY) {
+      resolve('')
+      return
+    }
+    let data = ''
+    process.stdin.setEncoding('utf8')
+    process.stdin.on('data', chunk => (data += chunk))
+    process.stdin.on('end', () => resolve(data))
+    process.stdin.on('error', reject)
+  })
+}
+
+function toArray(v) {
+  if (Array.isArray(v)) return v
+  if (v == null || v === '' || typeof v === 'boolean' || typeof v === 'number') return []
+  return [v]
+}
+
+function quote(s) {
+  return `'${String(s).replace(/'/g, "\\'")}'`
+}

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,6 +15,7 @@ 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
 
@@ -121,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
@@ -748,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
@@ -781,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) {

package/lib/element/WebElement.js

@@ -513,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

package/lib/globals.js

@@ -27,9 +27,19 @@ export async function initCodeceptGlobals(dir, config, container) {
   global.codecept_dir = dir
   global.output_dir = fsPath.resolve(dir, config.output)
 
+  // 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, pause, within, session } from "codeceptjs"` instead. Set `noGlobals: true` in config to disable globals.'));
+  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
@@ -40,12 +50,6 @@ export async function initCodeceptGlobals(dir, config, container) {
   }
   global.Actor = global.actor
 
-  // Use dynamic imports for modules to avoid circular dependencies
-  global.pause = async (...args) => {
-    const pauseModule = await import('./pause.js')
-    return (pauseModule.default || pauseModule)(...args)
-  }
-
   global.within = async (...args) => {
     return (await import('./effects.js')).within(...args)
   }
@@ -62,9 +66,6 @@ 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)