codeceptjs 3.7.0-beta.1 → 3.7.0-beta.11

package/lib/container.js

@@ -1,5 +1,6 @@
 const glob = require('glob')
 const path = require('path')
+const debug = require('debug')('codeceptjs:container')
 const { MetaStep } = require('./step')
 const { methodsOfObject, fileExists, isFunction, isAsyncFunction, installedLocally } = require('./utils')
 const Translation = require('./translation')
@@ -8,6 +9,7 @@ const recorder = require('./recorder')
 const event = require('./event')
 const WorkerStorage = require('./workerStorage')
 const store = require('./store')
+const Result = require('./result')
 const ai = require('./ai')
 
 let asyncHelperPromise
@@ -24,12 +26,21 @@ let container = {
    */
   mocha: {},
   translation: {},
+  /** @type {Result | null} */
+  result: null,
 }
 
 /**
  * Dependency Injection Container
  */
 class Container {
+  /**
+   * Get the standard acting helpers of CodeceptJS Container
+   *
+   */
+  static get STANDARD_ACTING_HELPERS() {
+    return ['Playwright', 'WebDriver', 'Puppeteer', 'Appium', 'TestCafe']
+  }
   /**
    * Create container with all required helpers and support objects
    *
@@ -38,6 +49,7 @@ class Container {
    * @param {*} opts
    */
   static create(config, opts) {
+    debug('creating container')
     asyncHelperPromise = Promise.resolve()
 
     // dynamically create mocha instance
@@ -52,6 +64,7 @@ class Container {
     container.translation = loadTranslation(config.translation || null, config.vocabularies || [])
     container.proxySupport = createSupportObjects(config.include || {})
     container.plugins = createPlugins(config.plugins || {}, opts)
+    container.result = new Result()
 
     createActor(config.include?.I)
 
@@ -125,6 +138,18 @@ class Container {
     return container.mocha
   }
 
+  /**
+   * Get result
+   *
+   * @returns {Result}
+   */
+  static result() {
+    if (!container.result) {
+      container.result = new Result()
+    }
+    return container.result
+  }
+
   /**
    * Append new services to container
    *
@@ -134,6 +159,7 @@ class Container {
   static append(newContainer) {
     const deepMerge = require('./utils').deepMerge
     container = deepMerge(container, newContainer)
+    debug('appended', JSON.stringify(newContainer).slice(0, 300))
   }
 
   /**
@@ -150,6 +176,7 @@ class Container {
     container.plugins = newPlugins || {}
     asyncHelperPromise = Promise.resolve()
     store.actor = null
+    debug('container cleared')
   }
 
   /**
@@ -216,6 +243,8 @@ function createHelpers(config) {
               throw new Error(`Helper class from module '${helperName}' is not a class. Use CJS async module syntax.`)
             }
 
+            debug(`helper ${helperName} async initialized`)
+
             helpers[helperName] = new ResolvedHelperClass(config[helperName])
           })
 
@@ -225,6 +254,7 @@ function createHelpers(config) {
       checkHelperRequirements(HelperClass)
 
       helpers[helperName] = new HelperClass(config[helperName])
+      debug(`helper ${helperName} initialized`)
     } catch (err) {
       throw new Error(`Could not load helper ${helperName} (${err.message})`)
     }
@@ -322,6 +352,7 @@ function createSupportObjects(config) {
               if (container.support[name]._init) {
                 container.support[name]._init()
               }
+              debug(`support object ${name} initialized`)
             } catch (err) {
               throw new Error(`Initialization failed for ${name}: ${container.support[name]}\n${err.message}\n${err.stack}`)
             }
@@ -334,6 +365,7 @@ function createSupportObjects(config) {
             const ms = new MetaStep(name, prop)
             ms.setContext(currentObject)
             if (isAsyncFunction(currentValue)) currentValue = asyncWrapper(currentValue)
+            debug(`metastep is created for ${name}.${prop.toString()}()`)
             return ms.run.bind(ms, currentValue)
           }
 

package/lib/effects.js

@@ -0,0 +1,218 @@
+const recorder = require('./recorder')
+const { debug } = require('./output')
+const store = require('./store')
+const event = require('./event')
+
+/**
+ * A utility function for CodeceptJS tests that acts as a soft assertion.
+ * Executes a callback within a recorded session, ensuring errors are handled gracefully without failing the test immediately.
+ *
+ * @async
+ * @function hopeThat
+ * @param {Function} callback - The callback function containing the logic to validate.
+ *                              This function should perform the desired assertion or condition check.
+ * @returns {Promise<boolean|any>} A promise resolving to `true` if the assertion or condition was successful,
+ *                             or `false` if an error occurred.
+ *
+ * @description
+ * - Designed for use in CodeceptJS tests as a "soft assertion."
+ *   Unlike standard assertions, it does not stop the test execution on failure.
+ * - Starts a new recorder session named 'hopeThat' and manages state restoration.
+ * - Logs errors and attaches them as notes to the test, enabling post-test reporting of soft assertion failures.
+ * - Resets the `store.hopeThat` flag after the execution, ensuring clean state for subsequent operations.
+ *
+ * @example
+ * const { hopeThat } = require('codeceptjs/effects')
+ * await hopeThat(() => {
+ *   I.see('Welcome'); // Perform a soft assertion
+ * });
+ *
+ * @throws Will handle errors that occur during the callback execution. Errors are logged and attached as notes to the test.
+ */
+async function hopeThat(callback) {
+  if (store.dryRun) return
+  const sessionName = 'hopeThat'
+
+  let result = false
+  return recorder.add(
+    'hopeThat',
+    () => {
+      recorder.session.start(sessionName)
+      store.hopeThat = true
+      callback()
+      recorder.add(() => {
+        result = true
+        recorder.session.restore(sessionName)
+        return result
+      })
+      recorder.session.catch(err => {
+        result = false
+        const msg = err.inspect ? err.inspect() : err.toString()
+        debug(`Unsuccessful assertion > ${msg}`)
+        event.dispatcher.once(event.test.finished, test => {
+          test.notes.push({ type: 'conditionalError', text: msg })
+        })
+        recorder.session.restore(sessionName)
+        return result
+      })
+      return recorder.add(
+        'result',
+        () => {
+          store.hopeThat = undefined
+          return result
+        },
+        true,
+        false,
+      )
+    },
+    false,
+    false,
+  )
+}
+
+/**
+ * A CodeceptJS utility function to retry a step or callback multiple times with a specified polling interval.
+ *
+ * @async
+ * @function retryTo
+ * @param {Function} callback - The function to execute, which will be retried upon failure.
+ *                               Receives the current retry count as an argument.
+ * @param {number} maxTries - The maximum number of attempts to retry the callback.
+ * @param {number} [pollInterval=200] - The delay (in milliseconds) between retry attempts.
+ * @returns {Promise<void|any>} A promise that resolves when the callback executes successfully, or rejects after reaching the maximum retries.
+ *
+ * @description
+ * - This function is designed for use in CodeceptJS tests to handle intermittent or flaky test steps.
+ * - Starts a new recorder session for each retry attempt, ensuring proper state management and error handling.
+ * - Logs errors and retries the callback until it either succeeds or the maximum number of attempts is reached.
+ * - Restores the session state after each attempt, whether successful or not.
+ *
+ * @example
+ * const { hopeThat } = require('codeceptjs/effects')
+ * await retryTo((tries) => {
+ *   if (tries < 3) {
+ *     I.see('Non-existent element'); // Simulates a failure
+ *   } else {
+ *     I.see('Welcome'); // Succeeds on the 3rd attempt
+ *   }
+ * }, 5, 300); // Retry up to 5 times, with a 300ms interval
+ *
+ * @throws Will reject with the last error encountered if the maximum retries are exceeded.
+ */
+async function retryTo(callback, maxTries, pollInterval = 200) {
+  const sessionName = 'retryTo'
+
+  return new Promise((done, reject) => {
+    let tries = 1
+
+    function handleRetryException(err) {
+      recorder.throw(err)
+      reject(err)
+    }
+
+    const tryBlock = async () => {
+      tries++
+      recorder.session.start(`${sessionName} ${tries}`)
+      try {
+        await callback(tries)
+      } catch (err) {
+        handleRetryException(err)
+      }
+
+      // Call done if no errors
+      recorder.add(() => {
+        recorder.session.restore(`${sessionName} ${tries}`)
+        done(null)
+      })
+
+      // Catch errors and retry
+      recorder.session.catch(err => {
+        recorder.session.restore(`${sessionName} ${tries}`)
+        if (tries <= maxTries) {
+          debug(`Error ${err}... Retrying`)
+          recorder.add(`${sessionName} ${tries}`, () => setTimeout(tryBlock, pollInterval))
+        } else {
+          // if maxTries reached
+          handleRetryException(err)
+        }
+      })
+    }
+
+    recorder.add(sessionName, tryBlock).catch(err => {
+      console.error('An error occurred:', err)
+      done(null)
+    })
+  })
+}
+
+/**
+ * A CodeceptJS utility function to attempt a step or callback without failing the test.
+ * If the step fails, the test continues execution without interruption, and the result is logged.
+ *
+ * @async
+ * @function tryTo
+ * @param {Function} callback - The function to execute, which may succeed or fail.
+ *                               This function contains the logic to be attempted.
+ * @returns {Promise<boolean|any>} A promise resolving to `true` if the step succeeds, or `false` if it fails.
+ *
+ * @description
+ * - Useful for scenarios where certain steps are optional or their failure should not interrupt the test flow.
+ * - Starts a new recorder session named 'tryTo' for isolation and error handling.
+ * - Captures errors during execution and logs them for debugging purposes.
+ * - Ensures the `store.tryTo` flag is reset after execution to maintain a clean state.
+ *
+ * @example
+ * const { tryTo } = require('codeceptjs/effects')
+ * const wasSuccessful = await tryTo(() => {
+ *   I.see('Welcome'); // Attempt to find an element on the page
+ * });
+ *
+ * if (!wasSuccessful) {
+ *   I.say('Optional step failed, but test continues.');
+ * }
+ *
+ * @throws Will handle errors internally, logging them and returning `false` as the result.
+ */
+async function tryTo(callback) {
+  if (store.dryRun) return
+  const sessionName = 'tryTo'
+
+  let result = false
+  return recorder.add(
+    sessionName,
+    () => {
+      recorder.session.start(sessionName)
+      store.tryTo = true
+      callback()
+      recorder.add(() => {
+        result = true
+        recorder.session.restore(sessionName)
+        return result
+      })
+      recorder.session.catch(err => {
+        result = false
+        const msg = err.inspect ? err.inspect() : err.toString()
+        debug(`Unsuccessful try > ${msg}`)
+        recorder.session.restore(sessionName)
+        return result
+      })
+      return recorder.add(
+        'result',
+        () => {
+          store.tryTo = undefined
+          return result
+        },
+        true,
+        false,
+      )
+    },
+    false,
+    false,
+  )
+}
+
+module.exports = {
+  hopeThat,
+  retryTo,
+  tryTo,
+}

package/lib/els.js

@@ -1,115 +1,124 @@
-const output = require('./output');
-const store = require('./store');
-const recorder = require('./recorder');
-const container = require('./container');
-const event = require('./event');
-const Step = require('./step');
-const { truth } = require('./assert/truth');
-const { isAsyncFunction, humanizeFunction } = require('./utils');
+const output = require('./output')
+const store = require('./store')
+const container = require('./container')
+const StepConfig = require('./step/config')
+const recordStep = require('./step/record')
+const FuncStep = require('./step/func')
+const { truth } = require('./assert/truth')
+const { isAsyncFunction, humanizeFunction } = require('./utils')
 
 function element(purpose, locator, fn) {
-  if (!fn) {
-    fn = locator;
-    locator = purpose;
-    purpose = 'first element';
+  let stepConfig
+  if (arguments[arguments.length - 1] instanceof StepConfig) {
+    stepConfig = arguments[arguments.length - 1]
   }
 
-  const step = prepareStep(purpose, locator, fn);
-  if (!step) return;
+  if (!fn || fn === stepConfig) {
+    fn = locator
+    locator = purpose
+    purpose = 'first element'
+  }
 
-  return executeStep(step, async () => {
-    const els = await step.helper._locate(locator);
-    output.debug(`Found ${els.length} elements, using first element`);
+  const step = prepareStep(purpose, locator, fn)
+  if (!step) return
 
-    return fn(els[0]);
-  });
+  return executeStep(
+    step,
+    async () => {
+      const els = await step.helper._locate(locator)
+      output.debug(`Found ${els.length} elements, using first element`)
+
+      return fn(els[0])
+    },
+    stepConfig,
+  )
 }
 
 function eachElement(purpose, locator, fn) {
   if (!fn) {
-    fn = locator;
-    locator = purpose;
-    purpose = 'for each element';
+    fn = locator
+    locator = purpose
+    purpose = 'for each element'
   }
 
-  const step = prepareStep(purpose, locator, fn);
-  if (!step) return;
+  const step = prepareStep(purpose, locator, fn)
+  if (!step) return
 
   return executeStep(step, async () => {
-    const els = await step.helper._locate(locator);
-    output.debug(`Found ${els.length} elements for each elements to iterate`);
+    const els = await step.helper._locate(locator)
+    output.debug(`Found ${els.length} elements for each elements to iterate`)
 
-    const errs = [];
-    let i = 0;
+    const errs = []
+    let i = 0
     for (const el of els) {
       try {
-        await fn(el, i);
+        await fn(el, i)
       } catch (err) {
-        output.error(`eachElement: failed operation on element #${i} ${el}`);
-        errs.push(err);
+        output.error(`eachElement: failed operation on element #${i} ${el}`)
+        errs.push(err)
       }
-      i++;
+      i++
     }
 
     if (errs.length) {
-      throw errs[0];
+      throw errs[0]
     }
-  });
+  })
 }
 
 function expectElement(locator, fn) {
-  const step = prepareStep('expect element to be', locator, fn);
-  if (!step) return;
+  const step = prepareStep('expect element to be', locator, fn)
+  if (!step) return
 
   return executeStep(step, async () => {
-    const els = await step.helper._locate(locator);
-    output.debug(`Found ${els.length} elements, first will be used for assertion`);
+    const els = await step.helper._locate(locator)
+    output.debug(`Found ${els.length} elements, first will be used for assertion`)
 
-    const result = await fn(els[0]);
-    const assertion = truth(`element (${locator})`, fn.toString());
-    assertion.assert(result);
-  });
+    const result = await fn(els[0])
+    const assertion = truth(`element (${locator})`, fn.toString())
+    assertion.assert(result)
+  })
 }
 
 function expectAnyElement(locator, fn) {
-  const step = prepareStep('expect any element to be', locator, fn);
-  if (!step) return;
+  const step = prepareStep('expect any element to be', locator, fn)
+  if (!step) return
 
   return executeStep(step, async () => {
-    const els = await step.helper._locate(locator);
-    output.debug(`Found ${els.length} elements, at least one should pass the assertion`);
+    const els = await step.helper._locate(locator)
+    output.debug(`Found ${els.length} elements, at least one should pass the assertion`)
 
-    const assertion = truth(`any element of (${locator})`, fn.toString());
+    const assertion = truth(`any element of (${locator})`, fn.toString())
 
-    let found = false;
+    let found = false
     for (const el of els) {
-      const result = await fn(el);
+      const result = await fn(el)
       if (result) {
-        found = true;
-        break;
+        found = true
+        break
       }
     }
-    if (!found) throw assertion.getException();
-  });
+    if (!found) throw assertion.getException()
+  })
 }
 
 function expectAllElements(locator, fn) {
-  const step = prepareStep('expect all elements', locator, fn);
-  if (!step) return;
+  const step = prepareStep('expect all elements', locator, fn)
+  if (!step) return
 
   return executeStep(step, async () => {
-    const els = await step.helper._locate(locator);
-    output.debug(`Found ${els.length} elements, all should pass the assertion`);
+    const els = await step.helper._locate(locator)
+    output.debug(`Found ${els.length} elements, all should pass the assertion`)
 
-    let i = 1;
+    let i = 1
     for (const el of els) {
-      output.debug(`checking element #${i}: ${el}`);
-      const result = await fn(el);
-      const assertion = truth(`element #${i} of (${locator})`, humanizeFunction(fn));
-      assertion.assert(result);
-      i++;
+      output.debug(`checking element #${i}: ${el}`)
+      const result = await fn(el)
+      const assertion = truth(`element #${i} of (${locator})`, humanizeFunction(fn))
+      assertion.assert(result)
+      i++
     }
-  });
+  })
 }
 
 module.exports = {
@@ -118,60 +127,32 @@ module.exports = {
   expectElement,
   expectAnyElement,
   expectAllElements,
-};
+}
 
 function prepareStep(purpose, locator, fn) {
-  if (store.dryRun) return;
-  const helpers = Object.values(container.helpers());
+  if (store.dryRun) return
+  const helpers = Object.values(container.helpers())
 
-  const helper = helpers.filter(h => !!h._locate)[0];
+  const helper = helpers.filter(h => !!h._locate)[0]
 
   if (!helper) {
-    throw new Error('No helper enabled with _locate method with returns a list of elements.');
+    throw new Error('No helper enabled with _locate method with returns a list of elements.')
   }
 
   if (!isAsyncFunction(fn)) {
-    throw new Error('Async function should be passed into each element');
+    throw new Error('Async function should be passed into each element')
   }
 
-  const isAssertion = purpose.startsWith('expect');
+  const isAssertion = purpose.startsWith('expect')
 
-  const step = new Step(helper, `${purpose} within "${locator}" ${isAssertion ? 'to be' : 'to'}`);
-  step.setActor('EL');
-  step.setArguments([humanizeFunction(fn)]);
-  step.helperMethod = '_locate';
+  const step = new FuncStep(`${purpose} within "${locator}" ${isAssertion ? 'to be' : 'to'}`)
+  step.setHelper(helper)
+  step.setArguments([humanizeFunction(fn)]) // user defined function is a passed argument
 
-  return step;
+  return step
 }
 
