codeceptjs 4.0.0-beta.9.esm-aria → 4.0.0-rc.10

package/lib/helper/Playwright.js

@@ -23,21 +23,26 @@ import {
   clearString,
   requireWithFallback,
   normalizeSpacesInString,
+  normalizePath,
+  resolveUrl,
   relativeDir,
+  getMimeType,
+  base64EncodeFile,
 } from '../utils.js'
 import { isColorProperty, convertColorToRGBA } from '../colorUtils.js'
 import ElementNotFound from './errors/ElementNotFound.js'
+import MultipleElementsFound from './errors/MultipleElementsFound.js'
 import RemoteBrowserConnectionRefused from './errors/RemoteBrowserConnectionRefused.js'
 import Popup from './extras/Popup.js'
 import Console from './extras/Console.js'
 import { findReact, findVue, findByPlaywrightLocator } from './extras/PlaywrightReactVueLocator.js'
+import { dropFile } from './scripts/dropFile.js'
 import WebElement from '../element/WebElement.js'
+import { selectElement } from './extras/elementSelection.js'
 
 let playwright
 let perfTiming
 let defaultSelectorEnginesInitialized = false
-let registeredCustomLocatorStrategies = new Set()
-let globalCustomLocatorStrategies = new Map()
 
 // Use global object to track selector registration across workers
 if (typeof global.__playwrightSelectorsRegistered === 'undefined') {
@@ -100,7 +105,6 @@ const pathSeparator = path.sep
  * @prop {boolean} [highlightElement] - highlight the interacting elements. Default: false. Note: only activate under verbose mode (--verbose).
  * @prop {object} [recordHar] - record HAR and will be saved to `output/har`. See more of [HAR options](https://playwright.dev/docs/api/class-browser#browser-new-context-option-record-har).
  * @prop {string} [testIdAttribute=data-testid] - locate elements based on the testIdAttribute. See more of [locate by test id](https://playwright.dev/docs/locators#locate-by-test-id).
- * @prop {object} [customLocatorStrategies] - custom locator strategies. An object with keys as strategy names and values as JavaScript functions. Example: `{ byRole: (selector, root) => { return root.querySelector(`[role="${selector}"]`) } }`
  * @prop {string|object} [storageState] - Playwright storage state (path to JSON file or object)
  *   passed directly to `browser.newContext`.
  *   If a Scenario is declared with a `cookies` option (e.g. `Scenario('name', { cookies: [...] }, fn)`),
@@ -355,28 +359,6 @@ class Playwright extends Helper {
     this.recordingWebSocketMessages = false
     this.recordedWebSocketMessagesAtLeastOnce = false
     this.cdpSession = null
-    
-    // Filter out invalid customLocatorStrategies (empty arrays, objects without functions)
-    // This can happen in worker threads where config is serialized/deserialized
-    let validCustomLocators = null
-    if (typeof config.customLocatorStrategies === 'object' && config.customLocatorStrategies !== null) {
-      // Check if it's an empty array or object with no function properties
-      const entries = Object.entries(config.customLocatorStrategies)
-      const hasFunctions = entries.some(([_, value]) => typeof value === 'function')
-      if (hasFunctions) {
-        validCustomLocators = config.customLocatorStrategies
-      }
-    }
-    
-    this.customLocatorStrategies = validCustomLocators
-    this._customLocatorsRegistered = false
-
-    // Add custom locator strategies to global registry for early registration
-    if (this.customLocatorStrategies) {
-      for (const [strategyName, strategyFunction] of Object.entries(this.customLocatorStrategies)) {
-        globalCustomLocatorStrategies.set(strategyName, strategyFunction)
-      }
-    }
 
     // Add test failure tracking to prevent false positives
     this.testFailures = []
@@ -416,6 +398,8 @@ class Playwright extends Helper {
       ignoreHTTPSErrors: false, // Adding it here o that context can be set up to ignore the SSL errors,
       highlightElement: false,
       storageState: undefined,
+      onResponse: null,
+      strict: false,
     }
 
     process.env.testIdAttribute = 'data-testid'
@@ -522,16 +506,6 @@ class Playwright extends Helper {
       }
     }
 
-    // Ensure custom locators from this instance are in the global registry
-    // This is critical for worker threads where globalCustomLocatorStrategies is a new Map
-    if (this.customLocatorStrategies) {
-      for (const [strategyName, strategyFunction] of Object.entries(this.customLocatorStrategies)) {
-        if (!globalCustomLocatorStrategies.has(strategyName)) {
-          globalCustomLocatorStrategies.set(strategyName, strategyFunction)
-        }
-      }
-    }
-
     // register an internal selector engine for reading value property of elements in a selector
     try {
       // Always wrap in try-catch since selectors might be registered globally across workers
@@ -562,54 +536,6 @@ class Playwright extends Helper {
           // Ignore if already set
         }
       }
-
-      // Register all custom locator strategies from the global registry
-      for (const [strategyName, strategyFunction] of globalCustomLocatorStrategies.entries()) {
-        if (!registeredCustomLocatorStrategies.has(strategyName)) {
-          try {
-            // Create a selector engine factory function exactly like createValueEngine pattern
-            // Capture variables in closure to avoid reference issues
-            const createCustomEngine = ((name, func) => {
-              return () => {
-                return {
-                  create() {
-                    return null
-                  },
-                  query(root, selector) {
-                    try {
-                      if (!root) return null
-                      const result = func(selector, root)
-                      return Array.isArray(result) ? result[0] : result
-                    } catch (error) {
-                      console.warn(`Error in custom locator "${name}":`, error)
-                      return null
-                    }
-                  },
-                  queryAll(root, selector) {
-                    try {
-                      if (!root) return []
-                      const result = func(selector, root)
-                      return Array.isArray(result) ? result : result ? [result] : []
-                    } catch (error) {
-                      console.warn(`Error in custom locator "${name}":`, error)
-                      return []
-                    }
-                  },
-                }
-              }
-            })(strategyName, strategyFunction)
-
-            await playwright.selectors.register(strategyName, createCustomEngine)
-            registeredCustomLocatorStrategies.add(strategyName)
-          } catch (error) {
-            if (!error.message.includes('already registered')) {
-              console.warn(`Failed to register custom locator strategy '${strategyName}':`, error)
-            } else {
-              console.log(`Custom locator strategy '${strategyName}' already registered`)
-            }
-          }
-        }
-      }
     } catch (e) {
       console.warn(e)
     }
@@ -794,10 +720,7 @@ class Playwright extends Helper {
             await Promise.allSettled(pages.map(p => p.close().catch(() => {})))
           }
           // Use timeout to prevent hanging (10s should be enough for browser cleanup)
-          await Promise.race([
-            this._stopBrowser(),
-            new Promise((_, reject) => setTimeout(() => reject(new Error('Browser stop timeout')), 10000)),
-          ])
+          await Promise.race([this._stopBrowser(), new Promise((_, reject) => setTimeout(() => reject(new Error('Browser stop timeout')), 10000))])
         } catch (e) {
           console.warn('Warning during browser restart in _after:', e.message)
           // Force cleanup even on timeout
@@ -840,10 +763,7 @@ class Playwright extends Helper {
     if (this.isRunning) {
       try {
         // Add timeout protection to prevent hanging
-        await Promise.race([
-          this._stopBrowser(),
-          new Promise((_, reject) => setTimeout(() => reject(new Error('Browser stop timeout in afterSuite')), 10000)),
-        ])
+        await Promise.race([this._stopBrowser(), new Promise((_, reject) => setTimeout(() => reject(new Error('Browser stop timeout in afterSuite')), 10000))])
       } catch (e) {
         console.warn('Warning during suite cleanup:', e.message)
         // Track suite cleanup failures
@@ -928,7 +848,7 @@ class Playwright extends Helper {
   }
 
   async _finishTest() {
-    if ((restartsSession() || restartsContext() || restartsBrowser()) && this.isRunning) {
+    if (this.isRunning) {
       try {
         await Promise.race([this._stopBrowser(), new Promise((_, reject) => setTimeout(() => reject(new Error('Test finish timeout')), 10000))])
       } catch (e) {
@@ -954,10 +874,7 @@ class Playwright extends Helper {
     if (this.isRunning) {
       try {
         // Add timeout protection to prevent hanging
-        await Promise.race([
-          this._stopBrowser(),
-          new Promise((_, reject) => setTimeout(() => reject(new Error('Browser stop timeout in cleanup')), 10000)),
-        ])
+        await Promise.race([this._stopBrowser(), new Promise((_, reject) => setTimeout(() => reject(new Error('Browser stop timeout in cleanup')), 10000))])
       } catch (e) {
         console.warn('Warning during final cleanup:', e.message)
         // Force cleanup on timeout
@@ -970,10 +887,7 @@ class Playwright extends Helper {
       if (this.browser) {
         try {
           // Add timeout protection to prevent hanging
-          await Promise.race([
-            this._stopBrowser(),
-            new Promise((_, reject) => setTimeout(() => reject(new Error('Browser stop timeout in forced cleanup')), 10000)),
-          ])
+          await Promise.race([this._stopBrowser(), new Promise((_, reject) => setTimeout(() => reject(new Error('Browser stop timeout in forced cleanup')), 10000))])
         } catch (e) {
           console.warn('Warning during forced cleanup:', e.message)
           // Force cleanup on timeout
@@ -1288,30 +1202,6 @@ class Playwright extends Helper {
     return this.browser
   }
 
-  _lookupCustomLocator(customStrategy) {
-    if (typeof this.customLocatorStrategies !== 'object' || this.customLocatorStrategies === null) {
-      return null
-    }
-    const strategy = this.customLocatorStrategies[customStrategy]
-    return typeof strategy === 'function' ? strategy : null
-  }
-
-  _isCustomLocator(locator) {
-    const locatorObj = new Locator(locator)
-    if (locatorObj.isCustom()) {
-      const customLocator = this._lookupCustomLocator(locatorObj.type)
-      if (customLocator) {
-        return true
-      }
-      throw new Error('Please define "customLocatorStrategies" as an Object and the Locator Strategy as a "function".')
-    }
-    return false
-  }
-
-  _isCustomLocatorStrategyDefined() {
-    return !!(this.customLocatorStrategies && Object.keys(this.customLocatorStrategies).length > 0)
-  }
-
   /**
    * Create a new browser context with a page. \
    * Usually it should be run from a custom helper after call of `_startBrowser()`
@@ -1323,63 +1213,11 @@ class Playwright extends Helper {
     }
     this.browserContext = await this.browser.newContext(contextOptions)
 
-    // Register custom locator strategies for this context
-    await this._registerCustomLocatorStrategies()
-
     const page = await this.browserContext.newPage()
     targetCreatedHandler.call(this, page)
     await this._setPage(page)
   }
 
-  async _registerCustomLocatorStrategies() {
-    if (!this.customLocatorStrategies) return
-
-    for (const [strategyName, strategyFunction] of Object.entries(this.customLocatorStrategies)) {
-      if (!registeredCustomLocatorStrategies.has(strategyName)) {
-        try {
-          const createCustomEngine = ((name, func) => {
-            return () => {
-              return {
-                create(root, target) {
-                  return null
-                },
-                query(root, selector) {
-                  try {
-                    if (!root) return null
-                    const result = func(selector, root)
-                    return Array.isArray(result) ? result[0] : result
-                  } catch (error) {
-                    console.warn(`Error in custom locator "${name}":`, error)
-                    return null
-                  }
-                },
-                queryAll(root, selector) {
-                  try {
-                    if (!root) return []
-                    const result = func(selector, root)
-                    return Array.isArray(result) ? result : result ? [result] : []
-                  } catch (error) {
-                    console.warn(`Error in custom locator "${name}":`, error)
-                    return []
-                  }
-                },
-              }
-            }
-          })(strategyName, strategyFunction)
-
-          await playwright.selectors.register(strategyName, createCustomEngine)
-          registeredCustomLocatorStrategies.add(strategyName)
-        } catch (error) {
-          if (!error.message.includes('already registered')) {
-            console.warn(`Failed to register custom locator strategy '${strategyName}':`, error)
-          } else {
-            console.log(`Custom locator strategy '${strategyName}' already registered`)
-          }
-        }
-      }
-    }
-  }
-
   _getType() {
     return this.browser._type
   }
@@ -1390,7 +1228,7 @@ class Playwright extends Helper {
     this.context = null
     this.frame = null
     popupStore.clear()
-    
+
     // Remove all event listeners to prevent hanging
     if (this.browser) {
       try {
@@ -1399,7 +1237,8 @@ class Playwright extends Helper {
         // Ignore errors if browser is already closed
       }
     }
-    
+
+    // Close browserContext if recordHar is enabled
     if (this.options.recordHar && this.browserContext) {
       try {
         await this.browserContext.close()
@@ -1408,22 +1247,17 @@ class Playwright extends Helper {
       }
     }
     this.browserContext = null
-    
+
+    // Initiate browser close without waiting for it to complete
+    // The browser process will be cleaned up when the Node process exits
     if (this.browser) {
       try {
-        // Add timeout to prevent browser.close() from hanging indefinitely
-        await Promise.race([
-          this.browser.close(),
-          new Promise((_, reject) => 
-            setTimeout(() => reject(new Error('Browser close timeout')), 5000)
-          )
-        ])
+        // Fire and forget - don't wait for close to complete
+        this.browser.close().catch(() => {
+          // Silently ignore any errors during async close
+        })
       } catch (e) {
-        // Ignore errors if browser is already closed or timeout
-        if (!e.message?.includes('Browser close timeout')) {
-          // Non-timeout error, can be ignored as well
-        }
-        // Force cleanup even on error
+        // Ignore any synchronous errors
       }
     }
     this.browser = null
@@ -1539,7 +1373,7 @@ class Playwright extends Helper {
           acceptDownloads: true,
           ...this.options.emulate,
         }
-        
+
         try {
           this.browserContext = await this.browser.newContext(contextOptions)
         } catch (err) {
@@ -1662,8 +1496,23 @@ class Playwright extends Helper {
    *
    */
   async moveCursorTo(locator, offsetX = 0, offsetY = 0) {
-    const el = await this._locateElement(locator)
-    assertElementExists(el, locator)
+    let context = null
+    if (typeof offsetX !== 'number') {
+      context = offsetX
+      offsetX = 0
+    }
+
+    let el
+    if (context) {
+      const contextEls = await this._locate(context)
+      assertElementExists(contextEls, context, 'Context element')
+      el = await findElements.call(this, contextEls[0], locator)
+      assertElementExists(el, locator)
+      el = el[0]
+    } else {
+      el = await this._locateElement(locator)
+      assertElementExists(el, locator)
+    }
 
     // Use manual mouse.move instead of .hover() so the offset can be added to the coordinates
     const { x, y } = await clickablePoint(el)
@@ -1927,7 +1776,11 @@ class Playwright extends Helper {
    */
   async _locateElement(locator) {
     const context = await this._getContext()
-    return findElement(context, locator)
+    const elements = await findElements.call(this, context, locator)
+    if (elements.length === 0) {
+      throw new ElementNotFound(locator, 'Element', 'was not found')
+    }
+    return selectElement(elements, locator, this)
   }
 
   /**
@@ -1942,7 +1795,7 @@ class Playwright extends Helper {
     const context = providedContext || (await this._getContext())
     const els = await findCheckable.call(this, locator, context)
     assertElementExists(els[0], locator, 'Checkbox or radio')
-    return els[0]
+    return selectElement(els, locator, this)
   }
 
   /**
@@ -2110,8 +1963,15 @@ class Playwright extends Helper {
    * {{> seeElement }}
    *
    */
-  async seeElement(locator) {
-    let els = await this._locate(locator)
+  async seeElement(locator, context = null) {
+    let els
+    if (context) {
+      const contextEls = await this._locate(context)
+      assertElementExists(contextEls, context, 'Context element')
+      els = await findElements.call(this, contextEls[0], locator)
+    } else {
+      els = await this._locate(locator)
+    }
     els = await Promise.all(els.map(el => el.isVisible()))
     try {
       return empty('visible elements').negate(els.filter(v => v).fill('ELEMENT'))
@@ -2124,8 +1984,15 @@ class Playwright extends Helper {
    * {{> dontSeeElement }}
    *
    */
-  async dontSeeElement(locator) {
-    let els = await this._locate(locator)
+  async dontSeeElement(locator, context = null) {
+    let els
+    if (context) {
+      const contextEls = await this._locate(context)
+      assertElementExists(contextEls, context, 'Context element')
+      els = await findElements.call(this, contextEls[0], locator)
+    } else {
+      els = await this._locate(locator)
+    }
     els = await Promise.all(els.map(el => el.isVisible()))
     try {
       return empty('visible elements').assert(els.filter(v => v).fill('ELEMENT'))
@@ -2411,10 +2278,10 @@ class Playwright extends Helper {
    * {{> fillField }}
    *
    */
-  async fillField(field, value) {
-    const els = await findFields.call(this, field)
+  async fillField(field, value, context = null) {
+    const els = await findFields.call(this, field, context)
     assertElementExists(els, field, 'Field')
-    const el = els[0]
+    const el = selectElement(els, field, this)
 
     await el.clear()
     if (store.debugMode) this.debugSection('Focused', await elToString(el, 1))
@@ -2427,27 +2294,13 @@ class Playwright extends Helper {
   }
 
   /**
-   * Clears the text input element: `<input>`, `<textarea>` or `[contenteditable]` .
-   *
-   *
-   * Examples:
-   *
-   * ```js
-   * I.clearField('.text-area')
-   *
-   * // if this doesn't work use force option
-   * I.clearField('#submit', { force: true })
-   * ```
-   * Use `force` to bypass the [actionability](https://playwright.dev/docs/actionability) checks.
-   *
-   * @param {CodeceptJS.LocatorOrString} locator field located by label|name|CSS|XPath|strict locator.
-   * @param {any} [options] [Additional options](https://playwright.dev/docs/api/class-locator#locator-clear) for available options object as 2nd argument.
+   * {{> clearField }}
    */
-  async clearField(locator, options = {}) {
-    const els = await findFields.call(this, locator)
+  async clearField(locator, context = null) {
+    const els = await findFields.call(this, locator, context)
     assertElementExists(els, locator, 'Field to clear')
 
-    const el = els[0]
+    const el = selectElement(els, locator, this)
 
     await highlightActiveElement.call(this, el)
 
@@ -2459,68 +2312,101 @@ class Playwright extends Helper {
   /**
    * {{> appendField }}
    */
-  async appendField(field, value) {
-    const els = await findFields.call(this, field)
+  async appendField(field, value, context = null) {
+    const els = await findFields.call(this, field, context)
     assertElementExists(els, field, 'Field')
-    await highlightActiveElement.call(this, els[0])
-    await els[0].press('End')
-    await els[0].type(value.toString(), { delay: this.options.pressKeyDelay })
+    const el = selectElement(els, field, this)
+    await highlightActiveElement.call(this, el)
+    await el.press('End')
+    await el.type(value.toString(), { delay: this.options.pressKeyDelay })
     return this._waitForAction()
   }
 
   /**
    * {{> seeInField }}
    */
-  async seeInField(field, value) {
+  async seeInField(field, value, context = null) {
     const _value = typeof value === 'boolean' ? value : value.toString()
-    return proceedSeeInField.call(this, 'assert', field, _value)
+    return proceedSeeInField.call(this, 'assert', field, _value, context)
   }
 
   /**
    * {{> dontSeeInField }}
    */
-  async dontSeeInField(field, value) {
+  async dontSeeInField(field, value, context = null) {
     const _value = typeof value === 'boolean' ? value : value.toString()
-    return proceedSeeInField.call(this, 'negate', field, _value)
+    return proceedSeeInField.call(this, 'negate', field, _value, context)
   }
 
   /**
    * {{> attachFile }}
    *
    */
-  async attachFile(locator, pathToFile) {
+  async attachFile(locator, pathToFile, context = null) {
     const file = path.join(global.codecept_dir, pathToFile)
 
     if (!fileExists(file)) {
       throw new Error(`File at ${file} can not be found on local system`)
     }
-    const els = await findFields.call(this, locator)
-    assertElementExists(els, locator, 'Field')
-    await els[0].setInputFiles(file)
+    const els = await findFields.call(this, locator, context)
+    if (els.length) {
+      const el = selectElement(els, locator, this)
+      const tag = await el.evaluate(el => el.tagName)
+      const type = await el.evaluate(el => el.type)
+      if (tag === 'INPUT' && type === 'file') {
+        await el.setInputFiles(file)
+        return this._waitForAction()
+      }
+    }
+
+    const targetEls = els.length ? els : await this._locate(locator)
+    assertElementExists(targetEls, locator, 'Element')
+    const el = selectElement(targetEls, locator, this)
+    const fileData = {
+      base64Content: base64EncodeFile(file),
+      fileName: path.basename(file),
+      mimeType: getMimeType(path.basename(file)),
+    }
+    await el.evaluate(dropFile, fileData)
     return this._waitForAction()
   }
 
   /**
    * {{> selectOption }}
    */
-  async selectOption(select, option) {
-    const els = await findFields.call(this, select)
-    assertElementExists(els, select, 'Selectable field')
-    const el = els[0]
+  async selectOption(select, option, context = null) {
+    const pageContext = await this.context
+    const matchedLocator = new Locator(select)
 
-    await highlightActiveElement.call(this, el)
-    let optionToSelect = ''
+    let contextEl
+    if (context) {
+      const contextEls = await this._locate(context)
+      assertElementExists(contextEls, context, 'Context element')
+      contextEl = contextEls[0]
+    }
 
-    try {
-      optionToSelect = (await el.locator('option', { hasText: option }).textContent()).trim()
-    } catch (e) {
-      optionToSelect = option
+    // Strict locator
+    if (!matchedLocator.isFuzzy()) {
+      this.debugSection('SelectOption', `Strict: ${JSON.stringify(select)}`)
+      const els = contextEl ? await findElements.call(this, contextEl, matchedLocator) : await this._locate(matchedLocator)
+      assertElementExists(els, select, 'Selectable element')
+      return proceedSelect.call(this, pageContext, selectElement(els, select, this), option)
     }
 
-    if (!Array.isArray(option)) option = [optionToSelect]
+    // Fuzzy: try combobox
+    this.debugSection('SelectOption', `Fuzzy: "${matchedLocator.value}"`)
+    const comboboxSearchCtx = contextEl || pageContext
+    let els = await findByRole(comboboxSearchCtx, { role: 'combobox', name: matchedLocator.value })
+    if (els?.length) return proceedSelect.call(this, pageContext, selectElement(els, select, this), option)
 
-    await el.selectOption(option)
-    return this._waitForAction()
+    // Fuzzy: try listbox
+    els = await findByRole(comboboxSearchCtx, { role: 'listbox', name: matchedLocator.value })
+    if (els?.length) return proceedSelect.call(this, pageContext, selectElement(els, select, this), option)
+
+    // Fuzzy: try native select
+    els = await findFields.call(this, select, context)
+    assertElementExists(els, select, 'Selectable element')
+    return proceedSelect.call(this, pageContext, selectElement(els, select, this), option)
   }
 
   /**
@@ -2561,6 +2447,26 @@ class Playwright extends Helper {
     urlEquals(this.options.url).negate(url, await this._getPageUrl())
   }
 
+  /**
+   * {{> seeCurrentPathEquals }}
+   */
+  async seeCurrentPathEquals(path) {
+    const currentUrl = await this._getPageUrl()
+    const baseUrl = this.options.url || 'http://localhost'
+    const actualPath = new URL(currentUrl, baseUrl).pathname
+    return equals('url path').assert(normalizePath(path), normalizePath(actualPath))
+  }
+
+  /**
+   * {{> dontSeeCurrentPathEquals }}
+   */
+  async dontSeeCurrentPathEquals(path) {
+    const currentUrl = await this._getPageUrl()
+    const baseUrl = this.options.url || 'http://localhost'
+    const actualPath = new URL(currentUrl, baseUrl).pathname
+    return equals('url path').negate(normalizePath(path), normalizePath(actualPath))
+  }
+
   /**
    * {{> see }}
    *
@@ -2778,23 +2684,12 @@ class Playwright extends Helper {
   _contextLocator(locator) {
     const locatorObj = new Locator(locator, 'css')
 
-    // Handle custom locators differently
-    if (locatorObj.isCustom()) {
-      return buildCustomLocatorString(locatorObj)
-    }
-
     locator = buildLocatorString(locatorObj)
 
     if (this.contextLocator) {
       const contextLocatorObj = new Locator(this.contextLocator, 'css')
-      if (contextLocatorObj.isCustom()) {
-        // For custom context locators, we can't use the >> syntax
-        // Instead, we'll need to handle this differently in the calling methods
-        return locator
-      } else {
-        const contextLocator = buildLocatorString(contextLocatorObj)
-        locator = `${contextLocator} >> ${locator}`
-      }
+      const contextLocator = buildLocatorString(contextLocatorObj)
+      locator = `${contextLocator} >> ${locator}`
     }
 
     return locator
@@ -2805,43 +2700,28 @@ class Playwright extends Helper {
    *
    */
   async grabTextFrom(locator) {
-    // Handle role locators with text/exact options
-    if (isRoleLocatorObject(locator)) {
-      const elements = await handleRoleLocator(this.page, locator)
-      if (elements && elements.length > 0) {
-        const text = await elements[0].textContent()
-        assertElementExists(text, JSON.stringify(locator))
-        this.debugSection('Text', text)
-        return text
-      }
+    const roleElements = await handleRoleLocator(this.page, locator)
+    if (roleElements && roleElements.length > 0) {
+      const text = await roleElements[0].textContent()
+      assertElementExists(text, JSON.stringify(locator))
+      this.debugSection('Text', text)
+      return text
     }
 
     const locatorObj = new Locator(locator, 'css')
 
-    if (locatorObj.isCustom()) {
-      // For custom locators, find the element first
-      const elements = await findCustomElements.call(this, this.page, locatorObj)
-      if (elements.length === 0) {
-        throw new Error(`Element not found: ${locatorObj.toString()}`)
-      }
-      const text = await elements[0].textContent()
-      assertElementExists(text, locatorObj.toString())
+    locator = this._contextLocator(locator)
+    try {
+      const text = await this.page.textContent(locator)
+      assertElementExists(text, locator)
       this.debugSection('Text', text)
       return text
-    } else {
-      locator = this._contextLocator(locator)
-      try {
-        const text = await this.page.textContent(locator)
-        assertElementExists(text, locator)
-        this.debugSection('Text', text)
-        return text
-      } catch (error) {
-        // Convert Playwright timeout errors to ElementNotFound for consistency
-        if (error.message && error.message.includes('Timeout')) {
-          throw new ElementNotFound(locator, 'text')
-        }
-        throw error
+    } catch (error) {
+      // Convert Playwright timeout errors to ElementNotFound for consistency
+      if (error.message && error.message.includes('Timeout')) {
+        throw new ElementNotFound(locator, 'text')
       }
+      throw error
     }
   }
 
@@ -3183,14 +3063,14 @@ class Playwright extends Helper {
     this.debugSection('Response', await response.text())
 
     // hook to allow JSON response handle this
-    if (this.config.onResponse) {
+    if (this.options.onResponse) {
       const axiosResponse = {
         data: await response.json(),
         status: response.status(),
         statusText: response.statusText(),
         headers: response.headers(),
       }
-      this.config.onResponse(axiosResponse)
+      this.options.onResponse(axiosResponse)
     }
 
     return response
@@ -3406,16 +3286,7 @@ class Playwright extends Helper {
 
     const context = await this._getContext()
     try {
-      if (locator.isCustom()) {
-        // For custom locators, we need to use our custom element finding logic
-        const elements = await findCustomElements.call(this, context, locator)
-        if (elements.length === 0) {
-          throw new Error(`Custom locator ${locator.type}=${locator.value} not found`)
-        }
-        await elements[0].waitFor({ timeout: waitTimeout, state: 'attached' })
-      } else {
-        await context.locator(buildLocatorString(locator)).first().waitFor({ timeout: waitTimeout, state: 'attached' })
-      }
+      await context.locator(buildLocatorString(locator)).first().waitFor({ timeout: waitTimeout, state: 'attached' })
     } catch (e) {
       throw new Error(`element (${locator.toString()}) still not present on page after ${waitTimeout / 1000} sec\n${e.message}`)
     }
@@ -3433,26 +3304,6 @@ class Playwright extends Helper {
     const context = await this._getContext()
     let count = 0
 
-    // Handle custom locators
-    if (locator.isCustom()) {
-      let waiter
-      do {
-        const elements = await findCustomElements.call(this, context, locator)
-        if (elements.length > 0) {
-          waiter = await elements[0].isVisible()
-        } else {
-          waiter = false
-        }
-        if (!waiter) {
-          await this.wait(1)
-          count += 1000
-        }
-      } while (!waiter && count <= waitTimeout)
-
-      if (!waiter) throw new Error(`element (${locator.toString()}) still not visible after ${waitTimeout / 1000} sec.`)
-      return
-    }
-
     // we have this as https://github.com/microsoft/playwright/issues/26829 is not yet implemented
     let waiter
     if (this.frame) {
@@ -3570,6 +3421,7 @@ class Playwright extends Helper {
    */
   async waitInUrl(urlPart, sec = null) {
     const waitTimeout = sec ? sec * 1000 : this.options.waitForTimeout
+    const expectedUrl = resolveUrl(urlPart, this.options.url)
 
     return this.page
       .waitForFunction(
@@ -3577,13 +3429,13 @@ class Playwright extends Helper {
           const currUrl = decodeURIComponent(decodeURIComponent(decodeURIComponent(window.location.href)))
           return currUrl.indexOf(urlPart) > -1
         },
-        urlPart,
+        expectedUrl,
         { timeout: waitTimeout },
       )
       .catch(async e => {
-        const currUrl = await this._getPageUrl() // Required because the waitForFunction can't return data.
+        const currUrl = await this._getPageUrl()
         if (/Timeout/i.test(e.message)) {
-          throw new Error(`expected url to include ${urlPart}, but found ${currUrl}`)
+          throw new Error(`expected url to include ${expectedUrl}, but found ${currUrl}`)
         } else {
           throw e
         }
@@ -3595,29 +3447,50 @@ class Playwright extends Helper {
    */
   async waitUrlEquals(urlPart, sec = null) {
     const waitTimeout = sec ? sec * 1000 : this.options.waitForTimeout
+    const expectedUrl = resolveUrl(urlPart, this.options.url)
 
-    const baseUrl = this.options.url
-    if (urlPart.indexOf('http') < 0) {
-      urlPart = baseUrl + urlPart
+    try {
+      await this.page.waitForURL(
+        url => url.href === expectedUrl,
+        { timeout: waitTimeout },
+      )
+    } catch (e) {
+      const currUrl = await this._getPageUrl()
+      if (/Timeout/i.test(e.message)) {
+        throw new Error(`expected url to be ${expectedUrl}, but found ${currUrl}`)
+      } else {
+        throw e
+      }
     }
+  }
 
-    return this.page
-      .waitForFunction(
-        urlPart => {
-          const currUrl = decodeURIComponent(decodeURIComponent(decodeURIComponent(window.location.href)))
-          return currUrl.indexOf(urlPart) > -1
+  /**
+   * {{> waitCurrentPathEquals }}
+   */
+  async waitCurrentPathEquals(path, sec = null) {
+    const waitTimeout = sec ? sec * 1000 : this.options.waitForTimeout
+    const normalizedPath = normalizePath(path)
+
+    try {
+      await this.page.waitForFunction(
+        expectedPath => {
+          const actualPath = window.location.pathname
+          const normalizePath = p => (p === '' || p === '/' ? '/' : p.replace(/\/+/g, '/').replace(/\/$/, '') || '/')
+          return normalizePath(actualPath) === expectedPath
         },
-        urlPart,
+        normalizedPath,
         { timeout: waitTimeout },
       )
-      .catch(async e => {
-        const currUrl = await this._getPageUrl() // Required because the waitForFunction can't return data.
-        if (/Timeout/i.test(e.message)) {
-          throw new Error(`expected url to be ${urlPart}, but found ${currUrl}`)
-        } else {
-          throw e
-        }
-      })
+    } catch (e) {
+      const currentUrl = await this._getPageUrl()
+      const baseUrl = this.options.url || 'http://localhost'
+      const actualPath = new URL(currentUrl, baseUrl).pathname
+      if (/Timeout/i.test(e.message)) {
+        throw new Error(`expected path to be ${normalizedPath}, but found ${normalizePath(actualPath)}`)
+      } else {
+        throw e
+      }
+    }
   }
 
   /**
@@ -3632,15 +3505,6 @@ class Playwright extends Helper {
     if (context) {
       const locator = new Locator(context, 'css')
       try {
-        if (locator.isCustom()) {
-          // For custom locators, find the elements first then check for text within them
-          const elements = await findCustomElements.call(this, contextObject, locator)
-          if (elements.length === 0) {
-            throw new Error(`Context element not found: ${locator.toString()}`)
-          }
-          return elements[0].locator(`text=${text}`).first().waitFor({ timeout: waitTimeout, state: 'visible' })
-        }
-
         if (!locator.isXPath()) {
           return contextObject
             .locator(`${locator.simplify()} >> text=${text}`)
@@ -3883,7 +3747,7 @@ class Playwright extends Helper {
     if (!locator.isXPath()) {
       try {
         await context
-          .locator(`${locator.isCustom() ? `${locator.type}=${locator.value}` : locator.simplify()}`)
+          .locator(locator.simplify())
           .first()
           .waitFor({ timeout: waitTimeout, state: 'detached' })
       } catch (e) {
@@ -4308,40 +4172,48 @@ class Playwright extends Helper {
 
 export default Playwright
 
-function buildCustomLocatorString(locator) {
-  // Note: this.debug not available in standalone function, using console.log
-  console.log(`Building custom locator string: ${locator.type}=${locator.value}`)
-  return `${locator.type}=${locator.value}`
-}
-
-function buildLocatorString(locator) {
-  if (locator.isCustom()) {
-    return buildCustomLocatorString(locator)
-  }
+export function buildLocatorString(locator) {
   if (locator.isXPath()) {
-    return `xpath=${locator.value}`
+    // Make XPath relative so it works correctly within scoped contexts (e.g. within()).
+    // Playwright's XPath engine auto-converts "//..." to ".//..." when the root is not a Document,
+    // but only when the selector starts with "/". Locator methods like at() wrap XPath in
+    // parentheses (e.g. "(//...)[position()=1]"), bypassing that auto-conversion.
+    // We fix this by prepending "." before the first "//" that follows any leading parentheses.
+    const value = locator.value.replace(/^(\(*)\/\//, '$1.//')
+    return `xpath=${value}`
+  }
+  if (locator.isShadow()) {
+    // Convert shadow locator to CSS with >> chaining operator
+    // Playwright pierces shadow DOM by default, >> chains selectors
+    // { shadow: ['my-app', 'my-form', 'button'] } => 'my-app >> my-form >> button'
+    return locator.value.join(' >> ')
   }
   return locator.simplify()
 }
 
-/**
- * Checks if a locator is a role locator object (e.g., {role: 'button', text: 'Submit', exact: true})
- */
-function isRoleLocatorObject(locator) {
-  return locator && typeof locator === 'object' && locator.role && !locator.type
-}
-
 /**
  * Handles role locator objects by converting them to Playwright's getByRole() API
+ * Accepts both raw objects ({role: 'button', text: 'Submit'}) and Locator-wrapped role objects.
  * Returns elements array if role locator, null otherwise
  */
 async function handleRoleLocator(context, locator) {
-  if (!isRoleLocatorObject(locator)) return null
-  
+  const loc = new Locator(locator)
+  if (!loc.isRole()) return null
+
+  const roleObj = loc.locator || {}
+  const options = {}
+  if (roleObj.text) options.name = roleObj.text
+  if (roleObj.name) options.name = roleObj.name
+  if (roleObj.exact !== undefined) options.exact = roleObj.exact
+
+  return context.getByRole(roleObj.role, Object.keys(options).length > 0 ? options : undefined).all()
+}
+
+async function findByRole(context, locator) {
+  if (!locator || !locator.role) return null
   const options = {}
-  if (locator.text) options.name = locator.text
+  if (locator.name) options.name = locator.name
   if (locator.exact !== undefined) options.exact = locator.exact
-  
   return context.getByRole(locator.role, Object.keys(options).length > 0 ? options : undefined).all()
 }
 
@@ -4350,7 +4222,7 @@ async function findElements(matcher, locator) {
   const isReactLocator = locator.type === 'react' || (locator.locator && locator.locator.react) || locator.react
   const isVueLocator = locator.type === 'vue' || (locator.locator && locator.locator.vue) || locator.vue
   const isPwLocator = locator.type === 'pw' || (locator.locator && locator.locator.pw) || locator.pw
-  
+
   if (isReactLocator) return findReact(matcher, locator)
   if (isVueLocator) return findVue(matcher, locator)
   if (isPwLocator) return findByPlaywrightLocator.call(this, matcher, locator)
@@ -4361,119 +4233,11 @@ async function findElements(matcher, locator) {
 
   locator = new Locator(locator, 'css')
 
-  // Handle custom locators directly instead of relying on Playwright selector engines
-  if (locator.isCustom()) {
-    return findCustomElements.call(this, matcher, locator)
-  }
-
-  // Check if we have a custom context locator and need to search within it
-  if (this.contextLocator) {
-    const contextLocatorObj = new Locator(this.contextLocator, 'css')
-    if (contextLocatorObj.isCustom()) {
-      // Find the context elements first
-      const contextElements = await findCustomElements.call(this, matcher, contextLocatorObj)
-      if (contextElements.length === 0) {
-        return []
-      }
-
-      // Search within the first context element
-      const locatorString = buildLocatorString(locator)
-      return contextElements[0].locator(locatorString).all()
-    }
-  }
-
   const locatorString = buildLocatorString(locator)
 
   return matcher.locator(locatorString).all()
 }
 
-async function findCustomElements(matcher, locator) {
-  // Always prioritize this.customLocatorStrategies which is set in constructor from config
-  // and persists in every worker thread instance
-  let strategyFunction = null
-  
-  if (this.customLocatorStrategies && this.customLocatorStrategies[locator.type]) {
-    strategyFunction = this.customLocatorStrategies[locator.type]
-  } else if (globalCustomLocatorStrategies.has(locator.type)) {
-    // Fallback to global registry (populated in constructor and _init)
-    strategyFunction = globalCustomLocatorStrategies.get(locator.type)
-  }
-
-  if (!strategyFunction) {
-    throw new Error(`Custom locator strategy "${locator.type}" is not defined. Please define "customLocatorStrategies" in your configuration.`)
-  }
-
-  // Execute the custom locator function in the browser context using page.evaluate
-  const page = matcher.constructor.name === 'Page' ? matcher : await matcher.page()
-
-  const elements = await page.evaluate(
-    ({ strategyCode, selector }) => {
-      const strategy = new Function('return ' + strategyCode)()
-      const result = strategy(selector, document)
-
-      // Convert NodeList or single element to array
-      if (result && result.nodeType) {
-        return [result]
-      } else if (result && result.length !== undefined) {
-        return Array.from(result)
-      } else if (Array.isArray(result)) {
-        return result
-      }
-
-      return []
-    },
-    {
-      strategyCode: strategyFunction.toString(),
-      selector: locator.value,
-    },
-  )
-
-  // Convert the found elements back to Playwright locators
-  if (elements.length === 0) {
-    return []
-  }
-
-  // Create CSS selectors for the found elements and return as locators
-  const locators = []
-  const timestamp = Date.now()
-
-  for (let i = 0; i < elements.length; i++) {
-    // Use a unique attribute approach to target specific elements
-    const uniqueAttr = `data-codecept-custom-${timestamp}-${i}`
-
-    await page.evaluate(
-      ({ index, uniqueAttr, strategyCode, selector }) => {
-        // Re-execute the strategy to find elements and mark the specific one
-        const strategy = new Function('return ' + strategyCode)()
-        const result = strategy(selector, document)
-
-        let elementsArray = []
-        if (result && result.nodeType) {
-          elementsArray = [result]
-        } else if (result && result.length !== undefined) {
-          elementsArray = Array.from(result)
-        } else if (Array.isArray(result)) {
-          elementsArray = result
-        }
-
-        if (elementsArray[index]) {
-          elementsArray[index].setAttribute(uniqueAttr, 'true')
-        }
-      },
-      {
-        index: i,
-        uniqueAttr,
-        strategyCode: strategyFunction.toString(),
-        selector: locator.value,
-      },
-    )
-
-    locators.push(page.locator(`[${uniqueAttr}="true"]`))
-  }
-
-  return locators
-}
-
 async function findElement(matcher, locator) {
   if (locator.react) return findReact(matcher, locator)
   if (locator.vue) return findVue(matcher, locator)
@@ -4511,16 +4275,22 @@ async function proceedClick(locator, context = null, options = {}) {
     assertElementExists(els, locator, 'Clickable element')
   }
 
-  await highlightActiveElement.call(this, els[0])
-  if (store.debugMode) this.debugSection('Clicked', await elToString(els[0], 1))
+  const opts = store.currentStep?.opts
+  let element
+  if (opts?.elementIndex != null) {
+    element = selectElement(els, locator, this)
+  } else {
+    const strict = (opts?.exact === false || opts?.strictMode === false) ? false : (this.options.strict || opts?.exact === true || opts?.strictMode === true)
+    if (strict) assertOnlyOneElement(els, locator, this)
+    element = els.length > 1 ? (await getVisibleElements(els))[0] : els[0]
+  }
+
+  await highlightActiveElement.call(this, element)
+  if (store.debugMode) this.debugSection('Clicked', await elToString(element, 1))
 
-  /*
-    using the force true options itself but instead dispatching a click
-  */
   if (options.force) {
-    await els[0].dispatchEvent('click')
+    await element.dispatchEvent('click')
   } else {
-    const element = els.length > 1 ? (await getVisibleElements(els))[0] : els[0]
     await element.click(options)
   }
   const promises = []
@@ -4535,7 +4305,10 @@ async function proceedClick(locator, context = null, options = {}) {
 async function findClickable(matcher, locator) {
   const matchedLocator = new Locator(locator)
 
-  if (!matchedLocator.isFuzzy()) return findElements.call(this, matcher, matchedLocator)
+  if (!matchedLocator.isFuzzy()) {
+    const els = await findElements.call(this, matcher, matchedLocator)
+    return els
+  }
 
   let els
   const literal = xpathLocator.literal(matchedLocator.value)
@@ -4635,38 +4408,92 @@ async function proceedIsChecked(assertType, option) {
   return truth(`checkable ${option}`, 'to be checked')[assertType](selected)
 }
 
-async function findFields(locator) {
-  // Handle role locators with text/exact options
-  if (isRoleLocatorObject(locator)) {
-    const page = await this.page
-    const roleElements = await handleRoleLocator(page, locator)
-    if (roleElements) return roleElements
+async function findFields(locator, context = null) {
+  let contextEl
+  if (context) {
+    const contextEls = await this._locate(context)
+    assertElementExists(contextEls, context, 'Context element')
+    contextEl = contextEls[0]
   }
 
+  const locateFn = contextEl
+    ? loc => findElements.call(this, contextEl, loc)
+    : loc => this._locate(loc)
+
+  const matcher = contextEl || (await this.page)
+  const roleElements = await handleRoleLocator(matcher, locator)
+  if (roleElements) return roleElements
+
   const matchedLocator = new Locator(locator)
   if (!matchedLocator.isFuzzy()) {
-    return this._locate(matchedLocator)
+    return locateFn(matchedLocator)
   }
   const literal = xpathLocator.literal(locator)
 
-  let els = await this._locate({ xpath: Locator.field.labelEquals(literal) })
+  let els = await locateFn({ xpath: Locator.field.labelEquals(literal) })
   if (els.length) {
     return els
   }
 
-  els = await this._locate({ xpath: Locator.field.labelContains(literal) })
+  els = await locateFn({ xpath: Locator.field.labelContains(literal) })
   if (els.length) {
     return els
   }
-  els = await this._locate({ xpath: Locator.field.byName(literal) })
+  els = await locateFn({ xpath: Locator.field.byName(literal) })
   if (els.length) {
     return els
   }
-  return this._locate({ css: locator })
+  return locateFn({ css: locator })
+}
+
+async function proceedSelect(context, el, option) {
+  const role = await el.getAttribute('role')
+  const options = Array.isArray(option) ? option : [option]
+
+  if (role === 'combobox') {
+    this.debugSection('SelectOption', 'Expanding combobox')
+    await highlightActiveElement.call(this, el)
+    const [ariaOwns, ariaControls] = await Promise.all([el.getAttribute('aria-owns'), el.getAttribute('aria-controls')])
+    await el.click()
+    await this._waitForAction()
+
+    const listboxId = ariaOwns || ariaControls
+    let listbox = listboxId ? context.locator(`#${listboxId}`).first() : null
+    if (!listbox || !(await listbox.count())) listbox = context.getByRole('listbox').first()
+
+    for (const opt of options) {
+      const optEl = listbox.getByRole('option', { name: opt }).first()
+      this.debugSection('SelectOption', `Clicking: "${opt}"`)
+      await highlightActiveElement.call(this, optEl)
+      await optEl.click()
+    }
+    return this._waitForAction()
+  }
+
+  if (role === 'listbox') {
+    for (const opt of options) {
+      const optEl = el.getByRole('option', { name: opt }).first()
+      this.debugSection('SelectOption', `Clicking: "${opt}"`)
+      await highlightActiveElement.call(this, optEl)
+      await optEl.click()
+    }
+    return this._waitForAction()
+  }
+
+  await highlightActiveElement.call(this, el)
+  let optionToSelect = option
+  try {
+    optionToSelect = (await el.locator('option', { hasText: option }).textContent()).trim()
+  } catch (e) {
+    optionToSelect = option
+  }
+  if (!Array.isArray(option)) option = [optionToSelect]
+  await el.selectOption(option)
+  return this._waitForAction()
 }
 
-async function proceedSeeInField(assertType, field, value) {
-  const els = await findFields.call(this, field)
+async function proceedSeeInField(assertType, field, value, context) {
+  const els = await findFields.call(this, field, context)
   assertElementExists(els, field, 'Field')
   const el = els[0]
   const tag = await el.evaluate(e => e.tagName)
@@ -4780,6 +4607,13 @@ function assertElementExists(res, locator, prefix, suffix) {
   }
 }
 
+function assertOnlyOneElement(elements, locator, helper) {
+  if (elements.length > 1) {
+    const webElements = elements.map(el => new WebElement(el, helper))
+    throw new MultipleElementsFound(locator, webElements)
+  }
+}
+
 function $XPath(element, selector) {
   const found = document.evaluate(selector, element || document.body, null, 5, null)
   const res = []
@@ -4967,7 +4801,7 @@ async function refreshContextSession() {
       this.debugSection('Session', 'Skipping storage cleanup - no active page/context')
       return
     }
-    
+
     const currentUrl = await this.grabCurrentUrl()
 
     if (currentUrl.startsWith('http')) {