codeceptjs 4.0.0-beta.7.esm-aria → 4.0.0-beta.9.esm-aria

package/lib/helper/Puppeteer.js

@@ -36,6 +36,7 @@ import { highlightElement } from './scripts/highlightElement.js'
 import { blurElement } from './scripts/blurElement.js'
 import { dontSeeElementError, seeElementError, dontSeeElementInDOMError, seeElementInDOMError } from './errors/ElementAssertion.js'
 import { dontSeeTraffic, seeTraffic, grabRecordedNetworkTraffics, stopRecordingTraffic, flushNetworkTraffics } from './network/actions.js'
+import WebElement from '../element/WebElement.js'
 
 let puppeteer
 
@@ -74,7 +75,7 @@ const consoleLogStore = new Console()
  * @prop {boolean} [keepBrowserState=false] - keep browser state between tests when `restart` is set to false.
  * @prop {boolean} [keepCookies=false] - keep cookies between tests when `restart` is set to false.
  * @prop {number} [waitForAction=100] - how long to wait after click, doubleClick or PressKey actions in ms. Default: 100.
- * @prop {string} [waitForNavigation=load] - when to consider navigation succeeded. Possible options: `load`, `domcontentloaded`, `networkidle0`, `networkidle2`. See [Puppeteer API](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#pagewaitfornavigationoptions). Array values are accepted as well.
+ * @prop {string|string[]} [waitForNavigation=load] - when to consider navigation succeeded. Possible options: `load`, `domcontentloaded`, `networkidle0`, `networkidle2`. See [Puppeteer API](https://github.com/puppeteer/puppeteer/blob/main/docs/api/puppeteer.waitforoptions.md). Array values are accepted as well.
  * @prop {number} [pressKeyDelay=10] - delay between key presses in ms. Used when calling Puppeteers page.type(...) in fillField/appendField
  * @prop {number} [getPageTimeout=30000] - config option to set maximum navigation time in milliseconds. If the timeout is set to 0, then timeout will be disabled.
  * @prop {number} [waitForTimeout=1000] - default wait* timeout in ms.
@@ -82,13 +83,13 @@ const consoleLogStore = new Console()
  * @prop {string} [userAgent] - user-agent string.
  * @prop {boolean} [manualStart=false] - do not start browser before a test, start it manually inside a helper with `this.helpers["Puppeteer"]._startBrowser()`.
  * @prop {string} [browser=chrome] - can be changed to `firefox` when using [puppeteer-firefox](https://codecept.io/helpers/Puppeteer-firefox).
- * @prop {object} [chrome] - pass additional [Puppeteer run options](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#puppeteerlaunchoptions).
+ * @prop {object} [chrome] - pass additional [Puppeteer run options](https://github.com/puppeteer/puppeteer/blob/main/docs/api/puppeteer.launchoptions.md).
  * @prop {boolean} [highlightElement] - highlight the interacting elements. Default: false. Note: only activate under verbose mode (--verbose).
  */
 const config = {}
 
 /**
- * Uses [Google Chrome's Puppeteer](https://github.com/GoogleChrome/puppeteer) library to run tests inside headless Chrome.
+ * Uses [Google Chrome's Puppeteer](https://github.com/puppeteer/puppeteer) library to run tests inside headless Chrome.
  * Browser control is executed via DevTools Protocol (instead of Selenium).
  * This helper works with a browser out of the box with no additional tools required to install.
  *
@@ -361,6 +362,9 @@ class Puppeteer extends Helper {
   async _after() {
     if (!this.isRunning) return
 
+    // Clear popup state to prevent leakage between tests
+    popupStore.clear()
+
     // close other sessions
     const contexts = this.browser.browserContexts()
     const defaultCtx = contexts.shift()
@@ -432,9 +436,27 @@ class Puppeteer extends Helper {
         } else {
           this.activeSessionName = session
         }
+        
         const defaultCtx = this.browser.defaultBrowserContext()
-        const existingPages = defaultCtx.targets().filter(t => t.type() === 'page')
-        await this._setPage(await existingPages[0].page())
+        if (!defaultCtx) {
+          this.debug('Cannot restore session vars: default browser context is undefined')
+          return
+        }
+
+        try {
+          const existingPages = defaultCtx.targets().filter(t => t.type() === 'page')
+          if (existingPages && existingPages.length > 0) {
+            await this._setPage(await existingPages[0].page())
+            // Reset context-related variables to ensure clean state after session
+            this.context = await this.page
+            this.contextLocator = null
+          } else {
+            this.debug('Cannot restore session vars: no pages available')
+          }
+        } catch (err) {
+          this.debug(`Failed to restore session vars: ${err.message}`)
+          return
+        }
 
         return this._waitForAction()
       },
@@ -650,9 +672,14 @@ class Puppeteer extends Helper {
     }
   }
 
-  async _evaluateHandeInContext(...args) {
+  async _evaluateHandeInContext(fn, handle, ...args) {
+    // If handle is provided, evaluate directly on it to avoid "JavaScript world" errors
+    if (handle) {
+      return handle.evaluate(fn, ...args)
+    }
+    // Otherwise use the context
     const context = await this._getContext()
-    return context.evaluateHandle(...args)
+    return context.evaluateHandle(fn, ...args)
   }
 
   async _withinBegin(locator) {
@@ -671,16 +698,22 @@ class Puppeteer extends Helper {
       return
     }
 
-    const els = await this._locate(locator)
-    assertElementExists(els, locator)
-    this.context = els[0]
+    const el = await this._locateElement(locator)
+    if (!el) {
+      throw new ElementNotFound(locator, 'Element for within context')
+    }
+    this.context = el
 
     this.withinLocator = new Locator(locator)
   }
 
   async _withinEnd() {
     this.withinLocator = null
-    this.context = await this.page.mainFrame().$('body')
+    if (this.page && !this.page.isClosed?.()) {
+      this.context = await this.page.mainFrame().$('body')
+    } else {
+      this.context = null
+    }
   }
 
   _extractDataFromPerformanceTiming(timing, ...dataNames) {
@@ -781,11 +814,13 @@ class Puppeteer extends Helper {
    * {{ react }}
    */
   async moveCursorTo(locator, offsetX = 0, offsetY = 0) {
-    const els = await this._locate(locator)
-    assertElementExists(els, locator)
+    const el = await this._locateElement(locator)
+    if (!el) {
+      throw new ElementNotFound(locator, 'Element to move cursor to')
+    }
 
     // Use manual mouse.move instead of .hover() so the offset can be added to the coordinates
-    const { x, y } = await getClickablePoint(els[0])
+    const { x, y } = await getClickablePoint(el)
     await this.page.mouse.move(x + offsetX, y + offsetY)
     return this._waitForAction()
   }
@@ -795,9 +830,10 @@ class Puppeteer extends Helper {
    *
    */
   async focus(locator) {
-    const els = await this._locate(locator)
-    assertElementExists(els, locator, 'Element to focus')
-    const el = els[0]
+    const el = await this._locateElement(locator)
+    if (!el) {
+      throw new ElementNotFound(locator, 'Element to focus')
+    }
 
     await el.click()
     await el.focus()
@@ -809,10 +845,12 @@ class Puppeteer extends Helper {
    *
    */
   async blur(locator) {
-    const els = await this._locate(locator)
-    assertElementExists(els, locator, 'Element to blur')
+    const el = await this._locateElement(locator)
+    if (!el) {
+      throw new ElementNotFound(locator, 'Element to blur')
+    }
 
-    await blurElement(els[0], this.page)
+    await blurElement(el, this.page)
     return this._waitForAction()
   }
 
@@ -861,11 +899,12 @@ class Puppeteer extends Helper {
     }
 
     if (locator) {
-      const els = await this._locate(locator)
-      assertElementExists(els, locator, 'Element')
-      const el = els[0]
+      const el = await this._locateElement(locator)
+      if (!el) {
+        throw new ElementNotFound(locator, 'Element to scroll into view')
+      }
       await el.evaluate(el => el.scrollIntoView())
-      const elementCoordinates = await getClickablePoint(els[0])
+      const elementCoordinates = await getClickablePoint(el)
       await this.executeScript((x, y) => window.scrollBy(x, y), elementCoordinates.x + offsetX, elementCoordinates.y + offsetY)
     } else {
       await this.executeScript((x, y) => window.scrollTo(x, y), offsetX, offsetY)
@@ -933,6 +972,21 @@ class Puppeteer extends Helper {
     return findElements.call(this, context, locator)
   }
 
+  /**
+   * Get single element by different locator types, including strict locator
+   * Should be used in custom helpers:
+   *
+   * ```js
+   * const element = await this.helpers['Puppeteer']._locateElement({name: 'password'});
+   * ```
+   *
+   * {{ react }}
+   */
+  async _locateElement(locator) {
+    const context = await this.context
+    return findElement.call(this, context, locator)
+  }
+
   /**
    * Find a checkbox by providing human-readable text:
    * NOTE: Assumes the checkable element exists
@@ -944,7 +998,9 @@ class Puppeteer extends Helper {
   async _locateCheckable(locator, providedContext = null) {
     const context = providedContext || (await this._getContext())
     const els = await findCheckable.call(this, locator, context)
-    assertElementExists(els[0], locator, 'Checkbox or radio')
+    if (!els || els.length === 0) {
+      throw new ElementNotFound(locator, 'Checkbox or radio')
+    }
     return els[0]
   }
 
@@ -976,7 +1032,20 @@ class Puppeteer extends Helper {
    *
    */
   async grabWebElements(locator) {
-    return this._locate(locator)
+    const elements = await this._locate(locator)
+    return elements.map(element => new WebElement(element, this))
+  }
+
+  /**
+   * {{> grabWebElement }}
+   *
+   */
+  async grabWebElement(locator) {
+    const elements = await this._locate(locator)
+    if (elements.length === 0) {
+      throw new ElementNotFound(locator, 'Element')
+    }
+    return new WebElement(elements[0], this)
   }
 
   async grabWebElement(locator) {
@@ -1146,7 +1215,7 @@ class Puppeteer extends Helper {
    *
    * {{ react }}
    */
-  async click(locator, context = null) {
+  async click(locator = '//body', context = null) {
     return proceedClick.call(this, locator, context)
   }
 
@@ -1306,6 +1375,49 @@ class Puppeteer extends Helper {
     return proceedClick.call(this, locator, context, { button: 'right' })
   }
 
+  /**
+   * Performs click at specific coordinates.
+   * If locator is provided, the coordinates are relative to the element.
+   * If locator is not provided, the coordinates are global page coordinates.
+   *
+   * ```js
+   * // Click at global coordinates (100, 200)
+   * I.clickXY(100, 200);
+   *
+   * // Click at coordinates (50, 30) relative to element
+   * I.clickXY('#someElement', 50, 30);
+   * ```
+   *
+   * @param {CodeceptJS.LocatorOrString|number} locator Element to click on or X coordinate if no element.
+   * @param {number} [x] X coordinate relative to element, or Y coordinate if locator is a number.
+   * @param {number} [y] Y coordinate relative to element.
+   * @returns {Promise<void>}
+   */
+  async clickXY(locator, x, y) {
+    // If locator is a number, treat it as global X coordinate
+    if (typeof locator === 'number') {
+      const globalX = locator
+      const globalY = x
+      await this.page.mouse.click(globalX, globalY)
+      return this._waitForAction()
+    }
+
+    // Locator is provided, click relative to element
+    const els = await this._locate(locator)
+    assertElementExists(els, locator, 'Element to click')
+
+    const box = await els[0].boundingBox()
+    if (!box) {
+      throw new Error(`Element ${locator} is not visible or has no bounding box`)
+    }
+
+    const absoluteX = box.x + x
+    const absoluteY = box.y + y
+
+    await this.page.mouse.click(absoluteX, absoluteY)
+    return this._waitForAction()
+  }
+
   /**
    * {{> checkOption }}
    */
@@ -1381,7 +1493,7 @@ class Puppeteer extends Helper {
   }
 
   /**
-   * _Note:_ Shortcuts like `'Meta'` + `'A'` do not work on macOS ([GoogleChrome/puppeteer#1313](https://github.com/GoogleChrome/puppeteer/issues/1313)).
+   * _Note:_ Shortcuts like `'Meta'` + `'A'` do not work on macOS ([puppeteer/puppeteer#1313](https://github.com/puppeteer/puppeteer/issues/1313)).
    *
    * {{> pressKeyWithKeyNormalization }}
    */
@@ -1840,7 +1952,7 @@ class Puppeteer extends Helper {
    */
   async grabHTMLFromAll(locator) {
     const els = await this._locate(locator)
-    const values = await Promise.all(els.map(el => el.evaluate(element => element.innerHTML, el)))
+    const values = await Promise.all(els.map(el => el.evaluate(element => element.innerHTML)))
     return values
   }
 
@@ -1863,7 +1975,7 @@ class Puppeteer extends Helper {
    */
   async grabCssPropertyFromAll(locator, cssProperty) {
     const els = await this._locate(locator)
-    const res = await Promise.all(els.map(el => el.evaluate(el => JSON.parse(JSON.stringify(getComputedStyle(el))), el)))
+    const res = await Promise.all(els.map(el => el.evaluate(el => JSON.parse(JSON.stringify(getComputedStyle(el))))))
     const cssValues = res.map(props => props[toCamelCase(cssProperty)])
 
     return cssValues
@@ -1988,7 +2100,7 @@ class Puppeteer extends Helper {
     const array = []
     for (let index = 0; index < els.length; index++) {
       const a = await this._evaluateHandeInContext((el, attr) => el[attr] || el.getAttribute(attr), els[index], attr)
-      array.push(await a.jsonValue())
+      array.push(a)
     }
     return array
   }
@@ -2030,6 +2142,12 @@ class Puppeteer extends Helper {
 
     this.debug(`Screenshot is saving to ${outputFile}`)
 
+    // Safety check: ensure page exists and is not closed
+    if (!this.page || this.page.isClosed?.()) {
+      this.debugSection('Screenshot', 'Page is not available, skipping screenshot')
+      return
+    }
+
     await this.page.screenshot({
       path: outputFile,
       fullPage: fullPageOption,
@@ -2043,7 +2161,7 @@ class Puppeteer extends Helper {
 
         this.debug(`${sessionName} - Screenshot is saving to ${outputFile}`)
 
-        if (activeSessionPage) {
+        if (activeSessionPage && !activeSessionPage.isClosed?.()) {
           await activeSessionPage.screenshot({
             path: outputFile,
             fullPage: fullPageOption,
@@ -2184,12 +2302,13 @@ class Puppeteer extends Helper {
    * {{> waitForClickable }}
    */
   async waitForClickable(locator, waitTimeout) {
-    const els = await this._locate(locator)
-    assertElementExists(els, locator)
+    const el = await this._locateElement(locator)
+    if (!el) {
+      throw new ElementNotFound(locator, 'Element to wait for clickable')
+    }
 
-    return this.waitForFunction(isElementClickable, [els[0]], waitTimeout).catch(async e => {
-      const errorMessage = e?.message || String(e)
-      if (/Waiting failed/i.test(errorMessage) || /failed: timeout/i.test(errorMessage)) {
+    return this.waitForFunction(isElementClickable, [el], waitTimeout).catch(async e => {
+      if (/Waiting failed/i.test(e.message) || /failed: timeout/i.test(e.message)) {
         throw new Error(`element ${new Locator(locator).toString()} still not clickable after ${waitTimeout || this.options.waitForTimeout / 1000} sec`)
       } else {
         throw e
@@ -2494,7 +2613,7 @@ class Puppeteer extends Helper {
   /**
    * Waits for navigation to finish. By default, takes configured `waitForNavigation` option.
    *
-   * See [Puppeteer's reference](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#pagewaitfornavigationoptions)
+   * See [Puppeteer's reference](https://github.com/puppeteer/puppeteer/blob/main/docs/api/puppeteer.page.waitfornavigation.md)
    *
    * @param {*} opts
    */
@@ -2622,7 +2741,8 @@ class Puppeteer extends Helper {
    *
    * {{> stopRecordingTraffic }}
    */
-  stopRecordingTraffic() {
+  async stopRecordingTraffic() {
+    await this.page.setRequestInterception(false)
     stopRecordingTraffic.call(this)
   }
 
@@ -2760,27 +2880,98 @@ class Puppeteer extends Helper {
   }
 }
 
-async function findElements(matcher, locator) {
-  const matchedLocator = new Locator(locator, 'css')
-
-  if (matchedLocator.type === 'react') return findReactElements.call(this, matchedLocator)
-  if (matchedLocator.isRole()) return findByRole.call(this, matcher, matchedLocator)
-
-  if (!matchedLocator.isXPath()) return matcher.$$(matchedLocator.simplify())
+export default Puppeteer
 
-  // Handle backward compatibility for different Puppeteer versions
-  // Puppeteer >= 19.4.0 uses xpath/ syntax, older versions use $x
-  try {
-    // Try the new xpath syntax first (for Puppeteer >= 19.4.0)
-    return await matcher.$$(`xpath/${matchedLocator.value}`)
-  } catch (error) {
-    // Fall back to the old $x method for older Puppeteer versions
-    if (matcher.$x && typeof matcher.$x === 'function') {
-      return await matcher.$x(matchedLocator.value)
+/**
+ * Find elements using Puppeteer's native element discovery methods
+ * Note: Unlike Playwright, Puppeteer's Locator API doesn't have .all() method for multiple elements
+ * @param {Object} matcher - Puppeteer context to search within
+ * @param {Object|string} locator - Locator specification
+ * @returns {Promise<Array>} Array of ElementHandle objects
+ */
+async function findElements(matcher, locator) {
+  // Check if locator is a Locator object with react type, or a raw object with react property
+  const isReactLocator = locator.type === 'react' || (locator.locator && locator.locator.react) || locator.react
+  if (isReactLocator) return findReactElements.call(this, locator)
+  
+  locator = new Locator(locator, 'css')
+  
+  // Check if locator is a role locator and call findByRole
+  if (locator.isRole()) return findByRole.call(this, matcher, locator)
+
+  // Use proven legacy approach - Puppeteer Locator API doesn't have .all() method
+  if (!locator.isXPath()) return matcher.$$(locator.simplify())
+  
+  // puppeteer version < 19.4.0 is no longer supported. This one is backward support.
+  if (puppeteer.default?.defaultBrowserRevision) {
+    return matcher.$$(`xpath/${locator.value}`)
+  }
+  
+  // For Puppeteer 24.x+, $x method was removed
+  // Use ::-p-xpath() selector syntax
+  // Check if matcher has $$ method (Page, Frame, or ElementHandle)
+  if (matcher && typeof matcher.$$ === 'function') {
+    const xpathSelector = `::-p-xpath(${locator.value})`
+    try {
+      return await matcher.$$(xpathSelector)
+    } catch (e) {
+      // XPath selector may not work on ElementHandle, fall through to evaluate method
+      this.debug && this.debug(`XPath selector failed on ${matcher.constructor?.name}: ${e.message}`)
     }
-    // If both methods fail, re-throw the original error
-    throw error
   }
+  
+  // ElementHandles don't support XPath directly  // Search within the element by making XPath relative
+  try {
+    const relativeXPath = locator.value.startsWith('.//') ? locator.value : `.//${locator.value.replace(/^\/\//, '')}`
+    
+    // Use the element as context by evaluating XPath from it
+    const elements = await matcher.evaluateHandle((element, xpath) => {
+      const iterator = document.evaluate(xpath, element, null, XPathResult.ORDERED_NODE_SNAPSHOT_TYPE, null)
+      const results = []
+      for (let i = 0; i < iterator.snapshotLength; i++) {
+        results.push(iterator.snapshotItem(i))
+      }
+      return results
+    }, relativeXPath)
+    
+    // Convert JSHandle to array of ElementHandles
+    const properties = await elements.getProperties()
+    return Array.from(properties.values())
+  } catch (e) {
+    this.debug(`XPath within element failed: ${e.message}`)
+  }
+  
+  // Fallback: return empty array
+  return []
+}
+
+/**
+ * Find a single element using Puppeteer's native element discovery methods
+ * Note: Puppeteer Locator API doesn't have .first() method like Playwright
+ * @param {Object} matcher - Puppeteer context to search within
+ * @param {Object|string} locator - Locator specification
+ * @returns {Promise<Object>} Single ElementHandle object
+ */
+async function findElement(matcher, locator) {
+  if (locator.react) return findReactElements.call(this, locator)
+  locator = new Locator(locator, 'css')
+  
+  // Check if locator is a role locator and call findByRole
+  if (locator.isRole()) {
+    const elements = await findByRole.call(this, matcher, locator)
+    return elements[0]
+  }
+
+  // Use proven legacy approach - Puppeteer Locator API doesn't have .first() method
+  if (!locator.isXPath()) {
+    const elements = await matcher.$$(locator.simplify())
+    return elements[0]
+  }
+  
+  // For XPath in Puppeteer 24.x+, use the same approach as findElements
+  // $x method was removed, so we use ::-p-xpath() or fallback
+  const elements = await findElements.call(this, matcher, locator)
+  return elements[0]
 }
 
 async function proceedClick(locator, context = null, options = {}) {
@@ -2970,15 +3161,19 @@ async function findFields(locator) {
 }
 
 async function proceedDragAndDrop(sourceLocator, destinationLocator) {
-  const src = await this._locate(sourceLocator)
-  assertElementExists(src, sourceLocator, 'Source Element')
+  const src = await this._locateElement(sourceLocator)
+  if (!src) {
+    throw new ElementNotFound(sourceLocator, 'Source Element')
+  }
 
-  const dst = await this._locate(destinationLocator)
-  assertElementExists(dst, destinationLocator, 'Destination Element')
+  const dst = await this._locateElement(destinationLocator)
+  if (!dst) {
+    throw new ElementNotFound(destinationLocator, 'Destination Element')
+  }
 
-  // Note: Using public api .getClickablePoint becaues the .BoundingBox does not take into account iframe offsets
-  const dragSource = await getClickablePoint(src[0])
-  const dragDestination = await getClickablePoint(dst[0])
+  // Note: Using public api .getClickablePoint because the .BoundingBox does not take into account iframe offsets
+  const dragSource = await getClickablePoint(src)
+  const dragDestination = await getClickablePoint(dst)
 
   // Drag start point
   await this.page.mouse.move(dragSource.x, dragSource.y, { steps: 5 })
@@ -3148,7 +3343,7 @@ async function getClickablePoint(el) {
 }
 
 // List of key values to key definitions
-// https://github.com/GoogleChrome/puppeteer/blob/v1.20.0/lib/USKeyboardLayout.js
+// https://github.com/puppeteer/puppeteer/blob/v1.20.0/lib/USKeyboardLayout.js
 const keyDefinitionMap = {
   0: 'Digit0',
   1: 'Digit1',
@@ -3226,7 +3421,9 @@ function _waitForElement(locator, options) {
 }
 
 async function findReactElements(locator) {
-  const resolved = toLocatorConfig(locator, 'react')
+  // Handle both Locator objects and raw locator objects
+  const resolved = locator.locator ? locator.locator : toLocatorConfig(locator, 'react')
+  this.debug(`Finding React elements: ${JSON.stringify(resolved)}`)
 
   // Use createRequire to access require.resolve in ESM
   const { createRequire } = await import('module')
@@ -3341,4 +3538,3 @@ function createRoleTextMatcher(expected, exactMatch) {
   return value => typeof value === 'string' && value.includes(target)
 }
 
-export { Puppeteer as default }

package/lib/helper/REST.js

@@ -298,6 +298,27 @@ class REST extends Helper {
     return this._executeRequest(request)
   }
 
+  /**
+   * Send HEAD request to REST API
+   *
+   * ```js
+   * I.sendHeadRequest('/api/users.json');
+   * ```
+   *
+   * @param {*} url
+   * @param {object} [headers={}] - the headers object to be sent. By default, it is sent as an empty object
+   *
+   * @returns {Promise<*>} response
+   */
+  async sendHeadRequest(url, headers = {}) {
+    const request = {
+      baseURL: this._url(url),
+      method: 'HEAD',
+      headers,
+    }
+    return this._executeRequest(request)
+  }
+
   /**
    * Sends POST request to API.
    *