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

package/docs/within.md

@@ -0,0 +1,55 @@
+---
+permalink: /within
+title: Within
+---
+
+# Within
+
+`within` scopes all actions inside it to a specific element on the page — useful when working with repeated UI components or narrowing interaction to a specific section.
+
+```js
+within('.js-signup-form', () => {
+  I.fillField('user[login]', 'User')
+  I.fillField('user[email]', 'user@user.com')
+  I.fillField('user[password]', 'user@user.com')
+  I.click('button')
+})
+I.see('There were problems creating your account.')
+```
+
+> ⚠ `within` can cause problems when used incorrectly. If you see unexpected behavior, refactor to use the context parameter on individual actions instead (e.g. `I.click('Login', '.nav')`). Keep `within` for the simplest cases.
+> Since `within` returns a Promise, always `await` it when you need its return value.
+
+## IFrames
+
+Use a `frame` locator to scope actions inside an iframe:
+
+```js
+within({ frame: '#editor' }, () => {
+  I.see('Page')
+  I.fillField('Body', 'Hello world')
+})
+```
+
+Nested iframes _(WebDriver & Puppeteer only)_:
+
+```js
+within({ frame: ['.content', '#editor'] }, () => {
+  I.see('Page')
+})
+```
+
+> ℹ IFrames can also be accessed via `I.switchTo` command.
+
+## Returning Values
+
+`within` can return a value for use in the scenario:
+
+```js
+const val = await within('#sidebar', () => {
+  return I.grabTextFrom({ css: 'h1' })
+})
+I.fillField('Description', val)
+```
+
+When running steps inside a `within` block, they will be shown indented in the output.

package/lib/ai.js

@@ -7,6 +7,7 @@ import { generateText } from 'ai'
 import { fileURLToPath } from 'url'
 import path from 'path'
 import { fileExists } from './utils.js'
+import store from './store.js'
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
 
