codeceptjs 3.7.0-beta.5 → 3.7.0-beta.7

package/README.md

@@ -5,13 +5,13 @@
 
 ## Build Status
 
-| Type      | Engine     | Status                                                                                                                                                                                                     |
-| --------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 🌐 Web    | Playwright | [![Playwright Tests](https://github.com/codeceptjs/CodeceptJS/actions/workflows/playwright.yml/badge.svg)](https://github.com/codeceptjs/CodeceptJS/actions/workflows/playwright.yml)                      |
-| 🌐 Web    | Puppeteer  | [![Puppeteer Tests](https://github.com/codeceptjs/CodeceptJS/actions/workflows/puppeteer.yml/badge.svg)](https://github.com/codeceptjs/CodeceptJS/actions/workflows/puppeteer.yml)                         |
-| 🌐 Web    | WebDriver  | [![WebDriver Tests](https://github.com/codeceptjs/CodeceptJS/actions/workflows/webdriver.yml/badge.svg)](https://github.com/codeceptjs/CodeceptJS/actions/workflows/webdriver.yml)                         |
-| 🌐 Web    | TestCafe   | [![TestCafe Tests](https://github.com/codeceptjs/CodeceptJS/actions/workflows/testcafe.yml/badge.svg)](https://github.com/codeceptjs/CodeceptJS/actions/workflows/testcafe.yml)                            |
-| 📱 Mobile | Appium     | [![Appium V2 Tests - Android](https://github.com/codeceptjs/CodeceptJS/actions/workflows/appiumV2_Android.yml/badge.svg)](https://github.com/codeceptjs/CodeceptJS/actions/workflows/appiumV2_Android.yml) |
+| Type      | Engine     | Status                                                                                                                                                                                              |
+| --------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 🌐 Web    | Playwright | [![Playwright Tests](https://github.com/codeceptjs/CodeceptJS/actions/workflows/playwright.yml/badge.svg)](https://github.com/codeceptjs/CodeceptJS/actions/workflows/playwright.yml)               |
+| 🌐 Web    | Puppeteer  | [![Puppeteer Tests](https://github.com/codeceptjs/CodeceptJS/actions/workflows/puppeteer.yml/badge.svg)](https://github.com/codeceptjs/CodeceptJS/actions/workflows/puppeteer.yml)                  |
+| 🌐 Web    | WebDriver  | [![WebDriver Tests](https://github.com/codeceptjs/CodeceptJS/actions/workflows/webdriver.yml/badge.svg)](https://github.com/codeceptjs/CodeceptJS/actions/workflows/webdriver.yml)                  |
+| 🌐 Web    | TestCafe   | [![TestCafe Tests](https://github.com/codeceptjs/CodeceptJS/actions/workflows/testcafe.yml/badge.svg)](https://github.com/codeceptjs/CodeceptJS/actions/workflows/testcafe.yml)                     |
+| 📱 Mobile | Appium     | [![Appium Tests - Android](https://github.com/codeceptjs/CodeceptJS/actions/workflows/appium_Android.yml/badge.svg)](https://github.com/codeceptjs/CodeceptJS/actions/workflows/appium_Android.yml) |
 
 # CodeceptJS [![Made in Ukraine](https://img.shields.io/badge/made_in-ukraine-ffd700.svg?labelColor=0057b7)](https://stand-with-ukraine.pp.ua)
 

package/lib/effects.js

@@ -1,84 +1,33 @@
 const recorder = require('./recorder')
 const { debug } = require('./output')
 const store = require('./store')
+const event = require('./event')
 
 /**
- * @module hopeThat
- *
- * `hopeThat` is a utility function for CodeceptJS tests that allows for soft assertions.
- * It enables conditional assertions without terminating the test upon failure.
- * This is particularly useful in scenarios like A/B testing, handling unexpected elements,
- * or performing multiple assertions where you want to collect all results before deciding
- * on the test outcome.
- *
- * ## Use Cases
- *
- * - **Multiple Conditional Assertions**: Perform several assertions and evaluate all their outcomes together.
- * - **A/B Testing**: Handle different variants in A/B tests without failing the entire test upon one variant's failure.
- * - **Unexpected Elements**: Manage elements that may or may not appear, such as "Accept Cookie" banners.
- *
- * ## Examples
- *
- * ### Multiple Conditional Assertions
- *
- * Add the assertion library:
- * ```js
- * const assert = require('assert');
- * const { hopeThat } = require('codeceptjs/effects');
- * ```
- *
- * Use `hopeThat` with assertions:
- * ```js
- * const result1 = await hopeThat(() => I.see('Hello, user'));
- * const result2 = await hopeThat(() => I.seeElement('.welcome'));
- * assert.ok(result1 && result2, 'Assertions were not successful');
- * ```
- *
- * ### Optional Click
- *
- * ```js
- * const { hopeThat } = require('codeceptjs/effects');
- *
- * I.amOnPage('/');
- * await hopeThat(() => I.click('Agree', '.cookies'));
- * ```
- *
- * Performs a soft assertion within CodeceptJS tests.
- *
- * This function records the execution of a callback containing assertion logic.
- * If the assertion fails, it logs the failure without stopping the test execution.
- * It is useful for scenarios where multiple assertions are performed, and you want
- * to evaluate all outcomes before deciding on the test result.
- *
- * ## Usage
- *
- * ```js
- * const result = await hopeThat(() => I.see('Welcome'));
- *
- * // If the text "Welcome" is on the page, result => true
- * // If the text "Welcome" is not on the page, result => false
- * ```
+ * 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 soft assertion logic.
- * @returns {Promise<boolean | any>} - Resolves to `true` if the assertion is successful, or `false` if it fails.
+ * @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
- * // Multiple Conditional Assertions
- * const assert = require('assert');
- * const { hopeThat } = require('codeceptjs/effects');
+ * const { hopeThat } = require('codeceptjs/effects')
+ * await hopeThat(() => {
+ *   I.see('Welcome'); // Perform a soft assertion
+ * });
  *
- * const result1 = await hopeThat(() => I.see('Hello, user'));
- * const result2 = await hopeThat(() => I.seeElement('.welcome'));
- * assert.ok(result1 && result2, 'Assertions were not successful');
- *
- * @example
- * // Optional Click
- * const { hopeThat } = require('codeceptjs/effects');
- *
- * I.amOnPage('/');
- * await hopeThat(() => I.click('Agree', '.cookies'));
+ * @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
@@ -100,6 +49,9 @@ async function hopeThat(callback) {
         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
       })
@@ -118,6 +70,149 @@ async function hopeThat(callback) {
   )
 }
 
+/**
+ * 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/helper/Appium.js

@@ -44,7 +44,7 @@ const vendorPrefix = {
  *
  * This helper should be configured in codecept.conf.ts or codecept.conf.js
  *
- * * `appiumV2`: set this to true if you want to run tests with AppiumV2. See more how to setup [here](https://codecept.io/mobile/#setting-up)
+ * * `appiumV2`: by default is true, set this to false if you want to run tests with AppiumV1. See more how to setup [here](https://codecept.io/mobile/#setting-up)
  * * `app`: Application path. Local path or remote URL to an .ipa or .apk file, or a .zip containing one of these. Alias to desiredCapabilities.appPackage
  * * `host`: (default: 'localhost') Appium host
  * * `port`: (default: '4723') Appium port
@@ -124,7 +124,7 @@ const vendorPrefix = {
  * {
  * helpers: {
  *   Appium: {
- *         appiumV2: true,
+ *         appiumV2: true, // By default is true, set to false if you want to run against Appium v1
  *         host: "hub-cloud.browserstack.com",
  *         port: 4444,
  *         user: process.env.BROWSERSTACK_USER,
@@ -178,14 +178,12 @@ class Appium extends Webdriver {
     super(config)
 
     this.isRunning = false
-    if (config.appiumV2 === true) {
-      this.appiumV2 = true
-    }
+    this.appiumV2 = config.appiumV2 || true
     this.axios = axios.create()
 
     webdriverio = require('webdriverio')
     if (!config.appiumV2) {
-      console.log('The Appium core team does not maintain Appium 1.x anymore since the 1st of January 2022. Please migrating to Appium 2.x by adding appiumV2: true to your config.')
+      console.log('The Appium core team does not maintain Appium 1.x anymore since the 1st of January 2022. Appium 2.x is used by default.')
       console.log('More info: https://bit.ly/appium-v2-migration')
       console.log('This Appium 1.x support will be removed in next major release.')
     }

package/lib/helper/WebDriver.js

@@ -24,6 +24,7 @@ const { dontSeeTraffic, seeTraffic, grabRecordedNetworkTraffics, stopRecordingTr
 
 const SHADOW = 'shadow'
 const webRoot = 'body'
+let browserLogs = []
 
 /**
  * ## Configuration
@@ -621,6 +622,10 @@ class WebDriver extends Helper {
     }
 
     this.browser.on('dialog', () => {})
+
+    await this.browser.sessionSubscribe({ events: ['log.entryAdded'] })
+    this.browser.on('log.entryAdded', logEvents)
+
     return this.browser
   }
 
@@ -658,6 +663,7 @@ class WebDriver extends Helper {
       if (!(err.message.indexOf("Storage is disabled inside 'data:' URLs.") > -1)) throw err
     })
     await this.closeOtherTabs()
+    browserLogs = []
     return this.browser
   }
 
@@ -1522,11 +1528,7 @@ class WebDriver extends Helper {
    * {{> grabBrowserLogs }}
    */
   async grabBrowserLogs() {
-    if (this.browser.isW3C) {
-      this.debug('Logs not available in W3C specification')
-      return
-    }
-    return this.browser.getLogs('browser')
+    return browserLogs
   }
 
   /**
@@ -1788,18 +1790,25 @@ class WebDriver extends Helper {
 
         if (browser) {
           this.debug(`Screenshot of ${sessionName} session has been saved to ${outputFile}`)
-          return browser.saveScreenshot(outputFile)
+          await browser.saveScreenshot(outputFile)
         }
       }
     }
 
     if (!fullPage) {
       this.debug(`Screenshot has been saved to ${outputFile}`)
-      return this.browser.saveScreenshot(outputFile)
+      await this.browser.saveScreenshot(outputFile)
     }
 
     const originalWindowSize = await this.browser.getWindowSize()
 
+    // this case running on device, so we could not set the windowSize
+    if (this.browser.isMobile) {
+      this.debug(`Screenshot has been saved to ${outputFile}, size: ${originalWindowSize.width}x${originalWindowSize.height}`)
+      const buffer = await this.browser.saveScreenshot(outputFile)
+      return buffer
+    }
+
     let { width, height } = await this.browser
       .execute(function () {
         return {
@@ -3134,4 +3143,8 @@ function prepareLocateFn(context) {
   }
 }
 
+function logEvents(event) {
+  browserLogs.push(event.text) // add log message to the array
+}
+
 module.exports = WebDriver

package/lib/pause.js

@@ -84,12 +84,10 @@ function pauseSession(passedObject = {}) {
   })
   return new Promise(resolve => {
     finish = resolve
-    // eslint-disable-next-line
     return askForStep()
   })
 }
 
-/* eslint-disable */
 async function parseInput(cmd) {
   rl.pause()
   next = false
@@ -198,7 +196,6 @@ async function parseInput(cmd) {
   recorder.add('ask for next step', askForStep)
   nextStep()
 }
-/* eslint-enable */
 
 function askForStep() {
   return new Promise(resolve => {

package/lib/plugin/retryTo.js

@@ -1,127 +1,19 @@
-const recorder = require('../recorder')
-const { debug } = require('../output')
-
-const defaultConfig = {
-  registerGlobal: true,
-  pollInterval: 200,
-}
-
-/**
- *
- *
- * Adds global `retryTo` which retries steps a few times before failing.
- *
- * Enable this plugin in `codecept.conf.js` (enabled by default for new setups):
- *
- * ```js
- * plugins: {
- *   retryTo: {
- *     enabled: true
- *   }
- * }
- * ```
- *
- * Use it in your tests:
- *
- * ```js
- * // retry these steps 5 times before failing
- * await retryTo((tryNum) => {
- *   I.switchTo('#editor frame');
- *   I.click('Open');
- *   I.see('Opened')
- * }, 5);
- * ```
- * Set polling interval as 3rd argument (200ms by default):
- *
- * ```js
- * // retry these steps 5 times before failing
- * await retryTo((tryNum) => {
- *   I.switchTo('#editor frame');
- *   I.click('Open');
- *   I.see('Opened')
- * }, 5, 100);
- * ```
- *
- * Default polling interval can be changed in a config:
- *
- * ```js
- * plugins: {
- *   retryTo: {
- *     enabled: true,
- *     pollInterval: 500,
- *   }
- * }
- * ```
- *
- * Disables retryFailedStep plugin for steps inside a block;
- *
- * Use this plugin if:
- *
- * * you need repeat a set of actions in flaky tests
- * * iframe was not rendered and you need to retry switching to it
- *
- *
- * #### Configuration
- *
- * * `pollInterval` - default interval between retries in ms. 200 by default.
- * * `registerGlobal` - to register `retryTo` function globally, true by default
- *
- * If `registerGlobal` is false you can use retryTo from the plugin:
- *
- * ```js
- * const retryTo = codeceptjs.container.plugins('retryTo');
- * ```
- *
- */
-module.exports = function (config) {
-  config = Object.assign(defaultConfig, config)
-  function retryTo(callback, maxTries, pollInterval = config.pollInterval) {
-    return new Promise((done, reject) => {
-      let tries = 1
-
-      function handleRetryException(err) {
-        recorder.throw(err)
-        reject(err)
-      }
-
-      const tryBlock = async () => {
-        tries++
-        recorder.session.start(`retryTo ${tries}`)
-        try {
-          await callback(tries)
-        } catch (err) {
-          handleRetryException(err)
-        }
-
-        // Call done if no errors
-        recorder.add(() => {
-          recorder.session.restore(`retryTo ${tries}`)
-          done(null)
-        })
-
-        // Catch errors and retry
-        recorder.session.catch(err => {
-          recorder.session.restore(`retryTo ${tries}`)
-          if (tries <= maxTries) {
-            debug(`Error ${err}... Retrying`)
-            recorder.add(`retryTo ${tries}`, () => setTimeout(tryBlock, pollInterval))
-          } else {
-            // if maxTries reached
-            handleRetryException(err)
-          }
-        })
-      }
-
-      recorder.add('retryTo', tryBlock).catch(err => {
-        console.error('An error occurred:', err)
-        done(null)
-      })
-    })
-  }
-
-  if (config.registerGlobal) {
-    global.retryTo = retryTo
-  }
-
-  return retryTo
+module.exports = function () {
+  console.log(`
+Deprecated Warning: 'retryTo' has been moved to the effects module.
+You should update your tests to use it as follows:
+
+\`\`\`javascript
+const { retryTo } = require('codeceptjs/effects');
+
+// Example: Retry these steps 5 times before failing
+await retryTo((tryNum) => {
+  I.switchTo('#editor frame');
+  I.click('Open');
+  I.see('Opened');
+}, 5);
+\`\`\`
+
+For more details, refer to the documentation.
+  `)
 }