address CR

Author: kobenguyent

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.
- *
- * @example
- * // Multiple Conditional Assertions
- * const assert = require('assert');
- * const { hopeThat } = require('codeceptjs/effects');
- *
- * const result1 = await hopeThat(() => I.see('Hello, user'));
- * const result2 = await hopeThat(() => I.seeElement('.welcome'));
- * assert.ok(result1 && result2, 'Assertions were not successful');
+ * @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
- * // Optional Click
- * const { hopeThat } = require('codeceptjs/effects');
+ * const { hopeThat } = require('codeceptjs/effects')
+ * await hopeThat(() => {
+ *   I.see('Welcome'); // Perform a soft assertion
+ * });
  *
- * 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.on(event.test.after, test => {
+          test.notes.push({ type: 'conditionalError', text: msg })
+        })
         recorder.session.restore(sessionName)
         return result
       })
@@ -119,46 +71,33 @@ async function hopeThat(callback) {
 }
 
 /**
+ * A CodeceptJS utility function to retry a step or callback multiple times with a specified polling interval.
  *
- * @module retryTo
- *
- * `retryTo` which retries steps a few times before failing.
- *
- *
- * Use it in your tests:
- *
- * const { retryTo } = require('codeceptjs/effects');
- * ```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);
- * ```
- *
- * 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, so you need to retry switching to it
- *
- *
- * #### Configuration
- *
- * * `pollInterval` - default interval between retries in ms. 200 by default.
+ * @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'
@@ -207,80 +146,32 @@ async function retryTo(callback, maxTries, pollInterval = 200) {
 }
 
 /**
- * @module tryTo
- *
- * `tryTo` which all failed steps won't fail a test but will return true/false.
- * 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 { tryTo } = require('codeceptjs/effects');
- * ```
- *
- * Use `hopeThat` with assertions:
- * ```js
- * const result1 = await tryTo(() => I.see('Hello, user'));
- * const result2 = await tryTo(() => I.seeElement('.welcome'));
- * assert.ok(result1 && result2, 'Assertions were not successful');
- * ```
- *
- * ### Optional Click
- *
- * ```js
- * const { tryTo } = require('codeceptjs/effects');
- *
- * I.amOnPage('/');
- * await tryTo(() => I.click('Agree', '.cookies'));
- * ```
- *
- * 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 tryTo(() => 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 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 callback function.
- * @returns {Promise<boolean | any>} - Resolves to `true` if the assertion is successful, or `false` if it fails.
+ * @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.
  *
- * @example
- * // Multiple Conditional Assertions
- * const assert = require('assert');
- * const { tryTo } = require('codeceptjs/effects');
- *
- * const result1 = await tryTo(() => I.see('Hello, user'));
- * const result2 = await tryTo(() => I.seeElement('.welcome'));
- * assert.ok(result1 && result2, 'Assertions were not successful');
+ * @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
- * // Optional Click
- * const { tryTo } = require('codeceptjs/effects');
+ * 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.');
+ * }
  *
- * I.amOnPage('/');
- * await tryTo(() => I.click('Agree', '.cookies'));
+ * @throws Will handle errors internally, logging them and returning `false` as the result.
  */
 async function tryTo(callback) {
   if (store.dryRun) return

test/unit/effects_test.js

@@ -5,6 +5,7 @@ const recorder = require('../../lib/recorder')
 describe('effects', () => {
   describe('hopeThat', () => {
     beforeEach(() => {
+      recorder.reset()
       recorder.start()
     })
 
@@ -25,8 +26,32 @@ describe('effects', () => {
     })
   })
 
+  describe('tryTo', () => {
+    beforeEach(() => {
+      recorder.reset()
+      recorder.start()
+    })
+
+    it('should execute command on success', async () => {
+      const ok = await tryTo(() => recorder.add(() => 5))
+      expect(ok).to.be.equal(true)
+      return recorder.promise()
+    })
+
+    it('should execute command on fail', async () => {
+      const notOk = await tryTo(() =>
+        recorder.add(() => {
+          throw new Error('Ups')
+        }),
+      )
+      expect(false).is.equal(notOk)
+      return recorder.promise()
+    })
+  })
+
   describe('retryTo', () => {
     beforeEach(() => {
+      recorder.reset()
       recorder.start()
     })
 
@@ -66,26 +91,4 @@ describe('effects', () => {
       expect(errorCaught).is.true
     })
   })
-
-  describe('tryTo', () => {
-    beforeEach(() => {
-      recorder.start()
-    })
-
-    it('should execute command on success', async () => {
-      const ok = await tryTo(() => recorder.add(() => 5))
-      expect(true).is.equal(ok)
-      return recorder.promise()
-    })
-
-    it('should execute command on fail', async () => {
-      const notOk = await tryTo(() =>
-        recorder.add(() => {
-          throw new Error('Ups')
-        }),
-      )
-      expect(false).is.equal(notOk)
-      return recorder.promise()
-    })
-  })
 })