Function findElements

lib/helper/Puppeteer.js:2995–3052

* 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 * @return

(matcher, locator)

 * @returns {Promise<Array>} Array of ElementHandle objects
 */
async function findElements(matcher, 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)

  // Handle shadow DOM locators with >>> deep descendant combinator
  // { shadow: ['my-app', 'recipe-hello', 'button'] } => 'my-app >>> recipe-hello >>> button'
  if (locator.isShadow()) {
    const shadowSelector = locator.value.join(' >>> ')
    return matcher.$$(shadowSelector)
  }

  // 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}`)
    }
  }
  
  // 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 []
}