codeceptjs 4.0.0-rc.1 → 4.0.0-rc.11

package/lib/plugin/retryFailedStep.js

@@ -1,7 +1,5 @@
 import event from '../event.js'
-
 import recorder from '../recorder.js'
-
 import store from '../store.js'
 
 const defaultConfig = {
@@ -9,6 +7,15 @@ const defaultConfig = {
   defaultIgnoredSteps: ['amOnPage', 'wait*', 'send*', 'execute*', 'run*', 'have*'],
   factor: 1.5,
   ignoredSteps: [],
+  deferToScenarioRetries: true,
+}
+
+const RETRY_PRIORITIES = {
+  MANUAL_STEP: 100,
+  STEP_PLUGIN: 50,
+  SCENARIO_CONFIG: 30,
+  FEATURE_CONFIG: 20,
+  HOOK_CONFIG: 10,
 }
 
 /**
@@ -49,6 +56,7 @@ const defaultConfig = {
  * * `ignoredSteps` - an array for custom steps to ignore on retry. Use it to append custom steps to ignored list.
  * You can use step names or step prefixes ending with `*`. As such, `wait*` will match all steps starting with `wait`.
  * To append your own steps to ignore list - copy and paste a default steps list. Regexp values are accepted as well.
+ * * `deferToScenarioRetries` - when enabled (default), step retries are automatically disabled if scenario retries are configured to avoid excessive total retries.
  *
  * #### Example
  *
@@ -88,73 +96,74 @@ export default function (config) {
     if (!enableRetry) return
     if (store.debugMode) return false
     if (!store.autoRetries) return false
-    // Don't retry terminal errors (e.g., frame detachment errors)
     if (err && err.isTerminal) return false
-    // Don't retry navigation errors that are known to be terminal
     if (err && err.message && (err.message.includes('ERR_ABORTED') || err.message.includes('frame was detached') || err.message.includes('Target page, context or browser has been closed'))) return false
     if (customWhen) return customWhen(err)
     return true
   }
   config.when = when
 
-  // Ensure retry options are available before any steps run
   if (!recorder.retries.find(r => r === config)) {
     recorder.retries.push(config)
   }
 
   event.dispatcher.on(event.step.started, step => {
-    // if a step is ignored - return
     for (const ignored of config.ignoredSteps) {
       if (step.name === ignored) return
       if (ignored instanceof RegExp) {
         if (step.name.match(ignored)) return
       } else if (ignored.indexOf('*') && step.name.startsWith(ignored.slice(0, -1))) return
     }
-    enableRetry = true // enable retry for a step
+    enableRetry = true
   })
 
-  // Disable retry only after a successful step; keep it enabled for failure so retry logic can act
   event.dispatcher.on(event.step.passed, () => {
     enableRetry = false
   })
 
   event.dispatcher.on(event.test.before, test => {
-    // pass disableRetryFailedStep is a preferred way to disable retries
-    // test.disableRetryFailedStep is used for backward compatibility
     if (!test.opts) test.opts = {}
     if (test.opts.disableRetryFailedStep || test.disableRetryFailedStep) {
       store.autoRetries = false
-      return // disable retry when a test is not active
+      return
+    }
+
+    const scenarioRetries = typeof test.retries === 'function' ? test.retries() : -1
+    const stepRetryPriority = RETRY_PRIORITIES.STEP_PLUGIN
+    const scenarioPriority = test.opts.retryPriority || 0
+
+    if (scenarioRetries > 0 && config.deferToScenarioRetries !== false) {
+      store.autoRetries = false
+      return
     }
 
-    // Don't apply plugin retry logic if there are already manual retries configured
-    // Check if any retry configs exist that aren't from this plugin
     const hasManualRetries = recorder.retries.some(retry => retry !== config)
     if (hasManualRetries) {
       store.autoRetries = false
       return
     }
 
-    // this option is used to set the retries inside _before() block of helpers
     store.autoRetries = true
     test.opts.conditionalRetries = config.retries
-    // debug: record applied retries value for tests
+    test.opts.stepRetryPriority = stepRetryPriority
+
     if (process.env.DEBUG_RETRY_PLUGIN) {
-      // eslint-disable-next-line no-console
       console.log('[retryFailedStep] applying retries =', config.retries, 'for test', test.title)
     }
     recorder.retry(config)
   })
 
-  // Fallback for environments where event.test.before wasn't emitted (runner scenarios)
   event.dispatcher.on(event.test.started, test => {
     if (test.opts?.disableRetryFailedStep || test.disableRetryFailedStep) return
 
-    // Don't apply plugin retry logic if there are already manual retries configured
-    // Check if any retry configs exist that aren't from this plugin
     const hasManualRetries = recorder.retries.some(retry => retry !== config)
     if (hasManualRetries) return
 
+    const scenarioRetries = typeof test.retries === 'function' ? test.retries() : -1
+    if (scenarioRetries > 0 && config.deferToScenarioRetries !== false) {
+      return
+    }
+
     if (!store.autoRetries) {
       store.autoRetries = true
       test.opts.conditionalRetries = test.opts.conditionalRetries || config.retries

package/lib/plugin/stepByStepReport.js

@@ -207,7 +207,11 @@ export default function (config) {
     stepNum++
     slides[fileName] = step
     try {
-      await helper.saveScreenshot(path.join(dir, fileName), config.fullPageScreenshots)
+      const screenshotPath = path.join(dir, fileName)
+      await helper.saveScreenshot(screenshotPath, config.fullPageScreenshots)
+
+      step.artifacts = step.artifacts || {}
+      step.artifacts.screenshot = screenshotPath
     } catch (err) {
       output.plugin(`Can't save step screenshot: ${err}`)
       error = err

package/lib/step/config.js

@@ -1,20 +1,33 @@
+/**
+ * @typedef {Object} StepOptions
+ * @property {number|'first'|'last'} [elementIndex] - Select a specific element when multiple match. 1-based positive index, negative from end, or 'first'/'last'.
+ * @property {boolean} [exact] - Enable strict mode for this step. Throws if multiple elements match.
+ * @property {boolean} [strictMode] - Alias for exact.
+ * @property {boolean} [ignoreCase] - Perform case-insensitive text matching.
+ */
+
 /**
  * StepConfig is a configuration object for a step.
  * It is used to create a new step that is a combination of other steps.
  */
 class StepConfig {
   constructor(opts = {}) {
-    /** @member {{ opts: Record<string, any>, timeout: number|undefined, retry: number|undefined }} */
+    /** @member {{ opts: StepOptions, timeout: number|undefined, retry: number|undefined }} */
     this.config = {
       opts,
       timeout: undefined,
       retry: undefined,
     }
+    this.__isStepConfig = true
+  }
+
+  static isStepConfig(obj) {
+    return obj && (obj instanceof StepConfig || obj.__isStepConfig === true)
   }
 
   /**
    * Set the options for the step.
-   * @param {object} opts - The options for the step.
+   * @param {StepOptions} opts - The options for the step.
    * @returns {StepConfig} - The step configuration object.
    */
   opts(opts) {

package/lib/step/record.js

@@ -11,7 +11,7 @@ function recordStep(step, args) {
 
   // apply step configuration
   const lastArg = args[args.length - 1]
-  if (lastArg instanceof StepConfig) {
+  if (StepConfig.isStepConfig(lastArg)) {
     const stepConfig = args.pop()
     const { opts, timeout, retry } = stepConfig.getConfig()
 

package/lib/utils.js

@@ -150,6 +150,24 @@ export const decodeUrl = function (url) {
   return decodeURIComponent(decodeURIComponent(decodeURIComponent(url)))
 }
 
+export const normalizePath = function (path) {
+  if (path === '' || path === '/') return '/'
+  return path
+    .replace(/\/+/g, '/')
+    .replace(/\/$/, '') || '/'
+}
+
+export const resolveUrl = function (url, baseUrl) {
+  if (!url) return url
+  if (url.indexOf('http') === 0) return url
+  if (!baseUrl) return url
+  try {
+    return new URL(url, baseUrl).href
+  } catch (e) {
+    return url
+  }
+}
+
 export const xpathLocator = {
   /**
    * @param {string} string
@@ -640,6 +658,36 @@ export const base64EncodeFile = function (filePath) {
   return Buffer.from(fs.readFileSync(filePath)).toString('base64')
 }
 
+export const getMimeType = function (fileName) {
+  const ext = path.extname(fileName).toLowerCase()
+  const mimeTypes = {
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.png': 'image/png',
+    '.gif': 'image/gif',
+    '.bmp': 'image/bmp',
+    '.svg': 'image/svg+xml',
+    '.webp': 'image/webp',
+    '.pdf': 'application/pdf',
+    '.txt': 'text/plain',
+    '.html': 'text/html',
+    '.css': 'text/css',
+    '.js': 'application/javascript',
+    '.json': 'application/json',
+    '.xml': 'application/xml',
+    '.zip': 'application/zip',
+    '.csv': 'text/csv',
+    '.doc': 'application/msword',
+    '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    '.xls': 'application/vnd.ms-excel',
+    '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    '.mp3': 'audio/mpeg',
+    '.mp4': 'video/mp4',
+    '.wav': 'audio/wav',
+  }
+  return mimeTypes[ext] || 'application/octet-stream'
+}
+
 export const markdownToAnsi = function (markdown) {
   return (
     markdown

package/lib/workers.js

@@ -28,7 +28,7 @@ const pathToWorker = path.join(__dirname, 'command', 'workers', 'runTests.js')
 
 const initializeCodecept = async (configPath, options = {}) => {
   const config = await mainConfig.load(configPath || '.')
-  const codecept = new Codecept(config, options)
+  const codecept = new Codecept(config, { ...options, skipDefaultListeners: true })
   await codecept.init(getTestRoot(configPath))
   codecept.loadTests()
 
@@ -625,13 +625,32 @@ class Workers extends EventEmitter {
 
           break
         case event.suite.before:
-          this.emit(event.suite.before, deserializeSuite(message.data))
+          {
+            const suite = deserializeSuite(message.data)
+            this.emit(event.suite.before, suite)
+            event.dispatcher.emit(event.suite.before, suite)
+          }
+          break
+        case event.suite.after:
+          {
+            const suite = deserializeSuite(message.data)
+            this.emit(event.suite.after, suite)
+            event.dispatcher.emit(event.suite.after, suite)
+          }
           break
         case event.test.before:
-          this.emit(event.test.before, deserializeTest(message.data))
+          {
+            const test = deserializeTest(message.data)
+            this.emit(event.test.before, test)
+            event.dispatcher.emit(event.test.before, test)
+          }
           break
         case event.test.started:
-          this.emit(event.test.started, deserializeTest(message.data))
+          {
+            const test = deserializeTest(message.data)
+            this.emit(event.test.started, test)
+            event.dispatcher.emit(event.test.started, test)
+          }
           break
         case event.test.failed:
           // For hook failures, emit immediately as there won't be a test.finished event
@@ -645,7 +664,11 @@ class Workers extends EventEmitter {
           // Skip individual passed events - we'll emit based on finished state
           break
         case event.test.skipped:
-          this.emit(event.test.skipped, deserializeTest(message.data))
+          {
+            const test = deserializeTest(message.data)
+            this.emit(event.test.skipped, test)
+            event.dispatcher.emit(event.test.skipped, test)
+          }
           break
         case event.test.finished:
           // Handle different types of test completion properly
@@ -674,28 +697,47 @@ class Workers extends EventEmitter {
               }
             }
 
-            this.emit(event.test.finished, deserializeTest(data))
+            const test = deserializeTest(data)
+            this.emit(event.test.finished, test)
+            event.dispatcher.emit(event.test.finished, test)
           }
           break
         case event.test.after:
-          this.emit(event.test.after, deserializeTest(message.data))
+          {
+            const test = deserializeTest(message.data)
+            this.emit(event.test.after, test)
+            event.dispatcher.emit(event.test.after, test)
+          }
           break
         case event.step.finished:
           this.emit(event.step.finished, message.data)
+          event.dispatcher.emit(event.step.finished, message.data)
           break
         case event.step.started:
           this.emit(event.step.started, message.data)
+          event.dispatcher.emit(event.step.started, message.data)
           break
         case event.step.passed:
           this.emit(event.step.passed, message.data)
+          event.dispatcher.emit(event.step.passed, message.data)
           break
         case event.step.failed:
           this.emit(event.step.failed, message.data, message.data.error)
+          event.dispatcher.emit(event.step.failed, message.data, message.data.error)
           break
         case event.hook.failed:
           // Hook failures are already reported as test failures by the worker
           // Just emit the hook.failed event for listeners
           this.emit(event.hook.failed, message.data)
+          event.dispatcher.emit(event.hook.failed, message.data)
+          break
+        case event.hook.passed:
+          this.emit(event.hook.passed, message.data)
+          event.dispatcher.emit(event.hook.passed, message.data)
+          break
+        case event.hook.finished:
+          this.emit(event.hook.finished, message.data)
+          event.dispatcher.emit(event.hook.finished, message.data)
           break
       }
     })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codeceptjs",
-  "version": "4.0.0-rc.1",
+  "version": "4.0.0-rc.11",
   "type": "module",
   "description": "Supercharged End 2 End Testing Framework for NodeJS",
   "keywords": [
@@ -44,9 +44,10 @@
     "./store": "./lib/store.js"
   },
   "bin": {
-    "codeceptjs": "./bin/codecept.js"
+    "codeceptjs": "./bin/codecept.js",
+    "codeceptjs-mcp": "./bin/mcp-server.js"
   },
-  "repository": "Codeception/codeceptjs",
+  "repository": "codeceptjs/CodeceptJS",
   "scripts": {
     "test-server": "node bin/test-server.js test/data/rest/db.json --host 0.0.0.0 -p 8010 --read-only",
     "test-server:writable": "node bin/test-server.js test/data/rest/db.json --host 0.0.0.0 -p 8010",
@@ -90,6 +91,7 @@
     "@cucumber/cucumber-expressions": "18",
     "@cucumber/gherkin": "38.0.0",
     "@cucumber/messages": "32.0.1",
+    "@modelcontextprotocol/sdk": "^1.26.0",
     "@xmldom/xmldom": "0.9.8",
     "acorn": "8.15.0",
     "ai": "^6.0.43",

package/typings/index.d.ts

@@ -745,3 +745,22 @@ declare module 'codeceptjs/effects' {
   export const retryTo: RetryTo
   export const hopeThat: HopeThat
 }
+
+declare module 'codeceptjs/steps' {
+  const step: {
+    opts(opts: CodeceptJS.StepOptions): CodeceptJS.StepConfig;
+    timeout(timeout: number): CodeceptJS.StepConfig;
+    retry(retry: number): CodeceptJS.StepConfig;
+    stepOpts(opts: CodeceptJS.StepOptions): CodeceptJS.StepConfig;
+    stepTimeout(timeout: number): CodeceptJS.StepConfig;
+    stepRetry(retry: number): CodeceptJS.StepConfig;
+    section(name: string): any;
+    endSection(): any;
+    Section(name: string): any;
+    EndSection(): any;
+    Given(): any;
+    When(): any;
+    Then(): any;
+  }
+  export default step
+}

package/lib/listener/enhancedGlobalRetry.js

@@ -1,110 +0,0 @@
-import event from '../event.js'
-import output from '../output.js'
-import Config from '../config.js'
-import { isNotSet } from '../utils.js'
-
-const hooks = ['Before', 'After', 'BeforeSuite', 'AfterSuite']
-
-/**
- * Priority levels for retry mechanisms (higher number = higher priority)
- * This ensures consistent behavior when multiple retry mechanisms are active
- */
-const RETRY_PRIORITIES = {
-  MANUAL_STEP: 100, // I.retry() or step.retry() - highest priority
-  STEP_PLUGIN: 50, // retryFailedStep plugin
-  SCENARIO_CONFIG: 30, // Global scenario retry config
-  FEATURE_CONFIG: 20, // Global feature retry config
-  HOOK_CONFIG: 10, // Hook retry config - lowest priority
-}
-
-/**
- * Enhanced global retry mechanism that coordinates with other retry types
- */
-export default function () {
-  event.dispatcher.on(event.suite.before, suite => {
-    let retryConfig = Config.get('retry')
-    if (!retryConfig) return
-
-    if (Number.isInteger(+retryConfig)) {
-      // is number - apply as feature-level retry
-      const retryNum = +retryConfig
-      output.log(`[Global Retry] Feature retries: ${retryNum}`)
-
-      // Only set if not already set by higher priority mechanism
-      if (isNotSet(suite.retries())) {
-        suite.retries(retryNum)
-        suite.opts.retryPriority = RETRY_PRIORITIES.FEATURE_CONFIG
-      }
-      return
-    }
-
-    if (!Array.isArray(retryConfig)) {
-      retryConfig = [retryConfig]
-    }
-
-    for (const config of retryConfig) {
-      if (config.grep) {
-        if (!suite.title.includes(config.grep)) continue
-      }
-
-      // Handle hook retries with priority awareness
-      hooks
-        .filter(hook => !!config[hook])
-        .forEach(hook => {
-          const retryKey = `retry${hook}`
-          if (isNotSet(suite.opts[retryKey])) {
-            suite.opts[retryKey] = config[hook]
-            suite.opts[`${retryKey}Priority`] = RETRY_PRIORITIES.HOOK_CONFIG
-          }
-        })
-
-      // Handle feature-level retries
-      if (config.Feature) {
-        if (isNotSet(suite.retries()) || (suite.opts.retryPriority || 0) <= RETRY_PRIORITIES.FEATURE_CONFIG) {
-          suite.retries(config.Feature)
-          suite.opts.retryPriority = RETRY_PRIORITIES.FEATURE_CONFIG
-          output.log(`[Global Retry] Feature retries: ${config.Feature}`)
-        }
-      }
-    }
-  })
-
-  event.dispatcher.on(event.test.before, test => {
-    let retryConfig = Config.get('retry')
-    if (!retryConfig) return
-
-    if (Number.isInteger(+retryConfig)) {
-      // Only set if not already set by higher priority mechanism
-      if (test.retries() === -1) {
-        test.retries(retryConfig)
-        test.opts.retryPriority = RETRY_PRIORITIES.SCENARIO_CONFIG
-        output.log(`[Global Retry] Scenario retries: ${retryConfig}`)
-      }
-      return
-    }
-
-    if (!Array.isArray(retryConfig)) {
-      retryConfig = [retryConfig]
-    }
-
-    retryConfig = retryConfig.filter(config => !!config.Scenario)
-
-    for (const config of retryConfig) {
-      if (config.grep) {
-        if (!test.fullTitle().includes(config.grep)) continue
-      }
-
-      if (config.Scenario) {
-        // Respect priority system
-        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(`[Global Retry] Scenario retries: ${config.Scenario}`)
-        }
-      }
-    }
-  })
-}
-
-// Export priority constants for use by other retry mechanisms
-export { RETRY_PRIORITIES }

package/lib/plugin/enhancedRetryFailedStep.js

@@ -1,99 +0,0 @@
-import event from '../event.js'
-import recorder from '../recorder.js'
-import store from '../store.js'
-import output from '../output.js'
-import { RETRY_PRIORITIES } from '../retryCoordinator.js'
-
-const defaultConfig = {
-  retries: 3,
-  defaultIgnoredSteps: ['amOnPage', 'wait*', 'send*', 'execute*', 'run*', 'have*'],
-  factor: 1.5,
-  ignoredSteps: [],
-}
-
-/**
- * Enhanced retryFailedStep plugin that coordinates with other retry mechanisms
- *
- * This plugin provides step-level retries and coordinates with global retry settings
- * to avoid conflicts and provide predictable behavior.
- */
-export default config => {
-  config = Object.assign({}, defaultConfig, config)
-  config.ignoredSteps = config.ignoredSteps.concat(config.defaultIgnoredSteps)
-  const customWhen = config.when
-
-  let enableRetry = false
-
-  const when = err => {
-    if (!enableRetry) return false
-    if (store.debugMode) return false
-    if (!store.autoRetries) return false
-    if (customWhen) return customWhen(err)
-    return true
-  }
-  config.when = when
-
-  event.dispatcher.on(event.step.started, step => {
-    // if a step is ignored - return
-    for (const ignored of config.ignoredSteps) {
-      if (step.name === ignored) return
-      if (ignored instanceof RegExp) {
-        if (step.name.match(ignored)) return
-      } else if (ignored.indexOf('*') && step.name.startsWith(ignored.slice(0, -1))) return
-    }
-    enableRetry = true // enable retry for a step
-  })
-
-  event.dispatcher.on(event.step.finished, () => {
-    enableRetry = false
-  })
-
-  event.dispatcher.on(event.test.before, test => {
-    // pass disableRetryFailedStep is a preferred way to disable retries
-    // test.disableRetryFailedStep is used for backward compatibility
-    if (test.opts.disableRetryFailedStep || test.disableRetryFailedStep) {
-      store.autoRetries = false
-      output.log(`[Step Retry] Disabled for test: ${test.title}`)
-      return // disable retry when a test is not active
-    }
-
-    // Check if step retries should be disabled due to higher priority scenario retries
-    const scenarioRetries = test.retries()
-    const stepRetryPriority = RETRY_PRIORITIES.STEP_PLUGIN
-    const scenarioPriority = test.opts.retryPriority || 0
-
-    if (scenarioRetries > 0 && config.deferToScenarioRetries !== false) {
-      // Scenario retries are configured with higher or equal priority
-      // Option 1: Disable step retries (conservative approach)
-      store.autoRetries = false
-      output.log(`[Step Retry] Deferred to scenario retries (${scenarioRetries} retries)`)
-      return
-
-      // Option 2: Reduce step retries to avoid excessive total retries
-      // const reducedStepRetries = Math.max(1, Math.floor(config.retries / scenarioRetries))
-      // config.retries = reducedStepRetries
-      // output.log(`[Step Retry] Reduced to ${reducedStepRetries} retries due to scenario retries (${scenarioRetries})`)
-    }
-
-    // this option is used to set the retries inside _before() block of helpers
-    store.autoRetries = true
-    test.opts.conditionalRetries = config.retries
-    test.opts.stepRetryPriority = stepRetryPriority
-
-    recorder.retry(config)
-
-    output.log(`[Step Retry] Enabled with ${config.retries} retries for test: ${test.title}`)
-  })
-
-  // Add coordination info for debugging
-  event.dispatcher.on(event.test.finished, test => {
-    if (test.state === 'passed' && test.opts.conditionalRetries && store.autoRetries) {
-      const stepRetries = test.opts.conditionalRetries || 0
-      const scenarioRetries = test.retries() || 0
-
-      if (stepRetries > 0 && scenarioRetries > 0) {
-        output.log(`[Retry Coordination] Test used both step retries (${stepRetries}) and scenario retries (${scenarioRetries})`)
-      }
-    }
-  })
-}