codeceptjs 4.0.0-beta.3 → 4.0.0-beta.5

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,223 @@
+const recorder = require('./recorder')
+const { debug } = require('./output')
+const store = require('./store')
+const event = require('./event')
+const within = require('./within')
+
+/**
+ * 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
+  let isAutoRetriesEnabled = store.autoRetries
+  return recorder.add(
+    sessionName,
+    () => {
+      recorder.session.start(sessionName)
+      isAutoRetriesEnabled = store.autoRetries
+      if (isAutoRetriesEnabled) debug('Auto retries disabled inside tryTo effect')
+      store.autoRetries = false
+      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.autoRetries = isAutoRetriesEnabled
+          return result
+        },
+        true,
+        false,
+      )
+    },
+    false,
+    false,
+  )
+}
+
+module.exports = {
+  hopeThat,
+  retryTo,
+  tryTo,
+  within,
+}