codeceptjs 4.0.1-beta.9 → 4.0.1

package/lib/helper/Playwright.js

@@ -7,6 +7,7 @@ import promiseRetry from 'promise-retry'
 import Locator from '../locator.js'
 import recorder from '../recorder.js'
 import store from '../store.js'
+import { checkFocusBeforeType, checkFocusBeforePressKey } from './extras/focusCheck.js'
 import { includes as stringIncludes } from '../assert/include.js'
 import { urlEquals, equals } from '../assert/equal.js'
 import { empty } from '../assert/empty.js'
@@ -23,26 +24,28 @@ 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 { findByPlaywrightLocator } from './extras/PlaywrightLocator.js'
+import { dropFile } from './scripts/dropFile.js'
 import WebElement from '../element/WebElement.js'
+import { selectElement } from './extras/elementSelection.js'
+import { fillRichEditor } from './extras/richTextEditor.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') {
-  global.__playwrightSelectorsRegistered = false
-}
 
 const popupStore = new Popup()
 const consoleLogStore = new Console()
@@ -100,7 +103,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)`),
@@ -356,28 +358,6 @@ class Playwright extends Helper {
     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 = []
     this.hasCleanupError = false
@@ -417,6 +397,7 @@ class Playwright extends Helper {
       highlightElement: false,
       storageState: undefined,
       onResponse: null,
+      strict: false,
     }
 
     process.env.testIdAttribute = 'data-testid'
@@ -465,7 +446,7 @@ class Playwright extends Helper {
       this.options.recordVideo = { size }
     }
     if (this.options.recordVideo && !this.options.recordVideo.dir) {
-      this.options.recordVideo.dir = `${global.output_dir}/videos/`
+      this.options.recordVideo.dir = `${store.outputDir}/videos/`
     }
     this.isRemoteBrowser = !!this.playwrightOptions.browserWSEndpoint
     this.isElectron = this.options.browser === 'electron'
@@ -523,32 +504,22 @@ 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
       // Check global flag to avoid re-registration in worker processes
-      if (!global.__playwrightSelectorsRegistered) {
+      if (!defaultSelectorEnginesInitialized) {
         try {
           await playwright.selectors.register('__value', createValueEngine)
           await playwright.selectors.register('__disabled', createDisabledEngine)
-          global.__playwrightSelectorsRegistered = true
+          defaultSelectorEnginesInitialized = true
           defaultSelectorEnginesInitialized = true
         } catch (e) {
           if (!e.message.includes('already registered')) {
             throw e
           }
           // Selector already registered globally by another worker
-          global.__playwrightSelectorsRegistered = true
+          defaultSelectorEnginesInitialized = true
           defaultSelectorEnginesInitialized = true
         }
       } else {
@@ -563,54 +534,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)
     }
@@ -689,7 +612,7 @@ class Playwright extends Helper {
       if (this.options.recordVideo) contextOptions.recordVideo = this.options.recordVideo
       if (this.options.recordHar) {
         const harExt = this.options.recordHar.content && this.options.recordHar.content === 'attach' ? 'zip' : 'har'
-        const fileName = `${`${global.output_dir}${path.sep}har${path.sep}${uuidv4()}_${clearString(this.currentRunningTest.title)}`.slice(0, 245)}.${harExt}`
+        const fileName = `${`${store.outputDir}${path.sep}har${path.sep}${uuidv4()}_${clearString(this.currentRunningTest.title)}`.slice(0, 245)}.${harExt}`
         const dir = path.dirname(fileName)
         if (!fileExists(dir)) fs.mkdirSync(dir)
         this.options.recordHar.path = fileName
@@ -832,6 +755,11 @@ class Playwright extends Helper {
   }
 
   async _afterSuite() {
+    // Reset leftover test-level cleanup state (e.g. screenshot failures)
+    // so only errors from this suite teardown are evaluated below.
+    this.hasCleanupError = false
+    this.testFailures = []
+
     // Stop browser after suite completes
     // For restart strategies: stop after each suite
     // For session mode (restart:false): stop after the last suite
@@ -923,7 +851,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) {
@@ -1277,30 +1205,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()`
@@ -1312,63 +1216,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
   }
@@ -1389,6 +1241,7 @@ class Playwright extends Helper {
       }
     }
 
