codeceptjs 3.6.10 → 3.7.0-beta.10

package/lib/data/context.js

@@ -13,8 +13,8 @@ module.exports = function (context) {
           fn = opts
           opts = {}
         }
-        opts.data = data.map((dataRow) => dataRow.data)
-        data.forEach((dataRow) => {
+        opts.data = data.map(dataRow => dataRow.data)
+        data.forEach(dataRow => {
           const dataTitle = replaceTitle(title, dataRow)
           if (dataRow.skip) {
             context.xScenario(dataTitle)
@@ -32,8 +32,8 @@ module.exports = function (context) {
             fn = opts
             opts = {}
           }
-          opts.data = data.map((dataRow) => dataRow.data)
-          data.forEach((dataRow) => {
+          opts.data = data.map(dataRow => dataRow.data)
+          data.forEach(dataRow => {
             const dataTitle = replaceTitle(title, dataRow)
             if (dataRow.skip) {
               context.xScenario(dataTitle)
@@ -51,8 +51,8 @@ module.exports = function (context) {
   context.xData = function (dataTable) {
     const data = detectDataType(dataTable)
     return {
-      Scenario: (title) => {
-        data.forEach((dataRow) => {
+      Scenario: title => {
+        data.forEach(dataRow => {
           const dataTitle = replaceTitle(title, dataRow)
           context.xScenario(dataTitle)
         })
@@ -69,10 +69,7 @@ function replaceTitle(title, dataRow) {
 
   // if `dataRow` is object and has own `toString()` method,
   // it should be printed
-  if (
-    Object.prototype.toString.call(dataRow.data) === Object().toString() &&
-    dataRow.data.toString() !== Object().toString()
-  ) {
+  if (Object.prototype.toString.call(dataRow.data) === Object().toString() && dataRow.data.toString() !== Object().toString()) {
     return `${title} | ${dataRow.data}`
   }
 
@@ -102,7 +99,7 @@ function detectDataType(dataTable) {
     return dataTable()
   }
   if (Array.isArray(dataTable)) {
-    return dataTable.map((item) => {
+    return dataTable.map(item => {
       if (isTableDataRow(item)) {
         return item
       }
@@ -117,10 +114,10 @@ function detectDataType(dataTable) {
 }
 
 function maskSecretInTitle(scenarios) {
-  scenarios.forEach((scenario) => {
+  scenarios.forEach(scenario => {
     const res = []
 
-    scenario.test.title.split(',').forEach((item) => {
+    scenario.test.title.split(',').forEach(item => {
       res.push(item.replace(/{"_secret":"(.*)"}/, '"*****"'))
     })
 

package/lib/data/dataScenarioConfig.js

@@ -10,7 +10,7 @@ class DataScenarioConfig {
    * @param {*} err
    */
   throws(err) {
-    this.scenarios.forEach((scenario) => scenario.throws(err))
+    this.scenarios.forEach(scenario => scenario.throws(err))
     return this
   }
 
@@ -21,7 +21,7 @@ class DataScenarioConfig {
    *
    */
   fails() {
-    this.scenarios.forEach((scenario) => scenario.fails())
+    this.scenarios.forEach(scenario => scenario.fails())
     return this
   }
 
@@ -31,7 +31,7 @@ class DataScenarioConfig {
    * @param {*} retries
    */
   retry(retries) {
-    this.scenarios.forEach((scenario) => scenario.retry(retries))
+    this.scenarios.forEach(scenario => scenario.retry(retries))
     return this
   }
 
@@ -40,7 +40,7 @@ class DataScenarioConfig {
    * @param {*} timeout
    */
   timeout(timeout) {
-    this.scenarios.forEach((scenario) => scenario.timeout(timeout))
+    this.scenarios.forEach(scenario => scenario.timeout(timeout))
     return this
   }
 
@@ -49,7 +49,7 @@ class DataScenarioConfig {
    * Helper name can be omitted and values will be applied to first helper.
    */
   config(helper, obj) {
-    this.scenarios.forEach((scenario) => scenario.config(helper, obj))
+    this.scenarios.forEach(scenario => scenario.config(helper, obj))
     return this
   }
 
@@ -58,7 +58,7 @@ class DataScenarioConfig {
    * @param {*} tagName
    */
   tag(tagName) {
-    this.scenarios.forEach((scenario) => scenario.tag(tagName))
+    this.scenarios.forEach(scenario => scenario.tag(tagName))
     return this
   }
 
@@ -67,7 +67,7 @@ class DataScenarioConfig {
    * @param {*} obj
    */
   inject(obj) {
-    this.scenarios.forEach((scenario) => scenario.inject(obj))
+    this.scenarios.forEach(scenario => scenario.inject(obj))
     return this
   }
 
@@ -76,7 +76,7 @@ class DataScenarioConfig {
    * @param {*} dependencies
    */
   injectDependencies(dependencies) {
-    this.scenarios.forEach((scenario) => scenario.injectDependencies(dependencies))
+    this.scenarios.forEach(scenario => scenario.injectDependencies(dependencies))
     return this
   }
 }

package/lib/data/dataTableArgument.js

@@ -5,8 +5,8 @@
 class DataTableArgument {
   /** @param {*} gherkinDataTable */
   constructor(gherkinDataTable) {
-    this.rawData = gherkinDataTable.rows.map((row) => {
-      return row.cells.map((cell) => {
+    this.rawData = gherkinDataTable.rows.map(row => {
+      return row.cells.map(cell => {
         return cell.value
       })
     })
@@ -34,7 +34,7 @@ class DataTableArgument {
   hashes() {
     const copy = this.raw()
     const header = copy.shift()
-    return copy.map((row) => {
+    return copy.map(row => {
       const r = {}
       row.forEach((cell, index) => (r[header[index]] = cell))
       return r
@@ -47,19 +47,19 @@ class DataTableArgument {
    */
   rowsHash() {
     const rows = this.raw()
-    const everyRowHasTwoColumns = rows.every((row) => row.length === 2)
+    const everyRowHasTwoColumns = rows.every(row => row.length === 2)
     if (!everyRowHasTwoColumns) {
       throw new Error('rowsHash can only be called on a data table where all rows have exactly two columns')
     }
     /** @type {Record<string, string>} */
     const result = {}
-    rows.forEach((x) => (result[x[0]] = x[1]))
+    rows.forEach(x => (result[x[0]] = x[1]))
     return result
   }
 
   /** Transposed the data */
   transpose() {
-    this.rawData = this.rawData[0].map((x, i) => this.rawData.map((y) => y[i]))
+    this.rawData = this.rawData[0].map((x, i) => this.rawData.map(y => y[i]))
   }
 }
 

package/lib/data/table.js

@@ -10,13 +10,10 @@ class DataTable {
 
   /** @param {Array<*>} array */
   add(array) {
-    if (array.length !== this.array.length)
-      throw new Error(
-        `There is too many elements in given data array. Please provide data in this format: ${this.array}`,
-      )
+    if (array.length !== this.array.length) throw new Error(`There is too many elements in given data array. Please provide data in this format: ${this.array}`)
     const tempObj = {}
     let arrayCounter = 0
-    this.array.forEach((elem) => {
+    this.array.forEach(elem => {
       tempObj[elem] = array[arrayCounter]
       tempObj.toString = () => JSON.stringify(tempObj)
       arrayCounter++
@@ -26,13 +23,10 @@ class DataTable {
 
   /** @param {Array<*>} array */
   xadd(array) {
-    if (array.length !== this.array.length)
-      throw new Error(
-        `There is too many elements in given data array. Please provide data in this format: ${this.array}`,
-      )
+    if (array.length !== this.array.length) throw new Error(`There is too many elements in given data array. Please provide data in this format: ${this.array}`)
     const tempObj = {}
     let arrayCounter = 0
-    this.array.forEach((elem) => {
+    this.array.forEach(elem => {
       tempObj[elem] = array[arrayCounter]
       tempObj.toString = () => JSON.stringify(tempObj)
       arrayCounter++
@@ -42,7 +36,7 @@ class DataTable {
 
   /** @param {Function} func */
   filter(func) {
-    return this.rows.filter((row) => func(row.data))
+    return this.rows.filter(row => func(row.data))
   }
 }
 

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

@@ -0,0 +1,158 @@
+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) {
+  let stepConfig
+  if (arguments[arguments.length - 1] instanceof StepConfig) {
+    stepConfig = arguments[arguments.length - 1]
+  }
+
+  if (!fn || fn === stepConfig) {
+    fn = locator
+    locator = purpose
+    purpose = 'first element'
+  }
+
+  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, using first element`)
+
+      return fn(els[0])
+    },
+    stepConfig,
+  )
+}
+
+function eachElement(purpose, locator, fn) {
+  if (!fn) {
+    fn = locator
+    locator = purpose
+    purpose = 'for each element'
+  }
+
+  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 errs = []
+    let i = 0
+    for (const el of els) {
+      try {
+        await fn(el, i)
+      } catch (err) {
+        output.error(`eachElement: failed operation on element #${i} ${el}`)
+        errs.push(err)
+      }
+      i++
+    }
+
+    if (errs.length) {
+      throw errs[0]
+    }
+  })
+}
+
+function expectElement(locator, fn) {
+  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 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
+
+  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 assertion = truth(`any element of (${locator})`, fn.toString())
+
+    let found = false
+    for (const el of els) {
+      const result = await fn(el)
+      if (result) {
+        found = true
+        break
+      }
+    }
+    if (!found) throw assertion.getException()
+  })
+}
+
+function expectAllElements(locator, fn) {
+  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`)
+
+    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++
+    }
+  })
+}
+
+module.exports = {
+  element,
+  eachElement,
+  expectElement,
+  expectAnyElement,
+  expectAllElements,
+}
+
+function prepareStep(purpose, locator, fn) {
+  if (store.dryRun) return
+  const helpers = Object.values(container.helpers())
+
+  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.')
+  }
+
+  if (!isAsyncFunction(fn)) {
+    throw new Error('Async function should be passed into each element')
+  }
+
+  const isAssertion = purpose.startsWith('expect')
+
+  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
+}
+
+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,7 +59,9 @@ module.exports = {
     started: 'hook.start',
     passed: 'hook.passed',
     failed: 'hook.failed',
+    finished: 'hook.finished',
   },
+
   /**
    * @type {object}
    * @constant
@@ -140,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])
     }
   },
-};
+}