codeceptjs 4.0.0-rc.16 → 4.0.0-rc.18

package/docs/webapi/seeFileDownloaded.mustache

@@ -0,0 +1,23 @@
+Checks that a file was downloaded during the current test.
+Downloads are automatically saved to `output/downloads`.
+
+Can be called with different arguments:
+
+- **No argument** — asserts that at least one file was downloaded.
+- **Number** — asserts that exactly N files were downloaded.
+- **String** — asserts that a file with the exact name was downloaded.
+- **Glob pattern** (contains `*`, `?`, `[`) — asserts that a file matching the pattern was downloaded.
+- **Regex string** (`/pattern/`) — asserts that a file matching the regex was downloaded.
+
+```js
+I.click('Download');
+I.seeFileDownloaded();
+
+I.seeFileDownloaded('report.pdf');
+I.seeFileDownloaded(2);
+I.seeFileDownloaded('*.pdf');
+I.seeFileDownloaded('/report-.+\\.pdf/');
+```
+
+@param {string|number} [arg] filename, number of files, glob pattern, or regex string.
+@returns {void} automatically synchronized promise through #recorder

package/lib/aria.js

@@ -0,0 +1,260 @@
+import yaml from 'js-yaml'
+
+// ─────────────────────────────────────────────────────────────────
+// Roles
+// ─────────────────────────────────────────────────────────────────
+
+const INTERACTIVE_ROLES = new Set([
+  'button',
+  'link',
+  'textbox',
+  'searchbox',
+  'checkbox',
+  'radio',
+  'switch',
+  'combobox',
+  'listbox',
+  'listitem',
+  'menu',
+  'menuitem',
+  'menuitemcheckbox',
+  'menuitemradio',
+  'option',
+  'tab',
+  'tabpanel',
+  'slider',
+  'spinbutton',
+  'treeitem',
+  'gridcell',
+])
+
+// Long groups of same-role siblings get summarised as: first N + "...M omitted..." + last N
+const SIBLING_COLLAPSE_THRESHOLD = 50
+const SIBLING_COLLAPSE_KEEP_EACH_SIDE = 5
+
+// ─────────────────────────────────────────────────────────────────
+// STEP 1 · Parse: YAML text → AriaNode[]
+// ─────────────────────────────────────────────────────────────────
+
+function unquote(value) {
+  const v = value.trim()
+  if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
+    return v.slice(1, -1)
+  }
+  return v
+}
+
+// Parse one YAML node label like:  `button "Save"`,  `textbox "Email" [focused]`,  `heading "Title" [level=2]`
+function parseLabel(label) {
+  if (!label) return null
+  const trimmed = label.trim()
+  const roleMatch = trimmed.match(/^(\w+)/)
+  if (!roleMatch) return null
+  const role = roleMatch[1].toLowerCase()
+  let rest = trimmed.slice(roleMatch[0].length)
+
+  let name
+  const nameMatch = rest.match(/^\s*"((?:[^"\\]|\\.)*)"/) || rest.match(/^\s*'((?:[^'\\]|\\.)*)'/)
+  if (nameMatch) {
+    name = nameMatch[1]
+    rest = rest.slice(nameMatch[0].length)
+  }
+
+  const attributes = {}
+  const attrMatch = rest.match(/\[([^\]]*)\]/)
+  if (attrMatch) {
+    for (const tok of attrMatch[1].split(/[\s,]+/).filter(Boolean)) {
+      const eq = tok.indexOf('=')
+      if (eq === -1) {
+        attributes[tok.toLowerCase()] = true
+        continue
+      }
+      attributes[tok.slice(0, eq).trim().toLowerCase()] = unquote(tok.slice(eq + 1))
+    }
+  }
+
+  return { role, name, attributes }
+}
+
+function yamlItemToNode(item) {
+  if (typeof item === 'string') {
+    const label = parseLabel(item)
+    if (!label) return null
+    const node = { role: label.role, name: label.name, attributes: label.attributes, children: [] }
+    return node
+  }
+  if (!item || typeof item !== 'object' || Array.isArray(item)) return null
+
+  const entries = Object.entries(item)
+  if (entries.length === 0) return null
+  const [key, value] = entries[0]
+  const label = parseLabel(key)
+  if (!label) return null
+  const node = { role: label.role, name: label.name, attributes: label.attributes, children: [] }
+
+  if (Array.isArray(value)) {
+    node.children = value.map(yamlItemToNode).filter(n => n !== null)
+    return node
+  }
+  if (value !== null && value !== undefined) node.value = String(value)
+  return node
+}
+
+function parseSnapshot(snapshot) {
+  if (!snapshot) return []
+  let parsed
+  try {
+    parsed = yaml.load(snapshot)
+  } catch {
+    return []
+  }
+  if (!Array.isArray(parsed)) return []
+  return parsed.map(yamlItemToNode).filter(n => n !== null)
+}
+
+// ─────────────────────────────────────────────────────────────────
+// STEP 2 · Transform: drop containers that contribute nothing.
+// ─────────────────────────────────────────────────────────────────
+
+function dropEmpty(nodes) {
+  return nodes.flatMap(node => {
+    const children = dropEmpty(node.children)
+    if (INTERACTIVE_ROLES.has(node.role)) return [{ ...node, children }]
+    if (children.length > 0) return [{ ...node, children }]
+    return []
+  })
+}
+
+// ─────────────────────────────────────────────────────────────────
+// STEP 3 · Render: AriaNode[] → indented YAML text
+// ─────────────────────────────────────────────────────────────────
+
+// One-line representation of a node. Stable attr order so diff comparisons are deterministic.
+function formatNode(node) {
+  let line = node.role
+  if (node.name && node.name.trim()) line += ` "${node.name.trim()}"`
+  const attrParts = []
+  for (const k of Object.keys(node.attributes).sort()) {
+    const v = node.attributes[k]
+    if (v === undefined || v === null || v === '') continue
+    if (v === true) attrParts.push(k)
+    else attrParts.push(`${k}=${v}`)
+  }
+  if (attrParts.length > 0) line += ` [${attrParts.join(' ')}]`
+  if (node.value !== undefined && node.value !== null) {
+    const text = String(node.value).trim()
+    if (text) line += `: ${text}`
+  }
+  return line
+}
+
+// Group consecutive same-role siblings.  [a,a,b,a,a,a] → [[a,a],[b],[a,a,a]]
+function groupByConsecutiveRole(nodes) {
+  return nodes.reduce((groups, node) => {
+    const last = groups[groups.length - 1]
+    if (last && last[0].role === node.role) {
+      last.push(node)
+      return groups
+    }
+    groups.push([node])
+    return groups
+  }, [])
+}
+
+// Large group of same-role siblings → first N + placeholder line + last N.
+// Returns mix of AriaNode (to render) and pre-rendered placeholder strings.
+function collapseGroup(group, depth) {
+  if (group.length <= SIBLING_COLLAPSE_THRESHOLD) return group
+  const keep = SIBLING_COLLAPSE_KEEP_EACH_SIDE
+  const omitted = group.length - keep * 2
+  const placeholder = `${'  '.repeat(depth)}- ...${omitted} similar "${group[0].role}" items omitted...`
+  return [...group.slice(0, keep), placeholder, ...group.slice(-keep)]
+}
+
+function renderTree(nodes, depth = 0) {
+  const items = groupByConsecutiveRole(nodes).flatMap(group => collapseGroup(group, depth))
+  return items
+    .map(item => {
+      if (typeof item === 'string') return item
+      const indent = '  '.repeat(depth)
+      const head = `${indent}- ${formatNode(item)}`
+      if (item.children.length === 0) return head
+      return `${head}:\n${renderTree(item.children, depth + 1)}`
+    })
+    .join('\n')
+}
+
+// ─────────────────────────────────────────────────────────────────
+// STEP 4 · Diff: collect interactive summaries → bag diff → text
+// ─────────────────────────────────────────────────────────────────
+
+// Walk tree, emit one summary string per meaningful interactive node.
+function collectSummaries(nodes) {
+  return nodes.flatMap(node => {
+    const fromChildren = collectSummaries(node.children)
+    if (!INTERACTIVE_ROLES.has(node.role)) return fromChildren
+    const summary = formatNode(node)
+    if (summary === node.role) return fromChildren  // skip empty unnamed interactive nodes
+    return [summary, ...fromChildren]
+  })
+}
+
+function countBy(items) {
+  return items.reduce((map, item) => {
+    map.set(item, (map.get(item) ?? 0) + 1)
+    return map
+  }, new Map())
+}
+
+// Bag diff: any summary appearing more in one bag than the other becomes added/removed.
+function diffSummaries(prev, curr) {
+  const before = countBy(prev)
+  const after = countBy(curr)
+  const added = []
+  const removed = []
+  for (const summary of new Set([...before.keys(), ...after.keys()])) {
+    const b = before.get(summary) ?? 0
+    const a = after.get(summary) ?? 0
+    for (let i = 0; i < a - b; i += 1) added.push(summary)
+    for (let i = 0; i < b - a; i += 1) removed.push(summary)
+  }
+  return { added, removed }
+}
+
+function formatDiff(added, removed) {
+  if (added.length === 0 && removed.length === 0) return null
+  const lines = ['ariaDiff:']
+  if (added.length === 0) {
+    lines.push('  added: []')
+  } else {
+    lines.push('  added:')
+    for (const [item, count] of [...countBy(added).entries()].sort(([a], [b]) => a.localeCompare(b))) {
+      const suffix = count > 1 ? ` (x${count})` : ''
+      lines.push(`    - ${item}${suffix}`)
+    }
+  }
+  if (removed.length === 0) {
+    lines.push('  removed: []')
+  } else {
+    lines.push(`  removed: ${removed.length} interactive elements`)
+  }
+  return lines.join('\n')
+}
+
+// ─────────────────────────────────────────────────────────────────
+// Public API — pipelines composed visibly, top-to-bottom
+// ─────────────────────────────────────────────────────────────────
+
+function compactAriaSnapshot(snapshot) {
+  if (!snapshot) return ''
+  const tree = dropEmpty(parseSnapshot(snapshot))
+  return renderTree(tree)
+}
+
+function diffAriaSnapshots(previous, current) {
+  const summariesOf = snap => collectSummaries(dropEmpty(parseSnapshot(snap)))
+  const { added, removed } = diffSummaries(summariesOf(previous), summariesOf(current))
+  return formatDiff(added, removed)
+}
+
+export { diffAriaSnapshots, compactAriaSnapshot }

