codeceptjs 4.0.2-beta.9 → 4.0.2

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
@@ -136,7 +138,7 @@ function executeRun(runName, runConfig) {
 
   outputDir = clearString(outputDir)
 
-  // tweaking default output directories and for mochawesome
+  // tweaking default output directories
   overriddenConfig = replaceValueDeep(overriddenConfig, 'output', path.join(config.output, outputDir))
   overriddenConfig = replaceValueDeep(overriddenConfig, 'reportDir', path.join(config.output, outputDir))
   overriddenConfig = replaceValueDeep(overriddenConfig, 'mochaFile', path.join(config.output, outputDir, `${browserName}_report.xml`))

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)
@@ -85,19 +87,5 @@ export default async function (workerCount, selectedRuns, options) {
     process.exitCode = 1
   } finally {
     await workers.teardownAll()
-    
-    // Force exit if event loop doesn't clear naturally
-    // This is needed because worker threads may leave handles open
-    // even after proper cleanup, preventing natural process termination
-    if (!options.noExit) {
-      // Use beforeExit to ensure we run after all other exit handlers
-      // have set the correct exit code
-      process.once('beforeExit', (code) => {
-        // Give cleanup a moment to complete, then force exit with the correct code
-        setTimeout(() => {
-          process.exit(code || process.exitCode || 0)
-        }, 100)
-      })
-    }
   }
 }

package/lib/command/run.js

@@ -1,8 +1,7 @@
-import { getConfig, printError, getTestRoot, createOutputDir } from './utils.js'
+import { getConfig, printError, getTestRoot, createOutputDir, autoExit } from './utils.js'
 import Config from '../config.js'
 import store from '../store.js'
 import Codecept from '../codecept.js'
-import container from '../container.js'
 
 export default async function (test, options) {
   // registering options globally to use in config
@@ -32,7 +31,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()
     }
@@ -43,19 +42,6 @@ export default async function (test, options) {
     process.exitCode = 1
   } finally {
     await codecept.teardown()
-
-    // Schedule a delayed exit to prevent process hanging due to browser helper event loops
-    // Only needed for Playwright/Puppeteer which keep the event loop alive
-    // Wait 1 second to allow final cleanup and output to complete
-    if (!process.env.CODECEPT_DISABLE_AUTO_EXIT) {
-      const helpers = container.helpers()
-      const hasBrowserHelper = helpers && (helpers.Playwright || helpers.Puppeteer || helpers.WebDriver)
-      
-      if (hasBrowserHelper) {
-        setTimeout(() => {
-          process.exit(process.exitCode || 0)
-        }, 1000).unref()
-      }
-    }
+    await autoExit()
   }
 }

package/lib/command/utils.js

@@ -107,6 +107,20 @@ export const createOutputDir = (config, testRoot) => {
   }
 }
 
+export async function autoExit() {
+  const timeout = parseInt(process.env.CODECEPT_AUTO_EXIT_TIMEOUT, 10)
+  if (timeout === 0) return
+  const exitTimeout = timeout || 2000
+
+  const { default: container } = await import('../container.js')
+  const helpers = container.helpers()
+  if (!helpers || !Object.values(helpers).some(h => typeof h._cleanup === 'function')) return
+
+  const { default: recorder } = await import('../recorder.js')
+  await Promise.race([recorder.promise(), new Promise(resolve => setTimeout(resolve, exitTimeout))])
+  process.exit(process.exitCode || 0)
+}
+
 export const findConfigFile = testsPath => {
   const extensions = ['js', 'ts']
   for (const ext of extensions) {