codeceptjs 3.7.0-beta.4 → 3.7.0-beta.6

package/lib/command/workers/runTests.js

@@ -1,83 +1,83 @@
-const tty = require('tty');
+const tty = require('tty')
 
 if (!tty.getWindowSize) {
   // this is really old method, long removed from Node, but Mocha
   // reporters fall back on it if they cannot use `process.stdout.getWindowSize`
   // we need to polyfill it.
-  tty.getWindowSize = () => [40, 80];
+  tty.getWindowSize = () => [40, 80]
 }
 
-const { parentPort, workerData } = require('worker_threads');
-const event = require('../../event');
-const container = require('../../container');
-const { getConfig } = require('../utils');
-const { tryOrDefault, deepMerge } = require('../../utils');
+const { parentPort, workerData } = require('worker_threads')
+const event = require('../../event')
+const container = require('../../container')
+const { getConfig } = require('../utils')
+const { tryOrDefault, deepMerge } = require('../../utils')
 
-let stdout = '';
+let stdout = ''
 
-const stderr = '';
+const stderr = ''
 
 // Requiring of Codecept need to be after tty.getWindowSize is available.
-const Codecept = require(process.env.CODECEPT_CLASS_PATH || '../../codecept');
+const Codecept = require(process.env.CODECEPT_CLASS_PATH || '../../codecept')
 
-const { options, tests, testRoot, workerIndex } = workerData;
+const { options, tests, testRoot, workerIndex } = workerData
 
 // hide worker output
 if (!options.debug && !options.verbose)
   process.stdout.write = string => {
-    stdout += string;
-    return true;
-  };
+    stdout += string
+    return true
+  }
 
-const overrideConfigs = tryOrDefault(() => JSON.parse(options.override), {});
+const overrideConfigs = tryOrDefault(() => JSON.parse(options.override), {})
 
 // important deep merge so dynamic things e.g. functions on config are not overridden
-const config = deepMerge(getConfig(options.config || testRoot), overrideConfigs);
+const config = deepMerge(getConfig(options.config || testRoot), overrideConfigs)
 
 // Load test and run
-const codecept = new Codecept(config, options);
-codecept.init(testRoot);
-codecept.loadTests();
-const mocha = container.mocha();
-filterTests();
+const codecept = new Codecept(config, options)
+codecept.init(testRoot)
+codecept.loadTests()
+const mocha = container.mocha()
+filterTests()
 
 // run tests
-(async function () {
+;(async function () {
   if (mocha.suite.total()) {
-    await runTests();
+    await runTests()
   }
-})();
+})()
 
 async function runTests() {
   try {
-    await codecept.bootstrap();
+    await codecept.bootstrap()
   } catch (err) {
-    throw new Error(`Error while running bootstrap file :${err}`);
+    throw new Error(`Error while running bootstrap file :${err}`)
   }
-  listenToParentThread();
-  initializeListeners();
-  disablePause();
+  listenToParentThread()
+  initializeListeners()
+  disablePause()
   try {
-    await codecept.run();
+    await codecept.run()
   } finally {
-    await codecept.teardown();
+    await codecept.teardown()
   }
 }
 
 function filterTests() {
-  const files = codecept.testFiles;
-  mocha.files = files;
-  mocha.loadFiles();
+  const files = codecept.testFiles
+  mocha.files = files
+  mocha.loadFiles()
 
   for (const suite of mocha.suite.suites) {
-    suite.tests = suite.tests.filter(test => tests.indexOf(test.uid) >= 0);
+    suite.tests = suite.tests.filter(test => tests.indexOf(test.uid) >= 0)
   }
 }
 
 function initializeListeners() {
   function simplifyError(error) {
     if (error) {
-      const { stack, uncaught, message, actual, expected } = error;
+      const { stack, uncaught, message, actual, expected } = error
 
       return {
         stack,
@@ -85,36 +85,36 @@ function initializeListeners() {
         message,
         actual,
         expected,
-      };
+      }
     }
 
-    return null;
+    return null
   }
   function simplifyTest(test, err = null) {
-    test = { ...test };
+    test = { ...test }
 
     if (test.start && !test.duration) {
-      const end = new Date();
-      test.duration = end - test.start;
+      const end = new Date()
+      test.duration = end - test.start
     }
 
     if (test.err) {
-      err = simplifyError(test.err);
-      test.status = 'failed';
+      err = simplifyError(test.err)
+      test.status = 'failed'
     } else if (err) {
-      err = simplifyError(err);
-      test.status = 'failed';
+      err = simplifyError(err)
+      test.status = 'failed'
     }
-    const parent = {};
+    const parent = {}
     if (test.parent) {
-      parent.title = test.parent.title;
+      parent.title = test.parent.title
     }
 
     if (test.opts) {
       Object.keys(test.opts).forEach(k => {
-        if (typeof test.opts[k] === 'object') delete test.opts[k];
-        if (typeof test.opts[k] === 'function') delete test.opts[k];
-      });
+        if (typeof test.opts[k] === 'object') delete test.opts[k]
+        if (typeof test.opts[k] === 'function') delete test.opts[k]
+      })
     }
 
     return {
@@ -125,30 +125,33 @@ function initializeListeners() {
       retries: test._retries,
       title: test.title,
       status: test.status,
+      notes: test.notes || [],
+      meta: test.meta || {},
+      artifacts: test.artifacts || [],
       duration: test.duration || 0,
       err,
       parent,
       steps: test.steps && test.steps.length > 0 ? simplifyStepsInTestObject(test.steps, err) : [],
-    };
+    }
   }
 
   function simplifyStepsInTestObject(steps, err) {
-    steps = [...steps];
-    const _steps = [];
+    steps = [...steps]
+    const _steps = []
 
     for (step of steps) {
-      const _args = [];
+      const _args = []
 
       if (step.args) {
         for (const arg of step.args) {
           // check if arg is a JOI object
           if (arg && arg.$_root) {
-            _args.push(JSON.stringify(arg).slice(0, 300));
+            _args.push(JSON.stringify(arg).slice(0, 300))
             // check if arg is a function
           } else if (arg && typeof arg === 'function') {
-            _args.push(arg.name);
+            _args.push(arg.name)
           } else {
-            _args.push(arg);
+            _args.push(arg)
           }
         }
       }
@@ -164,38 +167,38 @@ function initializeListeners() {
         finishedAt: step.finishedAt,
         duration: step.duration,
         err,
-      });
+      })
     }
 
