codeceptjs 4.0.0-beta.7.esm-aria → 4.0.0-beta.9.esm-aria

package/lib/plugin/retryFailedStep.js

@@ -121,6 +121,7 @@ export default function (config) {
   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

package/lib/plugin/stepByStepReport.js

@@ -2,7 +2,7 @@ import colors from 'chalk'
 import crypto from 'crypto'
 import figures from 'figures'
 import fs from 'fs'
-import mkdirp from 'mkdirp'
+import { mkdirp } from 'mkdirp'
 import path from 'path'
 import cheerio from 'cheerio'
 

package/lib/recorder.js

@@ -12,6 +12,7 @@ let running = false
 let errFn
 let queueId = 0
 let sessionId = null
+let sessionStack = [] // Stack to support nested sessions
 let asyncErr = null
 let ignoredErrs = []
 
@@ -90,6 +91,7 @@ export default {
     if (promise && running) this.catch()
     queueId++
     sessionId = null
+    sessionStack = [] // Clear the session stack
     asyncErr = null
     output.log(`${currentQueue()} Starting recording promises`)
     promise = Promise.resolve()
@@ -124,8 +126,13 @@ export default {
      */
     start(name) {
       if (sessionId) {
-        debug(`${currentQueue()}Session already started as ${sessionId}`)
-        this.restore(sessionId)
+        debug(`${currentQueue()}Session already started as ${sessionId}, nesting session ${name}`)
+        // Push current session to stack instead of restoring it
+        sessionStack.push({
+          id: sessionId,
+          promise: promise,
+          running: this.running,
+        })
       }
       debug(`${currentQueue()}Starting <${name}> session`)
       tasks.push('--->')
@@ -143,9 +150,18 @@ export default {
       tasks.push('<---')
       debug(`${currentQueue()}Finalize <${name}> session`)
       this.running = false
-      sessionId = null
       this.catch(errFn)
       promise = promise.then(() => oldPromises.pop())
+
+      // Restore parent session from stack if available
+      if (sessionStack.length > 0) {
+        const parentSession = sessionStack.pop()
+        sessionId = parentSession.id
+        this.running = parentSession.running
+        debug(`${currentQueue()}Restored parent session <${sessionId}>`)
+      } else {
+        sessionId = null
+      }
     },
 
     /**
@@ -398,6 +414,15 @@ export default {
   toString() {
     return `Queue: ${currentQueue()}\n\nTasks: ${this.scheduled()}`
   },
+
+  /**
+   * Get current session ID
+   * @return {string|null}
+   * @inner
+   */
+  getCurrentSessionId() {
+    return sessionId
+  },
 }
 
 function getTimeoutPromise(timeoutMs, taskName) {

package/lib/result.js

@@ -3,22 +3,21 @@ import path from 'path'
 import { serializeTest } from './mocha/test.js'
 
 /**
- * Result of the test run
- *
- * @typedef {Object} Stats
- * @property {number} passes
- * @property {number} failures
- * @property {number} tests
- * @property {number} pending
- * @property {number} failedHooks
- * @property {Date} start
- * @property {Date} end
- * @property {number} duration
+ * @typedef {Object} Stats Statistics for a test result.
+ * @property {number} passes Number of passed tests.
+ * @property {number} failures Number of failed tests.
+ * @property {number} tests Total number of tests.
+ * @property {number} pending Number of pending tests.
+ * @property {number} failedHooks Number of failed hooks.
+ * @property {Date} start Start time of the test run.
+ * @property {Date} end End time of the test run.
+ * @property {number} duration Duration of the test run, in milliseconds.
+ */
+
+/**
+ * Result of a test run. Will be emitted for example in "event.all.result" events.
  */
 class Result {
-  /**
-   * Create Result of the test run
-   */
   constructor() {
     this._startTime = new Date()
     this._endTime = null
@@ -27,6 +26,9 @@ class Result {
     this.start()
   }
 
+  /**
+   * Resets all collected stats, tests, and failure reports.
+   */
   reset() {
     this._stats = {
       passes: 0,
@@ -39,43 +41,85 @@ class Result {
       duration: 0,
     }
 
-    /** @type {CodeceptJS.Test[]} */
+    /**
+     * @type {CodeceptJS.Test[]}
+     * @private
+     */
     this._tests = []
 
-    /** @type {String[]} */
+    /**
+     * @type {string[][]}
+     * @private
+     */
     this._failures = []
   }
 
+  /**
+   * Sets the start time to the current time.
+   */
   start() {
     this._startTime = new Date()
   }
 
+  /**
+   * Sets the end time to the current time.
+   */
   finish() {
     this._endTime = new Date()
   }
 
+  /**
+   * Whether this result contains any failed tests.
+   *
+   * @type {boolean}
+   * @readonly
+   */
   get hasFailed() {
     return this._stats.failures > 0
   }
 
+  /**
+   * All collected tests.
+   *
+   * @type {CodeceptJS.Test[]}
+   * @readonly
+   */
   get tests() {
     return this._tests
   }
 
+  /**
+   * The failure reports (array of strings per failed test).
+   *
+   * @type {string[][]}
+   * @readonly
+   */
   get failures() {
     return this._failures.filter(f => f && (!Array.isArray(f) || f.length > 0))
   }
 
+  /**
+   * The test statistics.
+   *
+   * @type {Stats}
+   * @readonly
+   */
   get stats() {
     return this._stats
   }
 
+  /**
+   * The start time of the test run.
+   *
+   * @type {Date}
+   * @readonly
+   */
   get startTime() {
     return this._startTime
   }
 
   /**
-   * Add test to result
+   * Adds a test to this result.
    *
    * @param {CodeceptJS.Test} test
    */
@@ -90,34 +134,67 @@ class Result {
   }
 
   /**
-   * Add failures to result
+   * Adds failure reports to this result.
    *
-   * @param {String[]} newFailures
+   * @param {string[][]} newFailures
    */
   addFailures(newFailures) {
     this._failures.push(...newFailures)
   }
 
+  /**
+   * Whether this result contains any failed tests.
+   *
+   * @type {boolean}
+   * @readonly
+   */
   get hasFailures() {
     return this.stats.failures > 0
   }
 
+  /**
+   * The duration of the test run, in milliseconds.
+   *
+   * @type {number}
+   * @readonly
+   */
   get duration() {
     return this._endTime ? +this._endTime - +this._startTime : 0
   }
 
+  /**
+   * All failed tests.
+   *
+   * @type {CodeceptJS.Test[]}
+   * readonly
+   */
   get failedTests() {
     return this._tests.filter(test => test.state === 'failed')
   }
 
+  /**
+   * All passed tests.
+   *
+   * @type {CodeceptJS.Test[]}
+   * @readonly
+   */
   get passedTests() {
     return this._tests.filter(test => test.state === 'passed')
   }
 
+  /**
+   * All skipped tests.
+   *
+   * @type {CodeceptJS.Test[]}
+   * @readonly
+   */
   get skippedTests() {
     return this._tests.filter(test => test.state === 'skipped' || test.state === 'pending')
   }
 
+  /**
+   * @returns {object} The JSON representation of this result.
+   */
   simplify() {
     return {
       hasFailed: this.hasFailed,
@@ -129,9 +206,9 @@ class Result {
   }
 
   /**
-   * Save result to json file
+   * Saves this result to a JSON file.
    *
-   * @param {string} fileName
+   * @param {string} [fileName] Path to the JSON file, relative to `output_dir`. Defaults to "result.json".
    */
   save(fileName) {
     if (!fileName) fileName = 'result.json'
@@ -139,9 +216,9 @@ class Result {
   }
 
   /**
-   * Add stats to result
+   * Adds stats to this result.
    *
-   * @param {object} newStats
+   * @param {Partial<Stats>} [newStats]
    */
   addStats(newStats = {}) {
     this._stats.passes += newStats.passes || 0

package/lib/retryCoordinator.js

@@ -0,0 +1,207 @@
+import output from './output.js'
+
+/**
+ * Retry Coordinator - Central coordination for all retry mechanisms
+ *
+ * This module provides:
+ * 1. Priority-based retry coordination
+ * 2. Unified configuration validation
+ * 3. Consolidated retry reporting
+ * 4. Conflict detection and resolution
+ */
+
+/**
+ * Priority levels for retry mechanisms (higher number = higher priority)
+ */
+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
+}
+
+/**
+ * Retry mechanism types
+ */
+const RETRY_TYPES = {
+  MANUAL_STEP: 'manual-step',
+  STEP_PLUGIN: 'step-plugin',
+  SCENARIO: 'scenario',
+  FEATURE: 'feature',
+  HOOK: 'hook',
+}
+
+/**
+ * Global retry coordination state
+ */
+let retryState = {
+  activeTest: null,
+  activeSuite: null,
+  retryHistory: [],
+  conflicts: [],
+}
+
+/**
+ * Registers a retry mechanism for coordination
+ * @param {string} type - Type of retry mechanism
+ * @param {Object} config - Retry configuration
+ * @param {Object} target - Target object (test, suite, etc.)
+ * @param {number} priority - Priority level
+ */
+function registerRetry(type, config, target, priority = 0) {
+  const retryInfo = {
+    type,
+    config,
+    target,
+    priority,
+    timestamp: Date.now(),
+  }
+
+  // Detect conflicts
+  const existingRetries = retryState.retryHistory.filter(r => r.target === target && r.type !== type && r.priority !== priority)
+
+  if (existingRetries.length > 0) {
+    const conflict = {
+      newRetry: retryInfo,
+      existingRetries: existingRetries,
+      resolved: false,
+    }
+    retryState.conflicts.push(conflict)
+    handleRetryConflict(conflict)
+  }
+
+  retryState.retryHistory.push(retryInfo)
+
+  output.log(`[Retry Coordinator] Registered ${type} retry (priority: ${priority})`)
+}
+
+/**
+ * Handles conflicts between retry mechanisms
+ * @param {Object} conflict - Conflict information
+ */
+function handleRetryConflict(conflict) {
+  const { newRetry, existingRetries } = conflict
+
+  // Find highest priority retry
+  const allRetries = [newRetry, ...existingRetries]
+  const highestPriority = Math.max(...allRetries.map(r => r.priority))
+  const winningRetry = allRetries.find(r => r.priority === highestPriority)
+
+  // Log the conflict resolution
+  output.log(`[Retry Coordinator] Conflict detected:`)
+  allRetries.forEach(retry => {
+    const status = retry === winningRetry ? 'ACTIVE' : 'DEFERRED'
+    output.log(`  - ${retry.type} (priority: ${retry.priority}) [${status}]`)
+  })
+
+  conflict.resolved = true
+  conflict.winner = winningRetry
+}
+
+/**
+ * Gets the effective retry configuration for a target
+ * @param {Object} target - Target object (test, suite, etc.)
+ * @returns {Object} Effective retry configuration
+ */
+function getEffectiveRetryConfig(target) {
+  const targetRetries = retryState.retryHistory.filter(r => r.target === target)
+
+  if (targetRetries.length === 0) {
+    return { type: 'none', retries: 0 }
+  }
+
+  // Find highest priority retry
+  const highestPriority = Math.max(...targetRetries.map(r => r.priority))
+  const effectiveRetry = targetRetries.find(r => r.priority === highestPriority)
+
+  return {
+    type: effectiveRetry.type,
+    retries: effectiveRetry.config.retries || effectiveRetry.config,
+    config: effectiveRetry.config,
+  }
+}
+
+/**
+ * Generates a retry summary report
+ * @returns {Object} Retry summary
+ */
+function generateRetrySummary() {
+  const summary = {
+    totalRetryMechanisms: retryState.retryHistory.length,
+    conflicts: retryState.conflicts.length,
+    byType: {},
+    recommendations: [],
+  }
+
+  // Count by type
+  retryState.retryHistory.forEach(retry => {
+    summary.byType[retry.type] = (summary.byType[retry.type] || 0) + 1
+  })
+
+  // Generate recommendations
+  if (summary.conflicts > 0) {
+    summary.recommendations.push('Consider consolidating retry configurations to avoid conflicts')
+  }
+
+  if (summary.byType[RETRY_TYPES.STEP_PLUGIN] && summary.byType[RETRY_TYPES.SCENARIO]) {
+    summary.recommendations.push('Step-level and scenario-level retries are both active - consider using only one approach')
+  }
+
+  return summary
+}
+
+/**
+ * Resets the retry coordination state (useful for testing)
+ */
+function reset() {
+  retryState = {
+    activeTest: null,
+    activeSuite: null,
+    retryHistory: [],
+    conflicts: [],
+  }
+}
+
+/**
+ * Validates retry configuration for common issues
+ * @param {Object} config - Configuration object
+ * @returns {Array} Array of validation warnings
+ */
+function validateConfig(config) {
+  const warnings = []
+
+  if (!config) return warnings
+
+  // Check for potential configuration conflicts
+  if (config.retry && config.plugins && config.plugins.retryFailedStep) {
+    const globalRetries = typeof config.retry === 'number' ? config.retry : config.retry.Scenario || config.retry.Feature
+    const stepRetries = config.plugins.retryFailedStep.retries || 3
+
+    if (globalRetries && stepRetries) {
+      warnings.push(`Both global retries (${globalRetries}) and step retries (${stepRetries}) are configured - total executions could be ${globalRetries * (stepRetries + 1)}`)
+    }
+  }
+
+  // Check for excessive retry counts
+  if (config.retry) {
+    const retryValues = typeof config.retry === 'number' ? [config.retry] : Object.values(config.retry)
+    const maxRetries = Math.max(...retryValues.filter(v => typeof v === 'number'))
+
+    if (maxRetries > 5) {
+      warnings.push(`High retry count detected (${maxRetries}) - consider investigating test stability instead`)
+    }
+  }
+
+  return warnings
+}
+
+export {
+  RETRY_PRIORITIES,
+  RETRY_TYPES,
+  registerRetry,
+  getEffectiveRetryConfig,
+  generateRetrySummary,
+  validateConfig,
+  reset,
+}

package/lib/step/base.js

@@ -225,7 +225,7 @@ class Step {
     processingStep = this
 
     while (processingStep.metaStep) {
-      if (processingStep.metaStep.actor?.match(/^(Given|When|Then|And)/)) {
+      if (processingStep.metaStep.actor?.match(/^(Given|When|Then|And|But)/)) {
         hasBDD = true
         break
       } else {

package/lib/step/comment.js

@@ -1,4 +1,4 @@
-const FuncStep = require('./func')
+import FuncStep from './func.js'
 
 class CommentStep extends FuncStep {
   constructor(name, comment) {
@@ -7,4 +7,4 @@ class CommentStep extends FuncStep {
   }
 }
 
-module.exports = CommentStep
+export default CommentStep

package/lib/step/meta.js

@@ -15,7 +15,7 @@ class MetaStep extends Step {
 
   /** @return {boolean} */
   isBDD() {
-    if (this.actor && this.actor.match && this.actor.match(/^(Given|When|Then|And)/)) {
+    if (this.actor && this.actor.match && this.actor.match(/^(Given|When|Then|And|But)/)) {
       return true
     }
     return false

package/lib/template/heal.js

@@ -1,4 +1,4 @@
-const { heal, ai } = require('codeceptjs')
+import { heal, ai } from 'codeceptjs'
 
 heal.addRecipe('ai', {
   priority: 10,

package/lib/template/prompts/generatePageObject.js

@@ -0,0 +1,31 @@
+export default (html, extraPrompt = '', rootLocator = null) => [
+  {
+    role: 'user',
+    content: `As a test automation engineer I am creating a Page Object for a web application using CodeceptJS.
+      Here is an sample page object:
+
+const { I } = inject();
+
+export default {
+
+  // setting locators
+  element1: '#selector',
+  element2: '.selector',
+  element3: locate().withText('text'),
+
+  // setting methods
+  doSomethingOnPage(params) {
+    // ...
+  },
+}
+
+      I want to generate a Page Object for the page I provide.
+      Write JavaScript code in similar manner to list all locators on the page.
+      Use locators in order of preference: by text (use locate().withText()), label, CSS, XPath.
+      Avoid TailwindCSS, Bootstrap or React style formatting classes in locators.
+      Add methods to interact with page when needed.
+      ${extraPrompt}
+      ${rootLocator ? `All provided elements are inside '${rootLocator}'. Declare it as root variable and for every locator use locate(...).inside(root)` : ''}
+      Add only locators from this HTML: \n\n${html}`,
+  },
+]

package/lib/template/prompts/healStep.js

@@ -0,0 +1,13 @@
+export default (html, { step, error, prevSteps }) => {
+  return [
+    {
+      role: 'user',
+      content: `As a test automation engineer I am testing web application using CodeceptJS.
+      I want to heal a test that fails. Here is the list of executed steps: ${prevSteps.map(s => s.toString()).join(', ')}
+      Propose how to adjust ${step.toCode()} step to fix the test.
+      Use locators in order of preference: semantic locator by text, CSS, XPath. Use codeblocks marked with \`\`\`
+      Here is the error message: ${error.message}
+      Here is HTML code of a page where the failure has happened: \n\n${html}`,
+    },
+  ]
+}

package/lib/template/prompts/writeStep.js

@@ -0,0 +1,9 @@
+export default (html, input) => [
+  {
+    role: 'user',
+    content: `I am test engineer writing test in CodeceptJS
+      I have opened web page and I want to use CodeceptJS to ${input} on this page
+      Provide me valid CodeceptJS code to accomplish it
+      Use only locators from this HTML: \n\n${html}`,
+  },
+]