+    // Close browserContext if recordHar is enabled
     if (this.options.recordHar && this.browserContext) {
       try {
         await this.browserContext.close()
@@ -1398,16 +1251,16 @@ 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
@@ -1646,8 +1499,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)
@@ -1771,7 +1639,7 @@ class Playwright extends Helper {
    * @returns Promise<void>
    */
   async replayFromHar(harFilePath, opts) {
-    const file = path.join(global.codecept_dir, harFilePath)
+    const file = path.join(store.codeceptDir, harFilePath)
 
     if (!fileExists(file)) {
       throw new Error(`File at ${file} cannot be found on local system`)
@@ -1911,7 +1779,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)
   }
 
   /**
@@ -1926,7 +1798,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)
   }
 
   /**
@@ -2094,8 +1966,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'))
@@ -2108,8 +1987,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'))
@@ -2164,7 +2050,7 @@ class Playwright extends Helper {
       const filePath = await download.path()
       fileName = fileName || `downloads/${path.basename(filePath)}`
 
-      const downloadPath = path.join(global.output_dir, fileName)
+      const downloadPath = path.join(store.outputDir, fileName)
       if (!fs.existsSync(path.dirname(downloadPath))) {
         fs.mkdirSync(path.dirname(downloadPath), '0777')
       }
@@ -2195,15 +2081,6 @@ class Playwright extends Helper {
     return proceedClick.call(this, locator, context, options)
   }
 
-  /**
-   * Clicks link and waits for navigation (deprecated)
-   */
-  async clickLink(locator, context = null) {
-    console.log('clickLink deprecated: Playwright automatically waits for navigation to happen.')
-    console.log('Replace I.clickLink with I.click')
-    return this.click(locator, context)
-  }
-
   /**
    * {{> forceClick }}
    */
@@ -2348,6 +2225,7 @@ class Playwright extends Helper {
    * {{> pressKeyWithKeyNormalization }}
    */
   async pressKey(key) {
+    await checkFocusBeforePressKey(this, key)
     const modifiers = []
     if (Array.isArray(key)) {
       for (let k of key) {
@@ -2376,6 +2254,8 @@ class Playwright extends Helper {
    * {{> type }}
    */
   async type(keys, delay = null) {
+    await checkFocusBeforeType(this)
+
     // Always use page.keyboard.type for any string (including single character and national characters).
     if (!Array.isArray(keys)) {
       keys = keys.toString()
@@ -2395,43 +2275,33 @@ 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 highlightActiveElement.call(this, el)
+
+    if (await fillRichEditor(this, el, value)) {
+      return this._waitForAction()
+    }
 
     await el.clear()
     if (store.debugMode) this.debugSection('Focused', await elToString(el, 1))
 
-    await highlightActiveElement.call(this, el)
-
     await el.type(value.toString(), { delay: this.options.pressKeyDelay })
 
     return this._waitForAction()
   }
 
   /**
-   * 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)
 
@@ -2443,68 +2313,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) {
-    const file = path.join(global.codecept_dir, pathToFile)
+  async attachFile(locator, pathToFile, context = null) {
+    const file = path.join(store.codeceptDir, 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)
   }
 
   /**
@@ -2545,6 +2448,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 }}
    *
@@ -2747,8 +2670,11 @@ class Playwright extends Helper {
    * @returns {Promise<any>}
    */
   async executeScript(fn, arg) {
-    if (this.context && this.context.constructor.name === 'FrameLocator') {
-      // switching to iframe context
+    if (arg && typeof arg.getNativeElement === 'function') arg = arg.getNativeElement()
+    if (arg && typeof arg.evaluate === 'function' && typeof arg.locator === 'function') {
+      return arg.evaluate(fn)
+    }
+    if (this.context && typeof this.context.url !== 'function' && typeof this.context.innerText !== 'function') {
       return this.context.locator(':root').evaluate(fn, arg)
     }
     return this.page.evaluate.apply(this.page, [fn, arg])
@@ -2762,23 +2688,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
@@ -2789,43 +2704,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
     }
   }
 
@@ -3037,7 +2937,7 @@ class Playwright extends Helper {
     const els = await this._locate(matchedLocator)
     assertElementExists(els, locator)
     const snapshot = await els[0].ariaSnapshot()
-    this.debugSection('Aria Snapshot', snapshot)
+    this.debugSection('Aria Snapshot', `${snapshot.split('\n').length} lines`)
     return snapshot
   }
 
@@ -3390,24 +3290,13 @@ 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}`)
     }
   }
 
   /**
-   * This method accepts [React selectors](https://codecept.io/react).
-   *
    * {{> waitForVisible }}
    */
   async waitForVisible(locator, sec) {
@@ -3417,26 +3306,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) {
@@ -3540,7 +3409,7 @@ class Playwright extends Helper {
   }
 
   async _getContext() {
-    if ((this.context && this.context.constructor.name === 'FrameLocator') || this.context) {
+    if (this.context) {
       return this.context
     }
     if (this.frame) {
@@ -3554,6 +3423,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(
@@ -3561,13 +3431,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
         }
@@ -3579,29 +3449,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
+      }
+    }
   }
 
   /**
@@ -3616,15 +3507,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}`)
@@ -3867,7 +3749,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) {
@@ -4292,51 +4174,54 @@ 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 (locator.text) options.name = locator.text
-  if (locator.exact !== undefined) options.exact = locator.exact
+  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.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()
 }
 
 async function findElements(matcher, locator) {
-  // Check if locator is a Locator object with react/vue type, or a raw object with react/vue property
-  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)
 
   // Handle role locators with text/exact options (e.g., {role: 'button', text: 'Submit', exact: true})
@@ -4345,122 +4230,12 @@ 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)
   if (locator.pw) return findByPlaywrightLocator.call(this, matcher, locator)
 
   locator = new Locator(locator, 'css')
@@ -4495,16 +4270,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 = []
@@ -4519,7 +4300,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)
@@ -4561,7 +4345,9 @@ async function proceedSee(assertType, text, context, strict = false) {
   if (!context) {
     const el = await this.context
 
-    allText = el.constructor.name !== 'Locator' ? [await el.locator('body').innerText()] : [await el.innerText()]
+    allText = typeof el.url !== 'function' && typeof el.innerText === 'function'
+      ? [await el.innerText()]
+      : [await el.locator('body').innerText()]
 
     description = 'web application'
   } else {
@@ -4619,38 +4405,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 proceedSeeInField(assertType, field, value) {
-  const els = await findFields.call(this, field)
+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, 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)
@@ -4764,6 +4604,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 = []
@@ -4783,12 +4630,16 @@ async function targetCreatedHandler(page) {
       .catch(() => null)
       .then(async () => {
         if (this.context && this.context._type === 'Frame') {
-          // we are inside iframe?
+          // we are inside iframe via Frame object — refresh handle
           const frameEl = await this.context.frameElement()
           this.context = await frameEl.contentFrame()
           this.contextLocator = null
           return
         }
+        if (this.context && this.context.constructor && this.context.constructor.name === 'FrameLocator') {
+          // we are inside iframe via FrameLocator — keep it across load events
+          return
+        }
         // if context element was in iframe - keep it
         // if (await this.context.ownerFrame()) return;
         this.context = page
@@ -4969,7 +4820,7 @@ async function refreshContextSession() {
 
 function saveVideoForPage(page, name) {
   if (!page.video()) return null
-  const fileName = `${`${global.output_dir}${pathSeparator}videos${pathSeparator}${uuidv4()}_${clearString(name)}`.slice(0, 245)}.webm`
+  const fileName = `${`${store.outputDir}${pathSeparator}videos${pathSeparator}${uuidv4()}_${clearString(name)}`.slice(0, 245)}.webm`
   page
     .video()
     .saveAs(fileName)
@@ -4986,7 +4837,7 @@ async function saveTraceForContext(context, name) {
   if (!context) return
   if (!context.tracing) return
   try {
-    const fileName = `${`${global.output_dir}${pathSeparator}trace${pathSeparator}${uuidv4()}_${clearString(name)}`.slice(0, 245)}.zip`
+    const fileName = `${`${store.outputDir}${pathSeparator}trace${pathSeparator}${uuidv4()}_${clearString(name)}`.slice(0, 245)}.zip`
     await context.tracing.stop({ path: fileName })
     return fileName
   } catch (err) {