-    return _steps;
+    return _steps
   }
 
   function simplifyStep(step, err = null) {
-    step = { ...step };
+    step = { ...step }
 
     if (step.startTime && !step.duration) {
-      const end = new Date();
-      step.duration = end - step.startTime;
+      const end = new Date()
+      step.duration = end - step.startTime
     }
 
     if (step.err) {
-      err = simplifyError(step.err);
-      step.status = 'failed';
+      err = simplifyError(step.err)
+      step.status = 'failed'
     } else if (err) {
-      err = simplifyError(err);
-      step.status = 'failed';
+      err = simplifyError(err)
+      step.status = 'failed'
     }
 
-    const parent = {};
+    const parent = {}
     if (step.metaStep) {
-      parent.title = step.metaStep.actor;
+      parent.title = step.metaStep.actor
     }
 
     if (step.opts) {
       Object.keys(step.opts).forEach(k => {
-        if (typeof step.opts[k] === 'object') delete step.opts[k];
-        if (typeof step.opts[k] === 'function') delete step.opts[k];
-      });
+        if (typeof step.opts[k] === 'object') delete step.opts[k]
+        if (typeof step.opts[k] === 'function') delete step.opts[k]
+      })
     }
 
     return {
@@ -207,43 +210,43 @@ function initializeListeners() {
       err,
       parent,
       test: simplifyTest(step.test),
-    };
+    }
   }
 
-  collectStats();
+  collectStats()
   // suite
-  event.dispatcher.on(event.suite.before, suite => sendToParentThread({ event: event.suite.before, workerIndex, data: simplifyTest(suite) }));
-  event.dispatcher.on(event.suite.after, suite => sendToParentThread({ event: event.suite.after, workerIndex, data: simplifyTest(suite) }));
+  event.dispatcher.on(event.suite.before, suite => sendToParentThread({ event: event.suite.before, workerIndex, data: simplifyTest(suite) }))
+  event.dispatcher.on(event.suite.after, suite => sendToParentThread({ event: event.suite.after, workerIndex, data: simplifyTest(suite) }))
 
   // calculate duration
-  event.dispatcher.on(event.test.started, test => (test.start = new Date()));
+  event.dispatcher.on(event.test.started, test => (test.start = new Date()))
 
   // tests
-  event.dispatcher.on(event.test.before, test => sendToParentThread({ event: event.test.before, workerIndex, data: simplifyTest(test) }));
-  event.dispatcher.on(event.test.after, test => sendToParentThread({ event: event.test.after, workerIndex, data: simplifyTest(test) }));
+  event.dispatcher.on(event.test.before, test => sendToParentThread({ event: event.test.before, workerIndex, data: simplifyTest(test) }))
+  event.dispatcher.on(event.test.after, test => sendToParentThread({ event: event.test.after, workerIndex, data: simplifyTest(test) }))
   // we should force-send correct errors to prevent race condition
-  event.dispatcher.on(event.test.finished, (test, err) => sendToParentThread({ event: event.test.finished, workerIndex, data: simplifyTest(test, err) }));
-  event.dispatcher.on(event.test.failed, (test, err) => sendToParentThread({ event: event.test.failed, workerIndex, data: simplifyTest(test, err) }));
-  event.dispatcher.on(event.test.passed, (test, err) => sendToParentThread({ event: event.test.passed, workerIndex, data: simplifyTest(test, err) }));
-  event.dispatcher.on(event.test.started, test => sendToParentThread({ event: event.test.started, workerIndex, data: simplifyTest(test) }));
-  event.dispatcher.on(event.test.skipped, test => sendToParentThread({ event: event.test.skipped, workerIndex, data: simplifyTest(test) }));
+  event.dispatcher.on(event.test.finished, (test, err) => sendToParentThread({ event: event.test.finished, workerIndex, data: simplifyTest(test, err) }))
+  event.dispatcher.on(event.test.failed, (test, err) => sendToParentThread({ event: event.test.failed, workerIndex, data: simplifyTest(test, err) }))
+  event.dispatcher.on(event.test.passed, (test, err) => sendToParentThread({ event: event.test.passed, workerIndex, data: simplifyTest(test, err) }))
+  event.dispatcher.on(event.test.started, test => sendToParentThread({ event: event.test.started, workerIndex, data: simplifyTest(test) }))
+  event.dispatcher.on(event.test.skipped, test => sendToParentThread({ event: event.test.skipped, workerIndex, data: simplifyTest(test) }))
 
   // steps
