codeceptjs 4.0.0-beta.5 → 4.0.0-beta.6.esm-aria

package/lib/helper/Puppeteer.js

@@ -1,21 +1,19 @@
-const axios = require('axios')
-const fs = require('fs')
-const fsExtra = require('fs-extra')
-const path = require('path')
-
-const Helper = require('@codeceptjs/helper')
-const { v4: uuidv4 } = require('uuid')
-const promiseRetry = require('promise-retry')
-const Locator = require('../locator')
-const recorder = require('../recorder')
-const store = require('../store')
-const stringIncludes = require('../assert/include').includes
-const { urlEquals } = require('../assert/equal')
-const { equals } = require('../assert/equal')
-const { empty } = require('../assert/empty')
-const { truth } = require('../assert/truth')
-const isElementClickable = require('./scripts/isElementClickable')
-const {
+import axios from 'axios'
+import fs from 'fs'
+import fsExtra from 'fs-extra'
+import path from 'path'
+import Helper from '@codeceptjs/helper'
+import { v4 as uuidv4 } from 'uuid'
+import promiseRetry from 'promise-retry'
+import Locator from '../locator.js'
+import recorder from '../recorder.js'
+import store from '../store.js'
+import { includes as stringIncludes } from '../assert/include.js'
+import { urlEquals, equals } from '../assert/equal.js'
+import { empty } from '../assert/empty.js'
+import { truth } from '../assert/truth.js'
+import isElementClickable from './scripts/isElementClickable.js'
+import {
   xpathLocator,
   ucfirst,
   fileExists,
@@ -28,19 +26,31 @@ const {
   isModifierKey,
   requireWithFallback,
   normalizeSpacesInString,
-} = require('../utils')
-const { isColorProperty, convertColorToRGBA } = require('../colorUtils')
-const ElementNotFound = require('./errors/ElementNotFound')
-const RemoteBrowserConnectionRefused = require('./errors/RemoteBrowserConnectionRefused')
-const Popup = require('./extras/Popup')
-const Console = require('./extras/Console')
-const { highlightElement } = require('./scripts/highlightElement')
-const { blurElement } = require('./scripts/blurElement')
-const { dontSeeElementError, seeElementError, dontSeeElementInDOMError, seeElementInDOMError } = require('./errors/ElementAssertion')
-const { dontSeeTraffic, seeTraffic, grabRecordedNetworkTraffics, stopRecordingTraffic, flushNetworkTraffics } = require('./network/actions')
-const WebElement = require('../element/WebElement')
+} from '../utils.js'
+import { isColorProperty, convertColorToRGBA } from '../colorUtils.js'
+import ElementNotFound from './errors/ElementNotFound.js'
+import RemoteBrowserConnectionRefused from './errors/RemoteBrowserConnectionRefused.js'
+import Popup from './extras/Popup.js'
+import Console from './extras/Console.js'
+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'
 
 let puppeteer
+
+/**
+ * Wraps error objects that don't have a proper message property
+ * This is needed for ESM compatibility with Puppeteer error handling
+ */
+function wrapError(e) {
+  if (e && typeof e === 'object' && !e.message) {
+    const err = new Error(String(e))
+    err.stack = e.stack
+    return err
+  }
+  return e
+}
 let perfTiming
 const popupStore = new Popup()
 const consoleLogStore = new Console()
@@ -214,7 +224,7 @@ class Puppeteer extends Helper {
   constructor(config) {
     super(config)
 
-    puppeteer = requireWithFallback('puppeteer', 'puppeteer-core')
+    // puppeteer will be loaded dynamically in _init method
     // set defaults
     this.isRemoteBrowser = false
     this.isRunning = false
@@ -294,13 +304,34 @@ class Puppeteer extends Helper {
 
   static _checkRequirements() {
     try {
-      requireWithFallback('puppeteer', 'puppeteer-core')
+      // In ESM, puppeteer will be checked via dynamic import in _init
+      // The import will fail at module load time if puppeteer is missing
+      return null
     } catch (e) {
       return ['puppeteer']
     }
   }
 
-  _init() {}
+  async _init() {
+    // Load puppeteer dynamically with fallback
+    if (!puppeteer) {
+      try {
+        const puppeteerModule = await import('puppeteer')
+        puppeteer = puppeteerModule.default || puppeteerModule
+        this.debugSection('Puppeteer', `Loaded puppeteer successfully, launch available: ${!!puppeteer.launch}`)
+      } catch (e) {
+        try {
+          const puppeteerModule = await import('puppeteer-core')
+          puppeteer = puppeteerModule.default || puppeteerModule
+          this.debugSection('Puppeteer', `Loaded puppeteer-core successfully, launch available: ${!!puppeteer.launch}`)
+        } catch (e2) {
+          throw new Error('Neither puppeteer nor puppeteer-core could be loaded. Please install one of them.')
+        }
+      }
+    } else {
+      this.debugSection('Puppeteer', `Puppeteer already loaded, launch available: ${!!puppeteer.launch}`)
+    }
+  }
 
   _beforeSuite() {
     if (!this.options.restart && !this.options.manualStart && !this.isRunning) {
@@ -563,6 +594,12 @@ class Puppeteer extends Helper {
   }
 
   async _startBrowser() {
+    this.debugSection('Puppeteer', `Starting browser. Puppeteer available: ${!!puppeteer}, launch available: ${!!puppeteer?.launch}`)
+
+    if (!puppeteer) {
+      throw new Error('Puppeteer is not loaded. Make sure _init() was called before _startBrowser()')
+    }
+
     if (this.isRemoteBrowser) {
       try {
         this.browser = await puppeteer.connect(this.puppeteerOptions)
@@ -634,11 +671,9 @@ class Puppeteer extends Helper {
       return
     }
 
-    const el = await this._locateElement(locator)
-    if (!el) {
-      throw new ElementNotFound(locator, 'Element for within context')
-    }
-    this.context = el
+    const els = await this._locate(locator)
+    assertElementExists(els, locator)
+    this.context = els[0]
 
     this.withinLocator = new Locator(locator)
   }
@@ -682,7 +717,21 @@ class Puppeteer extends Helper {
       this.currentRunningTest.artifacts.trace = fileName
     }
 
-    await this.page.goto(url, { waitUntil: this.options.waitForNavigation })
+    try {
+      await this.page.goto(url, { waitUntil: this.options.waitForNavigation })
+    } catch (err) {
+      // Handle terminal navigation errors that shouldn't be retried
+      if (
+        err.message &&
+        (err.message.includes('ERR_ABORTED') || err.message.includes('frame was detached') || err.message.includes('Target page, context or browser has been closed') || err.message.includes('Navigation timeout'))
+      ) {
+        // Mark this as a terminal error to prevent retries
+        const terminalError = new Error(err.message)
+        terminalError.isTerminal = true
+        throw terminalError
+      }
+      throw err
+    }
 
     const performanceTiming = JSON.parse(await this.page.evaluate(() => JSON.stringify(window.performance.timing)))
 
@@ -732,13 +781,11 @@ class Puppeteer extends Helper {
    * {{ react }}
    */
   async moveCursorTo(locator, offsetX = 0, offsetY = 0) {
-    const el = await this._locateElement(locator)
-    if (!el) {
-      throw new ElementNotFound(locator, 'Element to move cursor to')
-    }
+    const els = await this._locate(locator)
+    assertElementExists(els, locator)
 
     // Use manual mouse.move instead of .hover() so the offset can be added to the coordinates
-    const { x, y } = await getClickablePoint(el)
+    const { x, y } = await getClickablePoint(els[0])
     await this.page.mouse.move(x + offsetX, y + offsetY)
     return this._waitForAction()
   }
@@ -748,10 +795,9 @@ class Puppeteer extends Helper {
    *
    */
   async focus(locator) {
-    const el = await this._locateElement(locator)
-    if (!el) {
-      throw new ElementNotFound(locator, 'Element to focus')
-    }
+    const els = await this._locate(locator)
+    assertElementExists(els, locator, 'Element to focus')
+    const el = els[0]
 
     await el.click()
     await el.focus()
@@ -763,12 +809,10 @@ class Puppeteer extends Helper {
    *
    */
   async blur(locator) {
-    const el = await this._locateElement(locator)
-    if (!el) {
-      throw new ElementNotFound(locator, 'Element to blur')
-    }
+    const els = await this._locate(locator)
+    assertElementExists(els, locator, 'Element to blur')
 
-    await blurElement(el, this.page)
+    await blurElement(els[0], this.page)
     return this._waitForAction()
   }
 
@@ -817,12 +861,11 @@ class Puppeteer extends Helper {
     }
 
     if (locator) {
-      const el = await this._locateElement(locator)
-      if (!el) {
-        throw new ElementNotFound(locator, 'Element to scroll into view')
-      }
+      const els = await this._locate(locator)
+      assertElementExists(els, locator, 'Element')
+      const el = els[0]
       await el.evaluate(el => el.scrollIntoView())
-      const elementCoordinates = await getClickablePoint(el)
+      const elementCoordinates = await getClickablePoint(els[0])
       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)
@@ -890,21 +933,6 @@ 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
@@ -916,9 +944,7 @@ class Puppeteer extends Helper {
   async _locateCheckable(locator, providedContext = null) {
     const context = providedContext || (await this._getContext())
     const els = await findCheckable.call(this, locator, context)
-    if (!els || els.length === 0) {
-      throw new ElementNotFound(locator, 'Checkbox or radio')
-    }
+    assertElementExists(els[0], locator, 'Checkbox or radio')
     return els[0]
   }
 
@@ -950,20 +976,13 @@ class Puppeteer extends Helper {
    *
    */
   async grabWebElements(locator) {
-    const elements = await this._locate(locator)
-    return elements.map(element => new WebElement(element, this))
+    return this._locate(locator)
   }
 
-  /**
-   * {{> 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)
+    const els = await this._locate(locator)
+    assertElementExists(els, locator)
+    return els[0]
   }
 
   /**
@@ -1292,8 +1311,16 @@ class Puppeteer extends Helper {
    */
   async checkOption(field, context = null) {
     const elm = await this._locateCheckable(field, context)
-    const curentlyChecked = await elm.getProperty('checked').then(checkedProperty => checkedProperty.jsonValue())
-    // Only check if NOT currently checked
+    let curentlyChecked = await elm
+      .getProperty('checked')
+      .then(checkedProperty => checkedProperty.jsonValue())
+      .catch(() => null)
+
+    if (!curentlyChecked) {
+      const ariaChecked = await elm.evaluate(el => el.getAttribute('aria-checked'))
+      curentlyChecked = ariaChecked === 'true'
+    }
+
     if (!curentlyChecked) {
       await elm.click()
       return this._waitForAction()
@@ -1305,8 +1332,16 @@ class Puppeteer extends Helper {
    */
   async uncheckOption(field, context = null) {
     const elm = await this._locateCheckable(field, context)
-    const curentlyChecked = await elm.getProperty('checked').then(checkedProperty => checkedProperty.jsonValue())
-    // Only uncheck if currently checked
+    let curentlyChecked = await elm
+      .getProperty('checked')
+      .then(checkedProperty => checkedProperty.jsonValue())
+      .catch(() => null)
+
+    if (!curentlyChecked) {
+      const ariaChecked = await elm.evaluate(el => el.getAttribute('aria-checked'))
+      curentlyChecked = ariaChecked === 'true'
+    }
+
     if (curentlyChecked) {
       await elm.click()
       return this._waitForAction()
@@ -2149,13 +2184,12 @@ class Puppeteer extends Helper {
    * {{> waitForClickable }}
    */
   async waitForClickable(locator, waitTimeout) {
-    const el = await this._locateElement(locator)
-    if (!el) {
-      throw new ElementNotFound(locator, 'Element to wait for clickable')
-    }
+    const els = await this._locate(locator)
+    assertElementExists(els, locator)
 
-    return this.waitForFunction(isElementClickable, [el], waitTimeout).catch(async e => {
-      if (/Waiting failed/i.test(e.message) || /failed: timeout/i.test(e.message)) {
+    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)) {
         throw new Error(`element ${new Locator(locator).toString()} still not clickable after ${waitTimeout || this.options.waitForTimeout / 1000} sec`)
       } else {
         throw e
@@ -2726,51 +2760,27 @@ class Puppeteer extends Helper {
   }
 }
 
-module.exports = Puppeteer
-
-/**
- * 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) {
-  if (locator.react) return findReactElements.call(this, locator)
-  locator = new Locator(locator, 'css')
+  const matchedLocator = new Locator(locator, 'css')
 
-  // 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}`)
-  }
-  return matcher.$x(locator.value)
-}
+  if (matchedLocator.type === 'react') return findReactElements.call(this, matchedLocator)
+  if (matchedLocator.isRole()) return findByRole.call(this, matcher, matchedLocator)
 
-/**
- * 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')
-
-  // Use proven legacy approach - Puppeteer Locator API doesn't have .first() method
-  if (!locator.isXPath()) {
-    const elements = await matcher.$$(locator.simplify())
-    return elements[0]
-  }
-  // puppeteer version < 19.4.0 is no longer supported. This one is backward support.
-  if (puppeteer.default?.defaultBrowserRevision) {
-    const elements = await matcher.$$(`xpath/${locator.value}`)
-    return elements[0]
-  }
-  const elements = await matcher.$x(locator.value)
-  return elements[0]
+  if (!matchedLocator.isXPath()) return matcher.$$(matchedLocator.simplify())
+
+  // 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)
+    }
+    // If both methods fail, re-throw the original error
+    throw error
+  }
 }
 
 async function proceedClick(locator, context = null, options = {}) {
@@ -2800,12 +2810,12 @@ async function proceedClick(locator, context = null, options = {}) {
 }
 
 async function findClickable(matcher, locator) {
-  if (locator.react) return findReactElements.call(this, locator)
-  locator = new Locator(locator)
-  if (!locator.isFuzzy()) return findElements.call(this, matcher, locator)
+  const matchedLocator = new Locator(locator)
+
+  if (!matchedLocator.isFuzzy()) return findElements.call(this, matcher, matchedLocator)
 
   let els
-  const literal = xpathLocator.literal(locator.value)
+  const literal = xpathLocator.literal(matchedLocator.value)
 
   els = await findElements.call(this, matcher, Locator.clickable.narrow(literal))
   if (els.length) return els
@@ -2820,7 +2830,15 @@ async function findClickable(matcher, locator) {
     // Do nothing
   }
 
-  return findElements.call(this, matcher, locator.value) // by css or xpath
+  // Try ARIA selector for accessible name
+  try {
+    els = await matcher.$$(`::-p-aria(${matchedLocator.value})`)
+    if (els.length) return els
+  } catch (err) {
+    // ARIA selector not supported or failed
+  }
+
+  return findElements.call(this, matcher, matchedLocator.value) // by css or xpath
 }
 
 async function proceedSee(assertType, text, context, strict = false) {
@@ -2864,10 +2882,10 @@ async function findCheckable(locator, context) {
 
   const matchedLocator = new Locator(locator)
   if (!matchedLocator.isFuzzy()) {
-    return findElements.call(this, contextEl, matchedLocator.simplify())
+    return findElements.call(this, contextEl, matchedLocator)
   }
 
-  const literal = xpathLocator.literal(locator)
+  const literal = xpathLocator.literal(matchedLocator.value)
   let els = await findElements.call(this, contextEl, Locator.checkable.byText(literal))
   if (els.length) {
     return els
@@ -2876,15 +2894,39 @@ async function findCheckable(locator, context) {
   if (els.length) {
     return els
   }
-  return findElements.call(this, contextEl, locator)
+
+  // Try ARIA selector for accessible name
+  try {
+    els = await contextEl.$$(`::-p-aria(${matchedLocator.value})`)
+    if (els.length) return els
+  } catch (err) {
+    // ARIA selector not supported or failed
+  }
+
+  return findElements.call(this, contextEl, matchedLocator.value)
 }
 
 async function proceedIsChecked(assertType, option) {
   let els = await findCheckable.call(this, option)
   assertElementExists(els, option, 'Checkable')
-  els = await Promise.all(els.map(el => el.getProperty('checked')))
-  els = await Promise.all(els.map(el => el.jsonValue()))
-  const selected = els.reduce((prev, cur) => prev || cur)
+
+  const checkedStates = await Promise.all(
+    els.map(async el => {
+      const checked = await el
+        .getProperty('checked')
+        .then(p => p.jsonValue())
+        .catch(() => null)
+
+      if (checked) {
+        return checked
+      }
+
+      const ariaChecked = await el.evaluate(el => el.getAttribute('aria-checked'))
+      return ariaChecked === 'true'
+    }),
+  )
+
+  const selected = checkedStates.reduce((prev, cur) => prev || cur)
   return truth(`checkable ${option}`, 'to be checked')[assertType](selected)
 }
 
@@ -2899,7 +2941,7 @@ async function findFields(locator) {
   if (!matchedLocator.isFuzzy()) {
     return this._locate(matchedLocator)
   }
-  const literal = xpathLocator.literal(locator)
+  const literal = xpathLocator.literal(matchedLocator.value)
 
   let els = await this._locate({ xpath: Locator.field.labelEquals(literal) })
   if (els.length) {
@@ -2914,23 +2956,29 @@ async function findFields(locator) {
   if (els.length) {
     return els
   }
-  return this._locate({ css: locator })
+
+  // Try ARIA selector for accessible name
+  try {
+    const page = await this.context
+    els = await page.$$(`::-p-aria(${matchedLocator.value})`)
+    if (els.length) return els
+  } catch (err) {
+    // ARIA selector not supported or failed
+  }
+
+  return this._locate({ css: matchedLocator.value })
 }
 
 async function proceedDragAndDrop(sourceLocator, destinationLocator) {
-  const src = await this._locateElement(sourceLocator)
-  if (!src) {
-    throw new ElementNotFound(sourceLocator, 'Source Element')
-  }
+  const src = await this._locate(sourceLocator)
+  assertElementExists(src, sourceLocator, 'Source Element')
 
-  const dst = await this._locateElement(destinationLocator)
-  if (!dst) {
-    throw new ElementNotFound(destinationLocator, 'Destination Element')
-  }
+  const dst = await this._locate(destinationLocator)
+  assertElementExists(dst, destinationLocator, 'Destination Element')
 
-  // 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)
+  // 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])
 
   // Drag start point
   await this.page.mouse.move(dragSource.x, dragSource.y, { steps: 5 })
@@ -2992,19 +3040,30 @@ async function proceedSeeInField(assertType, field, value) {
     }
     return proceedMultiple(els[0])
   }
-  const fieldVal = await el.getProperty('value').then(el => el.jsonValue())
+
+  let fieldVal = await el.getProperty('value').then(el => el.jsonValue())
+
+  if (fieldVal === undefined || fieldVal === null) {
+    fieldVal = await el.evaluate(el => el.textContent || el.innerText)
+  }
+
   return stringIncludes(`fields by ${field}`)[assertType](value, fieldVal)
 }
 
 async function filterFieldsByValue(elements, value, onlySelected) {
   const matches = []
   for (const element of elements) {
-    const val = await element.getProperty('value').then(el => el.jsonValue())
+    let val = await element.getProperty('value').then(el => el.jsonValue())
+
+    if (val === undefined || val === null) {
+      val = await element.evaluate(el => el.textContent || el.innerText)
+    }
+
     let isSelected = true
     if (onlySelected) {
       isSelected = await elementSelected(element)
     }
-    if ((value == null || val.indexOf(value) > -1) && isSelected) {
+    if ((value == null || (val && val.indexOf(value) > -1)) && isSelected) {
       matches.push(element)
     }
   }
@@ -3166,7 +3225,12 @@ function _waitForElement(locator, options) {
   }
 }
 
-async function findReactElements(locator, props = {}, state = {}) {
+async function findReactElements(locator) {
+  const resolved = toLocatorConfig(locator, 'react')
+
+  // Use createRequire to access require.resolve in ESM
+  const { createRequire } = await import('module')
+  const require = createRequire(import.meta.url)
   const resqScript = await fs.promises.readFile(require.resolve('resq'), 'utf-8')
   await this.page.evaluate(resqScript.toString())
 
@@ -3209,9 +3273,9 @@ async function findReactElements(locator, props = {}, state = {}) {
       return [...nodes]
     },
     {
-      selector: locator.react,
-      props: locator.props || {},
-      state: locator.state || {},
+      selector: resolved.react,
+      props: resolved.props || {},
+      state: resolved.state || {},
     },
   )
 
@@ -3227,3 +3291,54 @@ async function findReactElements(locator, props = {}, state = {}) {
   await arrayHandle.dispose()
   return result
 }
+
+async function findByRole(matcher, locator) {
+  const resolved = toLocatorConfig(locator, 'role')
+  const roleSelector = buildRoleSelector(resolved)
+
+  if (!resolved.text && !resolved.name) {
+    return matcher.$$(roleSelector)
+  }
+
+  const allElements = await matcher.$$(roleSelector)
+  const filtered = []
+  const accessibleName = resolved.text ?? resolved.name
+  const matcherFn = createRoleTextMatcher(accessibleName, resolved.exact === true)
+
+  for (const el of allElements) {
+    const texts = await el.evaluate(e => {
+      const ariaLabel = e.hasAttribute('aria-label') ? e.getAttribute('aria-label') : ''
+      const labelText = e.id ? document.querySelector(`label[for="${e.id}"]`)?.textContent.trim() || '' : ''
+      const placeholder = e.getAttribute('placeholder') || ''
+      const innerText = e.innerText ? e.innerText.trim() : ''
+      return [ariaLabel || labelText, placeholder, innerText]
+    })
+
+    if (texts.some(text => matcherFn(text))) filtered.push(el)
+  }
+
+  return filtered
+}
+
+function toLocatorConfig(locator, key) {
+  const matchedLocator = new Locator(locator, key)
+  if (matchedLocator.locator) return matchedLocator.locator
+  return { [key]: matchedLocator.value }
+}
+
+function buildRoleSelector(resolved) {
+  return `::-p-aria([role="${resolved.role}"])`
+}
+
+function createRoleTextMatcher(expected, exactMatch) {
+  if (expected instanceof RegExp) {
+    return value => expected.test(value || '')
+  }
+  const target = String(expected)
+  if (exactMatch) {
+    return value => value === target
+  }
+  return value => typeof value === 'string' && value.includes(target)
+}
+
+export { Puppeteer as default }