codeceptjs 4.0.0-beta.1 → 4.0.0-beta.11.esm-aria

package/lib/effects.js

@@ -0,0 +1,307 @@
+import recorder from './recorder.js'
+import output from './output.js'
+import store from './store.js'
+import event from './event.js'
+import container from './container.js'
+import MetaStep from './step/meta.js'
+import { isAsyncFunction } from './utils.js'
+
+/**
+ * @param {CodeceptJS.LocatorOrString}  context
+ * @param {Function}  fn
+ * @return {Promise<*> | undefined}
+ */
+function within(context, fn) {
+  const helpers = store.dryRun ? {} : container.helpers()
+  const locator = typeof context === 'object' ? JSON.stringify(context) : context
+
+  return recorder.add(
+    'register within wrapper',
+    () => {
+      const metaStep = new WithinStep(locator, fn)
+      const defineMetaStep = step => (step.metaStep = metaStep)
+      recorder.session.start('within')
+
+      event.dispatcher.prependListener(event.step.before, defineMetaStep)
+
+      Object.keys(helpers).forEach(helper => {
+        if (helpers[helper]._withinBegin) recorder.add(`[${helper}] start within`, () => helpers[helper]._withinBegin(context))
+      })
+
+      const finalize = () => {
+        event.dispatcher.removeListener(event.step.before, defineMetaStep)
+        recorder.add('Finalize session within session', () => {
+          output.stepShift = 1
+          recorder.session.restore('within')
+        })
+      }
+      const finishHelpers = () => {
+        Object.keys(helpers).forEach(helper => {
+          if (helpers[helper]._withinEnd) recorder.add(`[${helper}] finish within`, () => helpers[helper]._withinEnd())
+        })
+      }
+
+      if (isAsyncFunction(fn)) {
+        return fn()
+          .then(res => {
+            finishHelpers()
+            finalize()
+            return recorder.promise().then(() => res)
+          })
+          .catch(e => {
+            finalize()
+            recorder.throw(e)
+          })
+      }
+
+      let res
+      try {
+        res = fn()
+      } catch (err) {
+        recorder.throw(err)
+      } finally {
+        finishHelpers()
+        recorder.catch(err => {
+          output.stepShift = 1
+          throw err
+        })
+      }
+      finalize()
+      return recorder.promise().then(() => res)
+    },
+    false,
+    false,
+  )
+}
+
+class WithinStep extends MetaStep {
+  constructor(locator, fn) {
+    super('Within')
+    this.args = [locator]
+  }
+
+  toString() {
+    return `${this.prefix}Within ${this.humanizeArgs()}${this.suffix}`
+  }
+}
+
+/**
+ * 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()
+        output.debug(`Unsuccessful assertion > ${msg}`)
+        event.dispatcher.once(event.test.finished, test => {
+          if (!test.notes) test.notes = []
+          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 { retryTo } = 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) {
+          output.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) output.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()
+        output.debug(`Unsuccessful try > ${msg}`)
+        recorder.session.restore(sessionName)
+        return result
+      })
+      return recorder.add(
+        'result',
+        () => {
+          store.autoRetries = isAutoRetriesEnabled
+          return result
+        },
+        true,
+        false,
+      )
+    },
+    false,
+    false,
+  )
+}
+
+export { hopeThat, retryTo, tryTo, within }
+
+export default {
+  hopeThat,
+  retryTo,
+  tryTo,
+  within,
+}

package/lib/element/WebElement.js

@@ -0,0 +1,327 @@
+import assert from 'assert'
+
+/**
+ * Unified WebElement class that wraps native element instances from different helpers
+ * and provides a consistent API across all supported helpers (Playwright, WebDriver, Puppeteer).
+ */
+class WebElement {
+  constructor(element, helper) {
+    this.element = element
+    this.helper = helper
+    this.helperType = this._detectHelperType(helper)
+  }
+
+  _detectHelperType(helper) {
+    if (!helper) return 'unknown'
+
+    const className = helper.constructor.name
+    if (className === 'Playwright') return 'playwright'
+    if (className === 'WebDriver') return 'webdriver'
+    if (className === 'Puppeteer') return 'puppeteer'
+
+    return 'unknown'
+  }
+
+  /**
+   * Get the native element instance
+   * @returns {ElementHandle|WebElement|ElementHandle} Native element
+   */
+  getNativeElement() {
+    return this.element
+  }
+
+  /**
+   * Get the helper instance
+   * @returns {Helper} Helper instance
+   */
+  getHelper() {
+    return this.helper
+  }
+
+  /**
+   * Get text content of the element
+   * @returns {Promise<string>} Element text content
+   */
+  async getText() {
+    switch (this.helperType) {
+      case 'playwright':
+        return this.element.textContent()
+      case 'webdriver':
+        return this.element.getText()
+      case 'puppeteer':
+        return this.element.evaluate(el => el.textContent)
+      default:
+        throw new Error(`Unsupported helper type: ${this.helperType}`)
+    }
+  }
+
+  /**
+   * Get attribute value of the element
+   * @param {string} name Attribute name
+   * @returns {Promise<string|null>} Attribute value
+   */
+  async getAttribute(name) {
+    switch (this.helperType) {
+      case 'playwright':
+        return this.element.getAttribute(name)
+      case 'webdriver':
+        return this.element.getAttribute(name)
+      case 'puppeteer':
+        return this.element.evaluate((el, attrName) => el.getAttribute(attrName), name)
+      default:
+        throw new Error(`Unsupported helper type: ${this.helperType}`)
+    }
+  }
+
+  /**
+   * Get property value of the element
+   * @param {string} name Property name
+   * @returns {Promise<any>} Property value
+   */
+  async getProperty(name) {
+    switch (this.helperType) {
+      case 'playwright':
+        return this.element.evaluate((el, propName) => el[propName], name)
+      case 'webdriver':
+        return this.element.getProperty(name)
+      case 'puppeteer':
+        return this.element.evaluate((el, propName) => el[propName], name)
+      default:
+        throw new Error(`Unsupported helper type: ${this.helperType}`)
+    }
+  }
+
+  /**
+   * Get innerHTML of the element
+   * @returns {Promise<string>} Element innerHTML
+   */
+  async getInnerHTML() {
+    switch (this.helperType) {
+      case 'playwright':
+        return this.element.innerHTML()
+      case 'webdriver':
+        return this.element.getProperty('innerHTML')
+      case 'puppeteer':
+        return this.element.evaluate(el => el.innerHTML)
+      default:
+        throw new Error(`Unsupported helper type: ${this.helperType}`)
+    }
+  }
+
+  /**
+   * Get value of the element (for input elements)
+   * @returns {Promise<string>} Element value
+   */
+  async getValue() {
+    switch (this.helperType) {
+      case 'playwright':
+        return this.element.inputValue()
+      case 'webdriver':
+        return this.element.getValue()
+      case 'puppeteer':
+        return this.element.evaluate(el => el.value)
+      default:
+        throw new Error(`Unsupported helper type: ${this.helperType}`)
+    }
+  }
+
+  /**
+   * Check if element is visible
+   * @returns {Promise<boolean>} True if element is visible
+   */
+  async isVisible() {
+    switch (this.helperType) {
+      case 'playwright':
+        return this.element.isVisible()
+      case 'webdriver':
+        return this.element.isDisplayed()
+      case 'puppeteer':
+        return this.element.evaluate(el => {
+          const style = window.getComputedStyle(el)
+          return style.display !== 'none' && style.visibility !== 'hidden' && style.opacity !== '0'
+        })
+      default:
+        throw new Error(`Unsupported helper type: ${this.helperType}`)
+    }
+  }
+
+  /**
+   * Check if element is enabled
+   * @returns {Promise<boolean>} True if element is enabled
+   */
+  async isEnabled() {
+    switch (this.helperType) {
+      case 'playwright':
+        return this.element.isEnabled()
+      case 'webdriver':
+        return this.element.isEnabled()
+      case 'puppeteer':
+        return this.element.evaluate(el => !el.disabled)
+      default:
+        throw new Error(`Unsupported helper type: ${this.helperType}`)
+    }
+  }
+
+  /**
+   * Check if element exists in DOM
+   * @returns {Promise<boolean>} True if element exists
+   */
+  async exists() {
+    try {
+      switch (this.helperType) {
+        case 'playwright':
+          // For Playwright, if we have the element, it exists
+          return await this.element.evaluate(el => !!el)
+        case 'webdriver':
+          // For WebDriver, if we have the element, it exists
+          return true
+        case 'puppeteer':
+          // For Puppeteer, if we have the element, it exists
+          return await this.element.evaluate(el => !!el)
+        default:
+          throw new Error(`Unsupported helper type: ${this.helperType}`)
+      }
+    } catch (e) {
+      return false
+    }
+  }
+
+  /**
+   * Get bounding box of the element
+   * @returns {Promise<Object>} Bounding box with x, y, width, height properties
+   */
+  async getBoundingBox() {
+    switch (this.helperType) {
+      case 'playwright':
+        return this.element.boundingBox()
+      case 'webdriver':
+        const rect = await this.element.getRect()
+        return {
+          x: rect.x,
+          y: rect.y,
+          width: rect.width,
+          height: rect.height,
+        }
+      case 'puppeteer':
+        return this.element.boundingBox()
+      default:
+        throw new Error(`Unsupported helper type: ${this.helperType}`)
+    }
+  }
+
+  /**
+   * Click the element
+   * @param {Object} options Click options
+   * @returns {Promise<void>}
+   */
+  async click(options = {}) {
+    switch (this.helperType) {
+      case 'playwright':
+        return this.element.click(options)
+      case 'webdriver':
+        return this.element.click()
+      case 'puppeteer':
+        return this.element.click(options)
+      default:
+        throw new Error(`Unsupported helper type: ${this.helperType}`)
+    }
+  }
+
+  /**
+   * Type text into the element
+   * @param {string} text Text to type
+   * @param {Object} options Type options
+   * @returns {Promise<void>}
+   */
+  async type(text, options = {}) {
+    switch (this.helperType) {
+      case 'playwright':
+        return this.element.type(text, options)
+      case 'webdriver':
+        return this.element.setValue(text)
+      case 'puppeteer':
+        return this.element.type(text, options)
+      default:
+        throw new Error(`Unsupported helper type: ${this.helperType}`)
+    }
+  }
+
+  /**
+   * Find first child element matching the locator
+   * @param {string|Object} locator Element locator
+   * @returns {Promise<WebElement|null>} WebElement instance or null if not found
+   */
+  async $(locator) {
+    let childElement
+
+    switch (this.helperType) {
+      case 'playwright':
+        childElement = await this.element.$(this._normalizeLocator(locator))
+        break
+      case 'webdriver':
+        try {
+          childElement = await this.element.$(this._normalizeLocator(locator))
+        } catch (e) {
+          return null
+        }
+        break
+      case 'puppeteer':
+        childElement = await this.element.$(this._normalizeLocator(locator))
+        break
+      default:
+        throw new Error(`Unsupported helper type: ${this.helperType}`)
+    }
+
+    return childElement ? new WebElement(childElement, this.helper) : null
+  }
+
+  /**
+   * Find all child elements matching the locator
+   * @param {string|Object} locator Element locator
+   * @returns {Promise<WebElement[]>} Array of WebElement instances
+   */
+  async $$(locator) {
+    let childElements
+
+    switch (this.helperType) {
+      case 'playwright':
+        childElements = await this.element.$$(this._normalizeLocator(locator))
+        break
+      case 'webdriver':
+        childElements = await this.element.$$(this._normalizeLocator(locator))
+        break
+      case 'puppeteer':
+        childElements = await this.element.$$(this._normalizeLocator(locator))
+        break
+      default:
+        throw new Error(`Unsupported helper type: ${this.helperType}`)
+    }
+
+    return childElements.map(el => new WebElement(el, this.helper))
+  }
+
+  /**
+   * Normalize locator for element search
+   * @param {string|Object} locator Locator to normalize
+   * @returns {string} Normalized CSS selector
+   * @private
+   */
+  _normalizeLocator(locator) {
+    if (typeof locator === 'string') {
+      return locator
+    }
+
+    if (typeof locator === 'object') {
+      // Handle CodeceptJS locator objects
+      if (locator.css) return locator.css
+      if (locator.xpath) return locator.xpath
+      if (locator.id) return `#${locator.id}`
+      if (locator.name) return `[name="${locator.name}"]`
+      if (locator.className) return `.${locator.className}`
+    }
+
+    return locator.toString()
+  }
+}
+
+export default WebElement