codeceptjs 4.0.0-rc.9 → 4.0.0

package/lib/locator.js

@@ -58,9 +58,6 @@ class Locator {
     if (isShadow(locator)) {
       this.type = 'shadow'
     }
-    if (isPlaywrightLocator(locator)) {
-      this.type = 'pw'
-    }
 
     Locator.filters.forEach(f => f(locator, this))
   }
@@ -381,9 +378,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 +586,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 +629,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]`,
     ]),
 
   /**
@@ -630,16 +750,6 @@ function removePrefix(xpath) {
   return xpath.replace(/^(\.|\/)+/, '')
 }
 
-/**
- * @private
- * check if the locator is a Playwright locator
- * @param {string} locator
- * @returns {boolean}
- */
-function isPlaywrightLocator(locator) {
-  return locator.includes('_react') || locator.includes('_vue')
-}
-
 /**
  * @private
  * check if the locator is a role locator

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
 
@@ -213,6 +214,7 @@ class Cli extends Base {
       }
 
       // 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
@@ -275,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 }