-async function executeStep(step, action) {
-  let error;
-  const promise = recorder.add('register element wrapper', async () => {
-    event.emit(event.step.started, step);
-
-    try {
-      await action();
-    } catch (err) {
-      recorder.throw(err);
-      event.emit(event.step.failed, step, err);
-      event.emit(event.step.finished, step);
-      // event.emit(event.step.after, step)
-      error = err;
-      // await recorder.promise();
-      return;
-    }
-
-    event.emit(event.step.after, step);
-    event.emit(event.step.passed, step);
-    event.emit(event.step.finished, step);
-  });
-
-  // await recorder.promise();
-
-  // if (error) {
-  //   console.log('error', error.inspect())
-  //   return recorder.throw(error);
-  // }
-
-  return promise;
+async function executeStep(step, action, stepConfig = {}) {
+  step.setCallable(action)
+  return recordStep(step, [stepConfig])
 }

package/lib/event.js

@@ -1,10 +1,10 @@
-const debug = require('debug')('codeceptjs:event');
-const events = require('events');
-const { error } = require('./output');
+const debug = require('debug')('codeceptjs:event')
+const events = require('events')
+const { error } = require('./output')
 
-const dispatcher = new events.EventEmitter();
+const dispatcher = new events.EventEmitter()
 
-dispatcher.setMaxListeners(50);
+dispatcher.setMaxListeners(50)
 /**
  * @namespace
  * @alias event
@@ -59,6 +59,7 @@ module.exports = {
     started: 'hook.start',
     passed: 'hook.passed',
     failed: 'hook.failed',
+    finished: 'hook.finished',
   },
 
   /**
@@ -141,33 +142,33 @@ module.exports = {
    * @param {*} [param]
    */
   emit(event, param) {
-    let msg = `Emitted | ${event}`;
+    let msg = `Emitted | ${event}`
     if (param && param.toString()) {
-      msg += ` (${param.toString()})`;
+      msg += ` (${param.toString()})`
     }
-    debug(msg);
+    debug(msg)
     try {
-      this.dispatcher.emit.apply(this.dispatcher, arguments);
+      this.dispatcher.emit.apply(this.dispatcher, arguments)
     } catch (err) {
-      error(`Error processing ${event} event:`);
-      error(err.stack);
+      error(`Error processing ${event} event:`)
+      error(err.stack)
     }
   },
 
   /** for testing only! */
   cleanDispatcher: () => {
-    let event;
+    let event
     for (event in this.test) {
-      this.dispatcher.removeAllListeners(this.test[event]);
+      this.dispatcher.removeAllListeners(this.test[event])
     }
     for (event in this.suite) {
-      this.dispatcher.removeAllListeners(this.test[event]);
+      this.dispatcher.removeAllListeners(this.test[event])
     }
     for (event in this.step) {
-      this.dispatcher.removeAllListeners(this.test[event]);
+      this.dispatcher.removeAllListeners(this.test[event])
     }
     for (event in this.all) {
-      this.dispatcher.removeAllListeners(this.test[event]);
+      this.dispatcher.removeAllListeners(this.test[event])
     }
   },
-};
+}

package/lib/heal.js

@@ -129,6 +129,16 @@ class Heal {
             snippet: codeSnippet,
           })
 
+          if (failureContext?.test) {
+            const test = failureContext.test
+            let note = `This test was healed by '${suggestion.name}'`
+            note += `\n\nReplace the failed code:\n\n`
+            note += colors.red(`- ${failedStep.toCode()}\n`)
+            note += colors.green(`+ ${codeSnippet}\n`)
+            test.addNote('heal', note)
+            test.meta.healed = true
+          }
+
           recorder.add('healed', () => output.print(colors.bold.green(`  Code healed successfully by ${suggestion.name}`), colors.gray('(no errors thrown)')))
           this.numHealed++
           // recorder.session.restore();