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

package/lib/listener/globalRetry.js

@@ -5,16 +5,27 @@ import { isNotSet } from '../utils.js'
 
 const hooks = ['Before', 'After', 'BeforeSuite', 'AfterSuite']
 
+const RETRY_PRIORITIES = {
+  MANUAL_STEP: 100,
+  STEP_PLUGIN: 50,
+  SCENARIO_CONFIG: 30,
+  FEATURE_CONFIG: 20,
+  HOOK_CONFIG: 10,
+}
+
 export default function () {
   event.dispatcher.on(event.suite.before, suite => {
     let retryConfig = Config.get('retry')
     if (!retryConfig) return
 
     if (Number.isInteger(+retryConfig)) {
-      // is number
       const retryNum = +retryConfig
       output.log(`Retries: ${retryNum}`)
-      suite.retries(retryNum)
+
+      if (suite.retries() === -1 || (suite.opts.retryPriority || 0) <= RETRY_PRIORITIES.FEATURE_CONFIG) {
+        suite.retries(retryNum)
+        suite.opts.retryPriority = RETRY_PRIORITIES.FEATURE_CONFIG
+      }
       return
     }
 
@@ -30,11 +41,18 @@ export default function () {
       hooks
         .filter(hook => !!config[hook])
         .forEach(hook => {
-          if (isNotSet(suite.opts[`retry${hook}`])) suite.opts[`retry${hook}`] = config[hook]
+          const retryKey = `retry${hook}`
+          if (isNotSet(suite.opts[retryKey])) {
+            suite.opts[retryKey] = config[hook]
+            suite.opts[`${retryKey}Priority`] = RETRY_PRIORITIES.HOOK_CONFIG
+          }
         })
 
       if (config.Feature) {
-        if (isNotSet(suite.retries())) suite.retries(config.Feature)
+        if (suite.retries() === -1 || (suite.opts.retryPriority || 0) <= RETRY_PRIORITIES.FEATURE_CONFIG) {
+          suite.retries(config.Feature)
+          suite.opts.retryPriority = RETRY_PRIORITIES.FEATURE_CONFIG
+        }
       }
 
       output.log(`Retries: ${JSON.stringify(config)}`)
@@ -46,7 +64,10 @@ export default function () {
     if (!retryConfig) return
 
     if (Number.isInteger(+retryConfig)) {
-      if (test.retries() === -1) test.retries(retryConfig)
+      if (test.retries() === -1) {
+        test.retries(retryConfig)
+        test.opts.retryPriority = RETRY_PRIORITIES.SCENARIO_CONFIG
+      }
       return
     }
 
@@ -62,9 +83,14 @@ export default function () {
       }
 
       if (config.Scenario) {
-        if (test.retries() === -1) test.retries(config.Scenario)
+        if (test.retries() === -1 || (test.opts.retryPriority || 0) <= RETRY_PRIORITIES.SCENARIO_CONFIG) {
+          test.retries(config.Scenario)
+          test.opts.retryPriority = RETRY_PRIORITIES.SCENARIO_CONFIG
+        }
         output.log(`Retries: ${config.Scenario}`)
       }
     }
   })
 }
+
+export { RETRY_PRIORITIES }

package/lib/listener/helpers.js

@@ -3,11 +3,12 @@ import event from '../event.js'
 import recorder from '../recorder.js'
 import store from '../store.js'
 import output from '../output.js'
+import container from '../container.js'
 /**
  * Enable Helpers to listen to test events
  */
 export default function () {
-  const helpers = global.container.helpers()
+  const helpers = container.helpers()
 
   const runHelpersHook = (hook, param) => {
     if (store.dryRun) return
@@ -29,11 +30,13 @@ export default function () {
   event.dispatcher.on(event.suite.before, suite => {
     // if (suite.parent) return; // only for root suite
     runAsyncHelpersHook('_beforeSuite', suite, true)
+    recorder.catch()
   })
 
   event.dispatcher.on(event.suite.after, suite => {
     // if (suite.parent) return; // only for root suite
     runAsyncHelpersHook('_afterSuite', suite, true)
+    recorder.catch()
   })
 
   event.dispatcher.on(event.test.started, test => {

package/lib/listener/mocha.js

@@ -1,10 +1,11 @@
 import event from '../event.js'
+import container from '../container.js'
 
 export default function () {
   let mocha
 
   event.dispatcher.on(event.all.before, () => {
-    mocha = global.container.mocha()
+    mocha = container.mocha()
   })
 
   event.dispatcher.on(event.test.passed, test => {

package/lib/listener/pageobjects.js

@@ -0,0 +1,43 @@
+import event from '../event.js'
+import recorder from '../recorder.js'
+import store from '../store.js'
+import container from '../container.js'
+import { resetBeforeCalledSet, getBeforeCalledSet } from '../container.js'
+
+export default function () {
+  const runAsyncSupportHook = (hook, param, force) => {
+    if (store.dryRun) return
+    const support = container.supportObjects()
+    Object.keys(support).forEach(key => {
+      if (key === 'I') return
+      const obj = support[key]
+      if (!obj || typeof obj !== 'object' || !obj[hook]) return
+      recorder.add(`pageobject ${key}.${hook}()`, () => obj[hook](param), force, false)
+    })
+  }
+
+  event.dispatcher.on(event.test.started, () => {
+    resetBeforeCalledSet()
+  })
+
+  event.dispatcher.on(event.test.after, () => {
+    if (store.dryRun) return
+    const support = container.supportObjects()
+    const called = getBeforeCalledSet()
+    called.forEach(name => {
+      const obj = support[name]
+      if (obj && obj._after) {
+        recorder.add(`pageobject ${name}._after()`, () => obj._after(), true, false)
+      }
+    })
+    recorder.catchWithoutStop(() => {})
+  })
+
+  event.dispatcher.on(event.suite.after, suite => {
+    runAsyncSupportHook('_afterSuite', suite, true)
+  })
+
+  event.dispatcher.on(event.suite.before, suite => {
+    runAsyncSupportHook('_beforeSuite', suite, true)
+  })
+}

package/lib/listener/result.js

@@ -1,11 +1,12 @@
 import event from '../event.js'
+import container from '../container.js'
 
 export default function () {
   event.dispatcher.on(event.hook.failed, err => {
-    global.container.result().addStats({ failedHooks: 1 })
+    container.result().addStats({ failedHooks: 1 })
   })
 
   event.dispatcher.on(event.test.before, test => {
-    global.container.result().addTest(test)
+    container.result().addTest(test)
   })
 }

package/lib/locator.js

@@ -381,9 +381,121 @@ class Locator {
     return new Locator({ xpath })
   }
 
+  /**
+   * Find an element with all of the provided CSS classes (word-exact match).
+   * Accepts variadic class names; all must be present.
+   *
+   * Example:
+   *   locate('button').withClass('btn-primary', 'btn-lg')
+   *
+   * @param {...string} classes
+   * @returns {Locator}
+   */
+  withClass(...classes) {
+    if (!classes.length) return this
+    const predicates = classes.map(c => `contains(concat(' ', normalize-space(@class), ' '), ' ${c} ')`)
+    const xpath = sprintf('%s[%s]', this.toXPath(), predicates.join(' and '))
+    return new Locator({ xpath })
+  }
+
+  /**
+   * Find an element with none of the provided CSS classes.
+   *
+   * Example:
+   *   locate('tr').withoutClass('deleted')
+   *
+   * @param {...string} classes
+   * @returns {Locator}
+   */
+  withoutClass(...classes) {
+    if (!classes.length) return this
+    const predicates = classes.map(c => `not(contains(concat(' ', normalize-space(@class), ' '), ' ${c} '))`)
+    const xpath = sprintf('%s[%s]', this.toXPath(), predicates.join(' and '))
+    return new Locator({ xpath })
+  }
+
+  /**
+   * Find an element that does NOT contain the provided text.
+   * @param {string} text
+   * @returns {Locator}
+   */
+  withoutText(text) {
+    text = xpathLocator.literal(text)
+    const xpath = sprintf('%s[%s]', this.toXPath(), `not(contains(., ${text}))`)
+    return new Locator({ xpath })
+  }
+
+  /**
+   * Find an element that does NOT have any of the provided attribute/value pairs.
+   * @param {Object.<string, string>} attributes
+   * @returns {Locator}
+   */
+  withoutAttr(attributes) {
+    const operands = []
+    for (const attr of Object.keys(attributes)) {
+      operands.push(`not(@${attr} = ${xpathLocator.literal(attributes[attr])})`)
+    }
+    const xpath = sprintf('%s[%s]', this.toXPath(), operands.join(' and '))
+    return new Locator({ xpath })
+  }
+
+  /**
+   * Find an element that has no direct child matching the provided locator.
+   * @param {CodeceptJS.LocatorOrString} locator
+   * @returns {Locator}
+   */
+  withoutChild(locator) {
+    const xpath = sprintf('%s[not(./child::%s)]', this.toXPath(), convertToSubSelector(locator))
+    return new Locator({ xpath })
+  }
+
+  /**
+   * Find an element that has no descendant matching the provided locator.
+   *
+   * Example:
+   *   locate('button').withoutDescendant('svg')
+   *
+   * @param {CodeceptJS.LocatorOrString} locator
+   * @returns {Locator}
+   */
+  withoutDescendant(locator) {
+    const xpath = sprintf('%s[not(./descendant::%s)]', this.toXPath(), convertToSubSelector(locator))
+    return new Locator({ xpath })
+  }
+
+  /**
+   * Append a raw XPath predicate. Escape hatch for expressions not covered by the DSL.
+   * Argument is inserted as-is inside `[ ]`; quoting/escaping is the caller's responsibility.
+   *
+   * Example:
+   *   locate('input').and('@type="text" or @type="email"')
+   *
+   * @param {string} xpathExpression
+   * @returns {Locator}
+   */
+  and(xpathExpression) {
+    const xpath = sprintf('%s[%s]', this.toXPath(), xpathExpression)
+    return new Locator({ xpath })
+  }
+
+  /**
+   * Append a negated raw XPath predicate: `[not(expr)]`.
+   *
+   * Example:
+   *   locate('button').andNot('.//svg')   // button without a descendant svg
+   *
+   * @param {string} xpathExpression
+   * @returns {Locator}
+   */
+  andNot(xpathExpression) {
+    const xpath = sprintf('%s[not(%s)]', this.toXPath(), xpathExpression)
+    return new Locator({ xpath })
+  }
+
   /**
    * @param {String} text
    * @returns {Locator}
+   * @deprecated Use {@link Locator#withClass} for word-exact class matching, or {@link Locator#withAttrContains} for substring matching.
    */
   withClassAttr(text) {
     const xpath = sprintf('%s[%s]', this.toXPath(), `contains(@class, '${text}')`)
@@ -477,15 +589,26 @@ Locator.clickable = {
       `.//button[./@name = ${literal}]`,
       `.//*[@aria-label = ${literal}]`,
       `.//*[@title = ${literal}]`,
-      `.//*[@aria-labelledby = //*[@id][normalize-space(string(.)) = ${literal}]/@id ]`,
+      `.//*[@aria-labelledby][@aria-labelledby = //*[@id][normalize-space(string(.)) = ${literal}]/@id]`,
       `.//*[@role='button'][normalize-space(.)=${literal}]`,
+      `.//*[@role='tab' or @role='link' or @role='menuitem' or @role='menuitemcheckbox' or @role='menuitemradio' or @role='option' or @role='treeitem'][contains(normalize-space(string(.)), ${literal})]`,
     ]),
 
   /**
    * @param {string} literal
    * @returns {string}
    */
-  self: literal => `./self::*[contains(normalize-space(string(.)), ${literal}) or contains(normalize-space(@value), ${literal})]`,
+  self: literal => {
+    // Narrowest-match: prefer the deepest descendant whose string-value contains the literal.
+    // Falling back to `self` without the `not(descendant...)` guard would match a container
+    // whose concatenated text happens to include the literal (e.g. a <ul role="tablist"> whose
+    // tab labels all sit in its string-value) and click the container itself.
+    const narrowest = `contains(normalize-space(string(.)), ${literal}) and not(.//*[contains(normalize-space(string(.)), ${literal})])`
+    return xpathLocator.combine([
+      `.//*[${narrowest}]`,
+      `./self::*[${narrowest} or contains(normalize-space(@value), ${literal})]`,
+    ])
+  },
 }
 
 Locator.field = {
@@ -509,7 +632,7 @@ Locator.field = {
       `.//label[contains(normalize-space(string(.)), ${literal})]//.//*[self::input | self::textarea | self::select][not(./@type = 'submit' or ./@type = 'image' or ./@type = 'hidden')]`,
       `.//*[@aria-label = ${literal}]`,
       `.//*[@title = ${literal}]`,
-      `.//*[@aria-labelledby = //*[@id][normalize-space(string(.)) = ${literal}]/@id ]`,
+      `.//*[@aria-labelledby][@aria-labelledby = //*[@id][normalize-space(string(.)) = ${literal}]/@id]`,
     ]),
 
   /**

package/lib/mocha/cli.js

@@ -8,6 +8,7 @@ import { dirname, join } from 'path'
 import event from '../event.js'
 import AssertionFailedError from '../assert/error.js'
 import output from '../output.js'
+import store from '../store.js'
 import test, { cloneTest } from './test.js'
 import { fixErrorStack } from '../utils/typescript.js'
 
@@ -41,7 +42,7 @@ class Cli extends Base {
     if (opts.verbose) level = 3
     output.level(level)
     output.print(`CodeceptJS v${codeceptVersion} ${output.standWithUkraine()}`)
-    output.print(`Using test root "${global.codecept_dir}"`)
+    output.print(`Using test root "${store.codeceptDir}"`)
 
     const showSteps = level >= 1
 
@@ -202,7 +203,18 @@ class Cli extends Base {
 
     // failures
     if (stats.failures) {
+      for (const test of this.failures) {
+        if (test.err && typeof test.err.fetchDetails === 'function') {
+          try {
+            await test.err.fetchDetails()
+          } catch (e) {
+            // ignore fetch errors
+          }
+        }
+      }
+
       // append step traces
+      const Container = await getContainer()
       this.failures = this.failures.map(test => {
         // we will change the stack trace, so we need to clone the test
         const err = test.err
@@ -265,7 +277,7 @@ class Cli extends Base {
         }
 
         try {
-          const fileMapping = global.container?.tsFileMapping?.()
+          const fileMapping = Container?.tsFileMapping?.()
           if (fileMapping) {
             fixErrorStack(err, fileMapping)
           }

package/lib/mocha/factory.js

@@ -8,6 +8,7 @@ import output from '../output.js'
 import scenarioUiFunction from './ui.js'
 import { initMochaGlobals } from '../globals.js'
 import { fixErrorStack } from '../utils/typescript.js'
+import container from '../container.js'
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = fsPath.dirname(__filename)
@@ -16,7 +17,11 @@ let mocha
 
 class MochaFactory {
   static create(config, opts) {
-    mocha = new Mocha(Object.assign(config, opts))
+    const merged = Object.assign({}, config, opts)
+    mocha = new Mocha(merged)
+    if (merged.cleanReferencesAfterRun !== true) {
+      mocha.cleanReferencesAfterRun(false)
+    }
     output.process(opts.child)
     mocha.ui(scenarioUiFunction)
 
@@ -35,7 +40,7 @@ class MochaFactory {
           // Handle ECONNREFUSED without dynamic import for now
           err = new Error('Connection refused: ' + err.toString())
         }
-        const fileMapping = global.container?.tsFileMapping?.()
+        const fileMapping = container?.tsFileMapping?.()
         if (fileMapping) {
           fixErrorStack(err, fileMapping)
         }

package/lib/mocha/inject.js

@@ -5,7 +5,7 @@ const getInjectedArguments = async (fn, test, suite) => {
   const container = containerModule.default || containerModule
 
   const testArgs = {}
-  const params = getParams(fn) || []
+  const params = getParams(fn, { warnOnLegacyFormat: true }) || []
   const objects = container.support()
 
   for (const key of params) {

package/lib/mocha/scenarioConfig.js

@@ -1,4 +1,5 @@
 import { isAsyncFunction } from '../utils.js'
+import store from '../store.js'
 
 /** @class */
 class ScenarioConfig {
@@ -40,7 +41,7 @@ class ScenarioConfig {
    * @returns {this}
    */
   retry(retries) {
-    if (process.env.SCENARIO_ONLY) retries = -retries
+    if (store.scenarioOnly) retries = -retries
     this.test.retries(retries)
     return this
   }

package/lib/mocha/ui.js

@@ -9,13 +9,12 @@ import { HookConfig, AfterSuiteHook, AfterHook, BeforeSuiteHook, BeforeHook } fr
 import { initMochaGlobals } from '../globals.js'
 import common from 'mocha/lib/interfaces/common.js'
 import container from '../container.js'
+import store from '../store.js'
 
 const setContextTranslation = context => {
-  // Try global container first, then local container instance
-  const containerToUse = global.container || container
-  if (!containerToUse) return
+  if (!container) return
 
-  const translation = containerToUse.translation?.() || containerToUse.translation
+  const translation = container.translation?.() || container.translation
   const contexts = translation?.value?.('contexts')
 
   if (contexts) {
@@ -119,7 +118,7 @@ export default function (suite) {
     context.Feature.only = function (title, opts) {
       const reString = `^${escapeRe(`${title}:`)}`
       mocha.grep(new RegExp(reString))
-      process.env.FEATURE_ONLY = true
+      store.featureOnly = true
       return context.Feature(title, opts)
     }
 
@@ -171,7 +170,7 @@ export default function (suite) {
     context.Scenario.only = function (title, opts, fn) {
       const reString = `^${escapeRe(`${suites[0].title}: ${title}`.replace(/( \| {.+})?$/g, ''))}`
       mocha.grep(new RegExp(reString))
-      process.env.SCENARIO_ONLY = true
+      store.scenarioOnly = true
       return addScenario(title, opts, fn)
     }
 

package/lib/parser.js

@@ -14,11 +14,11 @@ export const getParamsToString = function (fn) {
   return getParams(newFn).join(', ')
 }
 
-function getParams(fn) {
+function getParams(fn, { warnOnLegacyFormat = false } = {}) {
   if (fn.isSinonProxy) return []
   try {
     const reflected = parser.parse(fn)
-    if (reflected.args.length > 1 || reflected.args[0] === 'I') {
+    if (warnOnLegacyFormat && (reflected.args.length > 1 || reflected.args[0] === 'I')) {
       output.error('Error: old CodeceptJS v2 format detected. Upgrade your project to the new format -> https://bit.ly/codecept3Up')
     }
     if (reflected.destructuredArgs.length > 0) reflected.args = [...reflected.destructuredArgs]

package/lib/pause.js

@@ -18,6 +18,8 @@ let nextStep
 let finish
 let next
 let registeredVariables = {}
+let externalHandler = null
+
 /**
  * Pauses test execution and starts interactive shell
  * @param {Object<string, *>} [passedObject]
@@ -37,10 +39,10 @@ const pause = function (passedObject = {}) {
   })
 
   event.dispatcher.on(event.test.finished, () => {
-    finish()
+    if (typeof finish === 'function') finish()
     recorder.session.restore('pause')
-    rl.close()
-    history.save()
+    if (rl) rl.close()
+    if (!externalHandler) history.save()
   })
 
   recorder.add('Start new session', () => pauseSession(passedObject))
@@ -49,6 +51,15 @@ const pause = function (passedObject = {}) {
 function pauseSession(passedObject = {}) {
   registeredVariables = passedObject
   recorder.session.start('pause')
+
+  if (externalHandler) {
+    store.onPause = true
+    return externalHandler({ registeredVariables }).then(() => {
+      store.onPause = false
+      recorder.session.restore('pause')
+    })
+  }
+
   if (!next) {
     let vars = Object.keys(registeredVariables).join(', ')
     if (vars) vars = `(vars: ${vars})`
@@ -234,5 +245,28 @@ function registerVariable(name, value) {
   registeredVariables[name] = value
 }
 
+/**
+ * Hook for external pause drivers (e.g. the MCP server). When set, pauseSession
+ * delegates to the handler instead of opening a readline REPL. The handler
+ * receives `{ registeredVariables }` and returns a Promise that resolves when
+ * the driver decides to continue (resume) or step.
+ *
+ * The driver controls step-vs-resume by mutating `next` via setNextStep before
+ * resolving its Promise.
+ */
+function setPauseHandler(handler) {
+  externalHandler = handler
+}
+
+/**
+ * Trigger a one-shot pause from outside the test (e.g. the MCP server,
+ * pausing the test at a specific step index without modifying the test).
+ * Schedules pauseSession through the recorder so it slots between steps.
+ */
+function pauseNow(passedObject = {}) {
+  if (store.dryRun) return
+  recorder.add('Triggered pause', () => pauseSession(passedObject))
+}
+
 export default pause
-export { registerVariable }
+export { registerVariable, setPauseHandler, pauseNow }