codeceptjs 4.0.0-rc.8 → 4.0.0

package/lib/history.js

@@ -2,6 +2,7 @@ import colors from 'chalk'
 import fs from 'fs'
 import path from 'path'
 import output from './output.js'
+import store from './store.js'
 
 /**
  * REPL history records REPL commands and stores them in
@@ -9,8 +10,8 @@ import output from './output.js'
  */
 class ReplHistory {
   constructor() {
-    if (global.output_dir) {
-      this.historyFile = path.join(global.output_dir, 'cli-history')
+    if (store.outputDir) {
+      this.historyFile = path.join(store.outputDir, 'cli-history')
     }
     this.commands = []
   }

package/lib/html.js

@@ -1,5 +1,8 @@
 import { parse, serialize } from 'parse5'
 import { minify } from 'html-minifier-terser'
+import beautify from 'js-beautify'
+
+const { html: html_beautify } = beautify
 
 async function minifyHtml(html) {
   return minify(html, {
@@ -14,6 +17,62 @@ async function minifyHtml(html) {
   })
 }
 
+const TRASH_HTML_CLASSES = /^(text-|color-|flex-|float-|v-|ember-|d-|border-)/
+
+function isTrashClass(className) {
+  if (!className) return true
+  if (/\d/.test(className)) return true
+  if (TRASH_HTML_CLASSES.test(className)) return true
+  if (/(:|__)/.test(className)) return true
+  return false
+}
+
+function filterClassValue(value) {
+  return (value || '')
+    .split(/\s+/)
+    .filter(c => c && !isTrashClass(c))
+    .join(' ')
+}
+
+const DROP_TAGS = new Set(['style', 'noscript'])
+const DROP_ATTRS = new Set(['style'])
+
+function cleanHtml(html) {
+  const document = parse(html)
+
+  function walk(node) {
+    if (!node) return false
+
+    if (DROP_TAGS.has(node.nodeName) || (node.nodeName === 'script' && !(node.attrs || []).some(a => a.name === 'src'))) {
+      const parent = node.parentNode
+      const idx = parent.childNodes.indexOf(node)
+      if (idx >= 0) parent.childNodes.splice(idx, 1)
+      return true
+    }
+
+    if (node.attrs) {
+      node.attrs = node.attrs.filter(attr => {
+        if (DROP_ATTRS.has(attr.name)) return false
+        if (attr.name === 'class') {
+          attr.value = filterClassValue(attr.value)
+          if (!attr.value) return false
+        }
+        return true
+      })
+    }
+
+    if (node.childNodes) {
+      for (let i = node.childNodes.length - 1; i >= 0; i--) {
+        walk(node.childNodes[i])
+      }
+    }
+    return false
+  }
+
+  walk(document)
+  return serialize(document)
+}
+
 const defaultHtmlOpts = {
   interactiveElements: ['a', 'input', 'button', 'select', 'textarea', 'option'],
   textElements: ['label', 'h1', 'h2'],
@@ -28,7 +87,6 @@ function removeNonInteractiveElements(html, opts = {}) {
   // Parse the HTML into a document tree
   const document = parse(html)
 
-  const trashHtmlClasses = /^(text-|color-|flex-|float-|v-|ember-|d-|border-)/
   // Array to store interactive elements
   const removeElements = ['path', 'script']
 
@@ -103,21 +161,10 @@ function removeNonInteractiveElements(html, opts = {}) {
     if (node.attrs) {
       // Filter and keep allowed attributes, accessibility attributes
       node.attrs = node.attrs.filter(attr => {
-        const { name, value } = attr
-        if (name === 'class') {
-          // Remove classes containing digits
-          attr.value = value
-            .split(' ')
-            // remove classes containing digits/
-            .filter(className => !/\d/.test(className))
-            // remove popular trash classes
-            .filter(className => !className.match(trashHtmlClasses))
-            // remove classes with : and __ in them
-            .filter(className => !className.match(/(:|__)/))
-            .join(' ')
+        if (attr.name === 'class') {
+          attr.value = filterClassValue(attr.value)
         }
-
-        return allowedAttrs.includes(name)
+        return allowedAttrs.includes(attr.name)
       })
     }
 
@@ -258,4 +305,31 @@ function simplifyHtmlElement(html, maxLength = 300) {
   return html
 }
 
-export { scanForErrorMessages, removeNonInteractiveElements, splitByChunks, minifyHtml, simplifyHtmlElement }
+async function formatHtml(html) {
+  let processed = html
+  try {
+    processed = await minifyHtml(processed)
+  } catch (e) {
+    // keep raw html if minification fails
+  }
+  try {
+    processed = cleanHtml(processed)
+  } catch (e) {
+    // keep minified html if cleaning fails
+  }
+  try {
+    return html_beautify(processed, {
+      indent_size: 2,
+      wrap_line_length: 0,
+      preserve_newlines: false,
+      end_with_newline: false,
+      // Force every element onto its own line so line numbers in trace HTML
+      // map 1:1 to elements (consumed by codeceptq for AI/agent debugging).
+      inline: [],
+    })
+  } catch (e) {
+    return processed
+  }
+}
+
+export { scanForErrorMessages, removeNonInteractiveElements, splitByChunks, minifyHtml, simplifyHtmlElement, formatHtml, cleanHtml, isTrashClass }

package/lib/index.js

@@ -23,6 +23,10 @@ import heal from './heal.js'
 import ai from './ai.js'
 import Workers from './workers.js'
 import Secret, { secret } from './secret.js'
+import session from './session.js'
+
+const inject = (name) => container.support(name)
+const locate = (query) => locator.build(query)
 
 export default {
   /** @type {typeof CodeceptJS.Codecept} */
@@ -67,7 +71,11 @@ export default {
   Secret,
   /** @type {typeof CodeceptJS.secret} */
   secret,
+
+  session,
+  inject,
+  locate,
 }
 
 // Named exports for ESM compatibility
-export { codecept, output, container, event, recorder, config, actor, helper, pause, within, dataTable, dataTableArgument, store, locator, heal, ai, Workers, Secret, secret }
+export { codecept, output, container, event, recorder, config, actor, helper, pause, within, dataTable, dataTableArgument, store, locator, heal, ai, Workers, Secret, secret, session, inject, locate }

package/lib/listener/config.js

@@ -2,16 +2,18 @@ import event from '../event.js'
 import recorder from '../recorder.js'
 import { deepMerge, deepClone, ucfirst } from '../utils.js'
 import output from '../output.js'
+import container from '../container.js'
 
 /**
  * Enable Helpers to listen to test events
  */
+let initialized = false
+
 export default function () {
-  // Use global flag to prevent duplicate initialization across module re-imports
-  if (global.__codeceptConfigListenerInitialized) {
+  if (initialized) {
     return
   }
-  global.__codeceptConfigListenerInitialized = true
+  initialized = true
 
   enableDynamicConfigFor('suite')
   enableDynamicConfigFor('test')
@@ -20,7 +22,7 @@ export default function () {
     event.dispatcher.on(event[type].before, (context = {}) => {
       // Get helpers dynamically at runtime, not at initialization time
       // This ensures we get the actual helper instances, not placeholders
-      const helpers = global.container.helpers()
+      const helpers = container.helpers()
 
       function updateHelperConfig(helper, config) {
         // Guard against undefined or invalid helpers

package/lib/listener/emptyRun.js

@@ -1,6 +1,7 @@
 import figures from 'figures'
 import event from '../event.js'
 import output from '../output.js'
+import container from '../container.js'
 import { searchWithFusejs } from '../utils.js'
 
 export default function () {
@@ -12,7 +13,7 @@ export default function () {
 
   event.dispatcher.on(event.all.result, () => {
     if (isEmptyRun) {
-      const mocha = global.container.mocha()
+      const mocha = container.mocha()
 
       if (mocha.options.grep) {
         output.print()

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

@@ -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]