codeceptjs 3.7.6-beta.4 → 4.0.0-beta.10.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,32 @@ 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'
+import WebElement from '../element/WebElement.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 +225,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 +305,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) {
@@ -404,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()
       },
@@ -566,6 +616,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)
@@ -616,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) {
@@ -648,7 +709,11 @@ class Puppeteer extends Helper {
 
   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) {
@@ -685,7 +750,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)))
 
@@ -969,6 +1048,12 @@ class Puppeteer extends Helper {
     return new WebElement(elements[0], this)
   }
 
+  async grabWebElement(locator) {
+    const els = await this._locate(locator)
+    assertElementExists(els, locator)
+    return els[0]
+  }
+
   /**
    * Switch focus to a particular tab by its number. It waits tabs loading and then switch tab
    *
@@ -1130,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)
   }
 
@@ -1290,13 +1375,64 @@ 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 }}
    */
   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()
@@ -1308,8 +1444,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()
@@ -1808,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
   }
 
@@ -1831,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
@@ -1956,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
   }
@@ -1998,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,
@@ -2011,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,
@@ -2730,7 +2880,7 @@ class Puppeteer extends Helper {
   }
 }
 
-module.exports = Puppeteer
+export default Puppeteer
 
 /**
  * Find elements using Puppeteer's native element discovery methods
@@ -2740,16 +2890,59 @@ module.exports = Puppeteer
  * @returns {Promise<Array>} Array of ElementHandle objects
  */
 async function findElements(matcher, locator) {
-  if (locator.react) return findReactElements.call(this, 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}`)
   }
-  return matcher.$x(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 []
 }
 
 /**
@@ -2762,18 +2955,22 @@ async function findElements(matcher, locator) {
 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]
   }
-  // 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)
+  
+  // 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]
 }
 
@@ -2804,12 +3001,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
@@ -2824,7 +3021,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) {
@@ -2868,10 +3073,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
@@ -2880,15 +3085,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)
 }
 
@@ -2903,7 +3132,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) {
@@ -2918,7 +3147,17 @@ 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) {
@@ -2996,19 +3235,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)
     }
   }
@@ -3170,7 +3420,14 @@ function _waitForElement(locator, options) {
   }
 }
 
-async function findReactElements(locator, props = {}, state = {}) {
+async function findReactElements(locator) {
+  // 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')
+  const require = createRequire(import.meta.url)
   const resqScript = await fs.promises.readFile(require.resolve('resq'), 'utf-8')
   await this.page.evaluate(resqScript.toString())
 
@@ -3213,9 +3470,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 || {},
     },
   )
 
@@ -3231,3 +3488,53 @@ 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)
+}
+