package/lib/command/dryRun.js

@@ -1,3 +1,4 @@
+import chalk from 'chalk'
 import { getConfig, getTestRoot } from './utils.js'
 import Config from '../config.js'
 import Codecept from '../codecept.js'
@@ -8,6 +9,7 @@ import Container from '../container.js'
 
 export default async function (test, options) {
   if (options.grep) process.env.grep = options.grep
+  if (options.ansi === false) chalk.level = 0
   const configFile = options.config
   let codecept
 
@@ -37,6 +39,7 @@ export default async function (test, options) {
       await printTests(codecept.testFiles)
       return
     }
+    if (options.numbers) numberSteps()
     event.dispatcher.on(event.all.result, printFooter)
     await codecept.run(test)
   } catch (err) {
@@ -45,6 +48,17 @@ export default async function (test, options) {
   }
 }
 
+function numberSteps() {
+  let stepIndex = 0
+  event.dispatcher.on(event.test.before, () => {
+    stepIndex = 0
+  })
+  event.dispatcher.prependListener(event.step.before, step => {
+    stepIndex++
+    step.prefix = `${stepIndex}. ${step.prefix || ''}`
+  })
+}
+
 async function printTests(files) {
   const { default: figures } = await import('figures')
   const { default: colors } = await import('chalk')

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/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)
   }
 
   /**

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) {