@@ -24,8 +25,8 @@ async function loadPrompts() {
   for (const name of promptNames) {
     let promptPath
 
-    if (global.codecept_dir) {
-      promptPath = path.join(global.codecept_dir, `prompts/${name}.js`)
+    if (store.codeceptDir) {
+      promptPath = path.join(store.codeceptDir, `prompts/${name}.js`)
     }
 
     if (!promptPath || !fileExists(promptPath)) {

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/assertions.js

@@ -0,0 +1,18 @@
+import Assertion from './assert.js'
+import { equals, urlEquals, fileEquals } from './assert/equal.js'
+import { includes, fileIncludes } from './assert/include.js'
+import { empty } from './assert/empty.js'
+import { truth } from './assert/truth.js'
+
+export { Assertion, equals, urlEquals, fileEquals, includes, fileIncludes, empty, truth }
+
+export default {
+  Assertion,
+  equals,
+  urlEquals,
+  fileEquals,
+  includes,
+  fileIncludes,
+  empty,
+  truth,
+}

package/lib/codecept.js

@@ -21,6 +21,7 @@ import { emptyFolder } from './utils.js'
 import { initCodeceptGlobals } from './globals.js'
 import { validateTypeScriptSetup, getTSNodeESMWarning } from './utils/loaderCheck.js'
 import recorder from './recorder.js'
+import store from './store.js'
 
 import storeListener from './listener/store.js'
 import stepsListener from './listener/steps.js'
@@ -71,7 +72,7 @@ class Codecept {
         } else {
           // For npm packages, resolve from the user's directory
           // This ensures packages like tsx are found in user's node_modules
-          const userDir = global.codecept_dir || process.cwd()
+          const userDir = store.codeceptDir || process.cwd()
           
           try {
             // Use createRequire to resolve from user's directory
@@ -102,8 +103,6 @@ class Codecept {
     await this.requireModules(this.requiringModules)
     // initializing listeners
     await container.create(this.config, this.opts)
-    // Store container globally for easy access
-    global.container = container
     await this.runHooks()
   }
 
@@ -120,23 +119,27 @@ class Codecept {
    * Executes hooks.
    */
   async runHooks() {
-    // default hooks - dynamic imports for ESM
-    const listenerModules = [
-      './listener/store.js',
-      './listener/steps.js',
-      './listener/config.js',
-      './listener/result.js',
-      './listener/helpers.js',
-      './listener/globalTimeout.js',
-      './listener/globalRetry.js',
-      './listener/retryEnhancer.js',
-      './listener/exit.js',
-      './listener/emptyRun.js',
-    ]
-
-    for (const modulePath of listenerModules) {
-      const module = await import(modulePath)
-      runHook(module.default || module)
+    // For workers parent process we only need plugins/hooks.
+    // Core listeners are executed inside worker threads.
+    if (!this.opts?.skipDefaultListeners) {
+      const listenerModules = [
+        './listener/store.js',
+        './listener/steps.js',
+        './listener/config.js',
+        './listener/result.js',
+        './listener/helpers.js',
+        './listener/pageobjects.js',
+        './listener/globalTimeout.js',
+        './listener/globalRetry.js',
+        './listener/retryEnhancer.js',
+        './listener/exit.js',
+        './listener/emptyRun.js',
+      ]
+
+      for (const modulePath of listenerModules) {
+        const module = await import(modulePath)
+        runHook(module.default || module)
+      }
     }
 
     // custom hooks (previous iteration of plugins)
@@ -168,7 +171,7 @@ class Codecept {
    */
   loadTests(pattern) {
     const options = {
-      cwd: global.codecept_dir,
+      cwd: store.codeceptDir,
     }
 
     let patterns = [pattern]
@@ -200,7 +203,7 @@ class Codecept {
         globSync(pattern, options).forEach(file => {
           if (file.includes('node_modules')) return
           if (!fsPath.isAbsolute(file)) {
-            file = fsPath.join(global.codecept_dir, file)
+            file = fsPath.join(store.codeceptDir, file)
           }
           if (!this.testFiles.includes(fsPath.resolve(file))) {
             this.testFiles.push(fsPath.resolve(file))
@@ -290,7 +293,7 @@ class Codecept {
 
       if (test) {
         if (!fsPath.isAbsolute(test)) {
-          test = fsPath.join(global.codecept_dir, test)
+          test = fsPath.join(store.codeceptDir, test)
         }
         const testBasename = fsPath.basename(test, '.js')
         const testFeatureBasename = fsPath.basename(test, '.feature')

package/lib/command/check.js

@@ -135,6 +135,7 @@ export default async function (options) {
   printCheck('plugins', checks['plugins'], Object.keys(Container.plugins()).join(', '))
 
   if (Object.keys(helpers).length) {
+    store.dryRun = false
     const suite = Container.mocha().suite
     const test = createTest('test', () => {})
     checks.setup = true
@@ -154,7 +155,6 @@ export default async function (options) {
     checks.teardown = true
     for (const helper of Object.values(helpers).reverse()) {
       try {
-        if (helper._passed) await helper._passed(test)
         if (helper._after) await helper._after(test)
         if (helper._finishTest) await helper._finishTest(suite)
         if (helper._afterSuite) await helper._afterSuite(suite)
@@ -166,6 +166,7 @@ export default async function (options) {
     }
 
     printCheck('Helpers After', checks['teardown'], standardActingHelpers.some(h => Object.keys(helpers).includes(h)) ? 'Closing browser' : '')
+    store.dryRun = true
   }
 
   try {

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,8 @@ 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
+  store.dryRun = true
   const configFile = options.config
   let codecept
 
@@ -18,10 +21,15 @@ export default async function (test, options) {
   }
 
   if (config.plugins) {
-    // disable all plugins by default, they can be enabled with -p option
+    // Disable plugins that block (interactive) or perform external I/O (AI/network).
+    // Leave the rest enabled so they can register support objects (e.g. auth registers
+    // `login`); helper calls inside those support fns are already no-op'd by HelperStep
+    // when store.dryRun is true.
+    const disableInDryRun = new Set(['pause', 'pauseOnFail', 'analyze', 'aiTrace', 'pageInfo', 'heal'])
     for (const plugin in config.plugins) {
-      // if `-p all` is passed, then enabling all plugins, otherwise plugins could be enabled by `-p customLocator,commentStep,tryTo`
-      config.plugins[plugin].enabled = options.plugins === 'all'
+      if (disableInDryRun.has(plugin)) {
+        config.plugins[plugin].enabled = false
+      }
     }
   }
 
@@ -32,12 +40,12 @@ export default async function (test, options) {
     if (options.bootstrap) await codecept.bootstrap()
 
     codecept.loadTests()
-    store.dryRun = true
 
     if (!options.steps && !options.verbose && !options.debug) {
       await printTests(codecept.testFiles)
       return
     }
+    if (options.numbers) numberSteps()
     event.dispatcher.on(event.all.result, printFooter)
     await codecept.run(test)
   } catch (err) {
@@ -46,11 +54,22 @@ 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')
 
-  output.print(output.styles.debug(`Tests from ${global.codecept_dir}:`))
+  output.print(output.styles.debug(`Tests from ${store.codeceptDir}:`))
   output.print()
 
   const mocha = Container.mocha()

package/lib/command/generate.js

@@ -5,6 +5,7 @@ import { mkdirp } from 'mkdirp'
 import path from 'path'
 import { fileExists, ucfirst, lcfirst, beautify } from '../utils.js'
 import output from '../output.js'
+import store from '../store.js'
 import generateDefinitions from './definitions.js'
 import { getConfig, getTestRoot, safeFileWrite, readConfig } from './utils.js'
 
@@ -20,6 +21,7 @@ Scenario('test something', async ({ {{actor}} }) => {
 // generates empty test
 export async function test(genPath) {
   const testsPath = getTestRoot(genPath)
+  store.codeceptDir = testsPath
   global.codecept_dir = testsPath
   const config = await getConfig(testsPath)
   if (!config) return

package/lib/command/gherkin/snippets.js

@@ -8,6 +8,7 @@ import fsPath from 'path'
 import { getConfig, getTestRoot } from '../utils.js'
 import Codecept from '../../codecept.js'
 import output from '../../output.js'
+import store from '../../store.js'
 import { matchStep } from '../../mocha/bdd.js'
 
 const uuidFn = IdGenerator.uuid()
@@ -43,9 +44,9 @@ export default async function (genPath, options) {
   }
 
   const files = []
-  globSync(options.feature || config.gherkin.features, { cwd: options.feature ? '.' : global.codecept_dir }).forEach(file => {
+  globSync(options.feature || config.gherkin.features, { cwd: options.feature ? '.' : store.codeceptDir }).forEach(file => {
     if (!fsPath.isAbsolute(file)) {
-      file = fsPath.join(global.codecept_dir, file)
+      file = fsPath.join(store.codeceptDir, file)
     }
     files.push(fsPath.resolve(file))
   })
@@ -92,7 +93,7 @@ export default async function (genPath, options) {
       if (child.scenario.keyword === 'Scenario Outline') continue // skip scenario outline
       parseSteps(child.scenario.steps)
         .map(step => {
-          return Object.assign(step, { file: file.replace(global.codecept_dir, '').slice(1) })
+          return Object.assign(step, { file: file.replace(store.codeceptDir, '').slice(1) })
         })
         .map(step => newSteps.set(`${step.type}(${step})`, step))
     }
@@ -107,7 +108,7 @@ export default async function (genPath, options) {
   }
 
   if (!fsPath.isAbsolute(stepFile)) {
-    stepFile = fsPath.join(global.codecept_dir, stepFile)
+    stepFile = fsPath.join(store.codeceptDir, stepFile)
   }
 
   const snippets = [...newSteps.values()]