codeceptjs 4.0.0-rc.2 → 4.0.0-rc.20

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/command/run-multiple.js

@@ -8,6 +8,7 @@ import event from '../event.js'
 import { createRuns } from './run-multiple/collection.js'
 import { clearString, replaceValueDeep } from '../utils.js'
 import { getConfig, getTestRoot, fail } from './utils.js'
+import store from '../store.js'
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = path.dirname(__filename)
@@ -35,6 +36,7 @@ export default async function (selectedRuns, options) {
   const configFile = options.config
 
   const testRoot = getTestRoot(configFile)
+  store.codeceptDir = testRoot
   global.codecept_dir = testRoot
 
   // copy opts to run

package/lib/command/run-workers.js

@@ -41,6 +41,8 @@ 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
+  store.workerMode = true
+  process.env.RUNS_WITH_WORKERS = 'true'
 
   const workers = new Workers(numberOfWorkers, config)
   workers.overrideConfig(overrideConfigs)

package/lib/command/run.js

@@ -32,7 +32,7 @@ export default async function (test, options) {
     codecept.loadTests(test)
 
     if (options.verbose) {
-      global.debugMode = true
+      store.debugMode = true
       const { getMachineInfo } = await import('./info.js')
       await getMachineInfo()
     }

package/lib/command/workers/runTests.js

@@ -21,8 +21,8 @@ const { options, tests, testRoot, workerIndex, poolMode } = workerData
 
 // Global error handlers to catch critical errors but not test failures
 process.on('uncaughtException', (err) => {
-  if (global.container?.tsFileMapping && fixErrorStack) {
-    const fileMapping = global.container.tsFileMapping()
+  if (container?.tsFileMapping && fixErrorStack) {
+    const fileMapping = container.tsFileMapping()
     if (fileMapping) {
       fixErrorStack(err, fileMapping)
     }
@@ -40,8 +40,8 @@ process.on('uncaughtException', (err) => {
 })
 
 process.on('unhandledRejection', (reason, promise) => {
-  if (reason && typeof reason === 'object' && reason.stack && global.container?.tsFileMapping && fixErrorStack) {
-    const fileMapping = global.container.tsFileMapping()
+  if (reason && typeof reason === 'object' && reason.stack && container?.tsFileMapping && fixErrorStack) {
+    const fileMapping = container.tsFileMapping()
     if (fileMapping) {
       fixErrorStack(reason, fileMapping)
     }
@@ -163,8 +163,8 @@ initPromise = (async function () {
       // IMPORTANT: await is required here since getConfig is async
       baseConfig = await getConfig(options.config || testRoot)
     } catch (configErr) {
-      if (global.container?.tsFileMapping && fixErrorStack) {
-        const fileMapping = global.container.tsFileMapping()
+      if (container?.tsFileMapping && fixErrorStack) {
+        const fileMapping = container.tsFileMapping()
         if (fileMapping) {
           fixErrorStack(configErr, fileMapping)
         }
@@ -185,8 +185,8 @@ initPromise = (async function () {
     try {
       await codecept.init(testRoot)
     } catch (initErr) {
-      if (global.container?.tsFileMapping && fixErrorStack) {
-        const fileMapping = global.container.tsFileMapping()
+      if (container?.tsFileMapping && fixErrorStack) {
+        const fileMapping = container.tsFileMapping()
         if (fileMapping) {
           fixErrorStack(initErr, fileMapping)
         }
@@ -218,8 +218,8 @@ initPromise = (async function () {
       parentPort?.close()
     }
   } catch (err) {
-    if (global.container?.tsFileMapping && fixErrorStack) {
-      const fileMapping = global.container.tsFileMapping()
+    if (container?.tsFileMapping && fixErrorStack) {
+      const fileMapping = container.tsFileMapping()
       if (fileMapping) {
         fixErrorStack(err, fileMapping)
       }

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