-  event.dispatcher.on(event.step.finished, step => sendToParentThread({ event: event.step.finished, workerIndex, data: simplifyStep(step) }));
-  event.dispatcher.on(event.step.started, step => sendToParentThread({ event: event.step.started, workerIndex, data: simplifyStep(step) }));
-  event.dispatcher.on(event.step.passed, step => sendToParentThread({ event: event.step.passed, workerIndex, data: simplifyStep(step) }));
-  event.dispatcher.on(event.step.failed, step => sendToParentThread({ event: event.step.failed, workerIndex, data: simplifyStep(step) }));
+  event.dispatcher.on(event.step.finished, step => sendToParentThread({ event: event.step.finished, workerIndex, data: simplifyStep(step) }))
+  event.dispatcher.on(event.step.started, step => sendToParentThread({ event: event.step.started, workerIndex, data: simplifyStep(step) }))
+  event.dispatcher.on(event.step.passed, step => sendToParentThread({ event: event.step.passed, workerIndex, data: simplifyStep(step) }))
+  event.dispatcher.on(event.step.failed, step => sendToParentThread({ event: event.step.failed, workerIndex, data: simplifyStep(step) }))
 
-  event.dispatcher.on(event.hook.failed, (test, err) => sendToParentThread({ event: event.hook.failed, workerIndex, data: simplifyTest(test, err) }));
-  event.dispatcher.on(event.hook.passed, (test, err) => sendToParentThread({ event: event.hook.passed, workerIndex, data: simplifyTest(test, err) }));
-  event.dispatcher.on(event.all.failures, data => sendToParentThread({ event: event.all.failures, workerIndex, data }));
+  event.dispatcher.on(event.hook.failed, (test, err) => sendToParentThread({ event: event.hook.failed, workerIndex, data: simplifyTest(test, err) }))
+  event.dispatcher.on(event.hook.passed, (test, err) => sendToParentThread({ event: event.hook.passed, workerIndex, data: simplifyTest(test, err) }))
+  event.dispatcher.on(event.all.failures, data => sendToParentThread({ event: event.all.failures, workerIndex, data }))
 
   // all
-  event.dispatcher.once(event.all.result, () => parentPort.close());
+  event.dispatcher.once(event.all.result, () => parentPort.close())
 }
 
 function disablePause() {
-  global.pause = () => {};
+  global.pause = () => {}
 }
 
 function collectStats() {
@@ -253,36 +256,36 @@ function collectStats() {
     skipped: 0,
     tests: 0,
     pending: 0,
-  };
+  }
   event.dispatcher.on(event.test.skipped, () => {
-    stats.skipped++;
-  });
+    stats.skipped++
+  })
   event.dispatcher.on(event.test.passed, () => {
-    stats.passes++;
-  });
+    stats.passes++
+  })
   event.dispatcher.on(event.test.failed, test => {
     if (test.ctx._runnable.title.includes('hook: AfterSuite')) {
-      stats.failedHooks += 1;
+      stats.failedHooks += 1
     }
-    stats.failures++;
-  });
+    stats.failures++
+  })
   event.dispatcher.on(event.test.skipped, () => {
-    stats.pending++;
-  });
+    stats.pending++
+  })
   event.dispatcher.on(event.test.finished, () => {
-    stats.tests++;
-  });
+    stats.tests++
+  })
   event.dispatcher.once(event.all.after, () => {
-    sendToParentThread({ event: event.all.after, data: stats });
-  });
+    sendToParentThread({ event: event.all.after, data: stats })
+  })
 }
 
 function sendToParentThread(data) {
-  parentPort.postMessage(data);
+  parentPort.postMessage(data)
 }
 
 function listenToParentThread() {
   parentPort.on('message', eventData => {
-    container.append({ support: eventData.data });
-  });
+    container.append({ support: eventData.data })
+  })
 }

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')
@@ -38,6 +39,7 @@ class Container {
    * @param {*} opts
    */
   static create(config, opts) {
+    debug('creating container')
     asyncHelperPromise = Promise.resolve()
 
     // dynamically create mocha instance
@@ -134,6 +136,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 +153,7 @@ class Container {
     container.plugins = newPlugins || {}
     asyncHelperPromise = Promise.resolve()
     store.actor = null
+    debug('container cleared')
   }
 
   /**
@@ -216,6 +220,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 +231,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 +329,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 +342,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/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();