codeceptjs 4.0.0-beta.7.esm-aria → 4.0.0-beta.8.esm-aria

package/lib/helper/Playwright.js

@@ -30,17 +30,25 @@ import ElementNotFound from './errors/ElementNotFound.js'
 import RemoteBrowserConnectionRefused from './errors/RemoteBrowserConnectionRefused.js'
 import Popup from './extras/Popup.js'
 import Console from './extras/Console.js'
-import { buildLocatorString, findElements, findElement, getVisibleElements, findReact, findVue, findByPlaywrightLocator, findByRole } from './extras/PlaywrightLocator.js'
+import { findReact, findVue, findByPlaywrightLocator } from './extras/PlaywrightReactVueLocator.js'
+import WebElement from '../element/WebElement.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()
 const availableBrowsers = ['chromium', 'webkit', 'firefox', 'electron']
 
-import { setRestartStrategy, restartsSession, restartsContext } from './extras/PlaywrightRestartOpts.js'
+import { setRestartStrategy, restartsSession, restartsContext, restartsBrowser } from './extras/PlaywrightRestartOpts.js'
 import { createValueEngine, createDisabledEngine } from './extras/PlaywrightPropEngine.js'
 import { seeElementError, dontSeeElementError, dontSeeElementInDOMError, seeElementInDOMError } from './errors/ElementAssertion.js'
 import { dontSeeTraffic, seeTraffic, grabRecordedNetworkTraffics, stopRecordingTraffic, flushNetworkTraffics } from './network/actions.js'
@@ -92,6 +100,13 @@ 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)`),
+ *   those cookies are used instead and the configured `storageState` is ignored (no merge).
+ *   May include session cookies, auth tokens, localStorage and (if captured with
+ *   `grabStorageState({ indexedDB: true })`) IndexedDB data; treat as sensitive and do not commit.
  */
 const config = {}
 
@@ -340,6 +355,28 @@ 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 = []
@@ -347,6 +384,11 @@ class Playwright extends Helper {
 
     // override defaults with config
     this._setConfig(config)
+
+    // pass storageState directly (string path or object) and let Playwright handle errors/missing file
+    if (typeof config.storageState !== 'undefined') {
+      this.storageState = config.storageState
+    }
   }
 
   _validateConfig(config) {
@@ -373,6 +415,7 @@ class Playwright extends Helper {
       use: { actionTimeout: 0 },
       ignoreHTTPSErrors: false, // Adding it here o that context can be set up to ignore the SSL errors,
       highlightElement: false,
+      storageState: undefined,
     }
 
     process.env.testIdAttribute = 'data-testid'
@@ -479,19 +522,106 @@ 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
-    if (defaultSelectorEnginesInitialized) return
-    defaultSelectorEnginesInitialized = true
     try {
-      await playwright.selectors.register('__value', createValueEngine)
-      await playwright.selectors.register('__disabled', createDisabledEngine)
-      if (process.env.testIdAttribute) await playwright.selectors.setTestIdAttribute(process.env.testIdAttribute)
+      // 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) {
+        try {
+          await playwright.selectors.register('__value', createValueEngine)
+          await playwright.selectors.register('__disabled', createDisabledEngine)
+          global.__playwrightSelectorsRegistered = 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
+        }
+      } else {
+        // Selectors already registered in a worker, skip
+        defaultSelectorEnginesInitialized = true
+        this.debugSection('Init', 'Default selector engines already registered globally, skipping')
+      }
+      if (process.env.testIdAttribute) {
+        try {
+          await playwright.selectors.setTestIdAttribute(process.env.testIdAttribute)
+        } catch (e) {
+          // 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)
     }
   }
 
   _beforeSuite() {
+    // Skip browser start in dry-run mode (used by check command)
+    if (store.dryRun) {
+      this.debugSection('Dry Run', 'Skipping browser start')
+      return
+    }
+
     // Start browser if not manually started and not already running
     // Browser should start in singleton mode (restart: false) or when restart strategy is enabled
     if (!this.options.manualStart && !this.isRunning) {
@@ -501,6 +631,12 @@ class Playwright extends Helper {
   }
 
   async _before(test) {
+    // Skip browser operations in dry-run mode (used by check command)
+    if (store.dryRun) {
+      this.currentRunningTest = test
+      return
+    }
+
     this.currentRunningTest = test
 
     // Reset failure tracking for each test to prevent false positives
@@ -526,7 +662,12 @@ class Playwright extends Helper {
       },
     })
 
+    // Start browser if needed (initial start or browser restart strategy)
     if (!this.isRunning && !this.options.manualStart) await this._startBrowser()
+    else if (restartsBrowser() && !this.options.manualStart) {
+      // Browser restart strategy: start browser for each test
+      await this._startBrowser()
+    }
 
     this.isAuthenticated = false
     if (this.isElectron) {
@@ -557,8 +698,7 @@ class Playwright extends Helper {
 
       // load pre-saved cookies
       if (test?.opts?.cookies) contextOptions.storageState = { cookies: test.opts.cookies }
-
-      if (this.storageState) contextOptions.storageState = this.storageState
+      else if (this.storageState) contextOptions.storageState = this.storageState
       if (this.options.userAgent) contextOptions.userAgent = this.options.userAgent
       if (this.options.locale) contextOptions.locale = this.options.locale
       if (this.options.colorScheme) contextOptions.colorScheme = this.options.colorScheme
@@ -573,7 +713,20 @@ class Playwright extends Helper {
           }
         }
         this.debugSection('New Session', JSON.stringify(this.contextOptions))
-        this.browserContext = await this.browser.newContext(this.contextOptions) // Adding the HTTPSError ignore in the context so that we can ignore those errors
+        try {
+          this.browserContext = await this.browser.newContext(this.contextOptions) // Adding the HTTPSError ignore in the context so that we can ignore those errors
+        } catch (err) {
+          // In worker mode with Playwright 1.x, there's a known issue where newContext() fails
+          // with "selector engine already registered" when selectors are registered globally
+          // across worker threads. This is safe to retry without ANY custom options.
+          if (err.message && err.message.includes('already registered')) {
+            this.debugSection('Worker Mode', 'Selector conflict detected, retrying context creation with no options')
+            // Create context with NO options to avoid selector conflicts
+            this.browserContext = await this.browser.newContext()
+          } else {
+            throw err
+          }
+        }
       }
     }
 
@@ -614,6 +767,9 @@ class Playwright extends Helper {
   async _after() {
     if (!this.isRunning) return
 
+    // Clear popup state to prevent leakage between tests
+    popupStore.clear()
+
     if (this.isElectron) {
       try {
         this.browser.close()
@@ -628,6 +784,31 @@ class Playwright extends Helper {
       return refreshContextSession.bind(this)()
     }
 
+    if (restartsBrowser()) {
+      // Close browser completely for restart strategy
+      if (this.isRunning) {
+        try {
+          // Close all pages first to release resources
+          if (this.browserContext) {
+            const pages = await this.browserContext.pages()
+            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)),
+          ])
+        } catch (e) {
+          console.warn('Warning during browser restart in _after:', e.message)
+          // Force cleanup even on timeout
+          this.browser = null
+          this.browserContext = null
+          this.isRunning = false
+        }
+      }
+      return
+    }
+
     // close other sessions with timeout protection, but only if restartsContext() is true
     if (restartsContext()) {
       try {
@@ -653,15 +834,25 @@ class Playwright extends Helper {
   }
 
   async _afterSuite() {
-    // Only stop browser if restart strategy requires it
-    if ((restartsSession() || restartsContext()) && this.isRunning) {
+    // Stop browser after suite completes
+    // For restart strategies: stop after each suite
+    // For session mode (restart:false): stop after the last suite
+    if (this.isRunning) {
       try {
-        await this._stopBrowser()
+        // Add timeout protection to prevent hanging
+        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
         this.hasCleanupError = true
         this.testFailures.push(`Suite cleanup failed: ${e.message}`)
+        // Force cleanup on timeout
+        this.browser = null
+        this.browserContext = null
+        this.isRunning = false
       } finally {
         this.isRunning = false
       }
@@ -737,7 +928,7 @@ class Playwright extends Helper {
   }
 
   async _finishTest() {
-    if ((restartsSession() || restartsContext()) && this.isRunning) {
+    if ((restartsSession() || restartsContext() || restartsBrowser()) && this.isRunning) {
       try {
         await Promise.race([this._stopBrowser(), new Promise((_, reject) => setTimeout(() => reject(new Error('Test finish timeout')), 10000))])
       } catch (e) {
@@ -762,17 +953,32 @@ class Playwright extends Helper {
     // Final cleanup when test run completes
     if (this.isRunning) {
       try {
-        await this._stopBrowser()
+        // Add timeout protection to prevent hanging
+        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
+        this.browser = null
+        this.browserContext = null
+        this.isRunning = false
       }
     } else {
       // Check if we still have a browser object despite isRunning being false
       if (this.browser) {
         try {
-          await this._stopBrowser()
+          // 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)),
+          ])
         } catch (e) {
           console.warn('Warning during forced cleanup:', e.message)
+          // Force cleanup on timeout
+          this.browser = null
+          this.browserContext = null
         }
       }
     }
@@ -950,6 +1156,9 @@ class Playwright extends Helper {
       try {
         this.page.removeAllListeners('crash')
         this.page.removeAllListeners('dialog')
+        this.page.removeAllListeners('load')
+        this.page.removeAllListeners('console')
+        this.page.removeAllListeners('requestfinished')
       } catch (e) {
         console.warn('Warning cleaning previous page listeners:', e.message)
       }
@@ -1038,6 +1247,12 @@ class Playwright extends Helper {
   }
 
   async _startBrowser() {
+    // Ensure custom locator strategies are registered before browser launch
+    // Only init once globally to avoid selector re-registration in workers
+    if (!defaultSelectorEnginesInitialized) {
+      await this._init()
+    }
+
     if (this.isElectron) {
       this.browser = await playwright._electron.launch(this.playwrightOptions)
     } else if (this.isRemoteBrowser && this.isCDPConnection) {
@@ -1073,6 +1288,30 @@ 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()`
@@ -1083,11 +1322,64 @@ class Playwright extends Helper {
       throw new Error('Browser not started. Call _startBrowser() first or disable manualStart option.')
     }
     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
   }
@@ -1098,57 +1390,43 @@ class Playwright extends Helper {
     this.context = null
     this.frame = null
     popupStore.clear()
-
-    // Clean up event listeners to prevent hanging
-    try {
-      if (this.browser) {
-        this.browser.removeAllListeners('targetchanged')
-        if (this.browserContext) {
-          // Clean up any page event listeners in the context
-          const pages = this.browserContext.pages()
-          for (const page of pages) {
-            try {
-              page.removeAllListeners('crash')
-              page.removeAllListeners('dialog')
-            } catch (e) {
-              console.warn('Warning cleaning page listeners:', e.message)
-            }
-          }
-        }
-      }
-    } catch (e) {
-      console.warn('Warning cleaning event listeners:', e.message)
-    }
-
-    try {
-      if (this.browserContext) {
-        await Promise.race([this.browserContext.close(), new Promise((_, reject) => setTimeout(() => reject(new Error('Context close timeout')), 3000))])
+    
+    // Remove all event listeners to prevent hanging
+    if (this.browser) {
+      try {
+        this.browser.removeAllListeners()
+      } catch (e) {
+        // Ignore errors if browser is already closed
       }
-    } catch (error) {
-      console.warn('Failed to close browser context:', error.message)
     }
-
-    try {
-      if (this.browser) {
-        await Promise.race([this.browser.close(), new Promise((_, reject) => setTimeout(() => reject(new Error('Browser close timeout')), 3000))])
+    
+    if (this.options.recordHar && this.browserContext) {
+      try {
+        await this.browserContext.close()
+      } catch (e) {
+        // Ignore errors if context is already closed
       }
-    } catch (error) {
-      console.warn('Failed to close browser:', error.message)
     }
-
-    // Always try to kill the browser process to ensure cleanup
-    try {
-      if (this.browser && this.browser.process && this.browser.process()) {
-        this.browser.process().kill('SIGKILL')
+    this.browserContext = null
+    
+    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)
+          )
+        ])
+      } 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
       }
-    } catch (e) {
-      // Silently ignore process kill errors
     }
-
-    // Ensure cleanup is complete
     this.browser = null
-    this.browserContext = null
-    this.page = null
     this.isRunning = false
   }
 
@@ -1225,8 +1503,9 @@ class Playwright extends Helper {
       throw new Error('Cannot open pages inside an Electron container')
     }
 
-    // Prevent navigation attempts when browser is being torn down
-    if (!this.isRunning && (!this.browser || !this.browserContext || !this.page)) {
+    // Prevent navigation attempts only when manual start is enabled and browser is not running
+    // Allow auto-initialization for normal operation (e.g., when using BROWSER_RESTART=browser)
+    if (!this.isRunning && this.options.manualStart && (!this.browser || !this.browserContext || !this.page)) {
       throw new Error('Cannot navigate: browser is not running or has been closed')
     }
 
@@ -1260,7 +1539,21 @@ class Playwright extends Helper {
           acceptDownloads: true,
           ...this.options.emulate,
         }
-        this.browserContext = await this.browser.newContext(contextOptions)
+        
+        try {
+          this.browserContext = await this.browser.newContext(contextOptions)
+        } catch (err) {
+          // In worker mode with Playwright 1.x, there's a known issue where newContext() fails
+          // with "selector engine already registered" when selectors are registered globally
+          // across worker threads. This is safe to retry without ANY custom options.
+          if (err.message && err.message.includes('already registered')) {
+            this.debugSection('Worker Mode', 'Selector conflict in amOnPage, retrying with empty options')
+            // Create context with NO options to avoid selector conflicts
+            this.browserContext = await this.browser.newContext()
+          } else {
+            throw err
+          }
+        }
       }
 
       let pages
@@ -1450,20 +1743,21 @@ class Playwright extends Helper {
   async dragAndDrop(srcElement, destElement, options) {
     const src = new Locator(srcElement)
     const dst = new Locator(destElement)
+    const context = await this._getContext()
 
     if (options) {
-      return this.page.dragAndDrop(buildLocatorString(src), buildLocatorString(dst), options)
+      return context.dragAndDrop(buildLocatorString(src), buildLocatorString(dst), options)
     }
 
     const _smallWaitInMs = 600
-    await this.page.locator(buildLocatorString(src)).hover()
+    await context.locator(buildLocatorString(src)).hover()
     await this.page.mouse.down()
     await this.page.waitForTimeout(_smallWaitInMs)
 
-    const destElBox = await this.page.locator(buildLocatorString(dst)).boundingBox()
+    const destElBox = await context.locator(buildLocatorString(dst)).boundingBox()
 
     await this.page.mouse.move(destElBox.x + destElBox.width / 2, destElBox.y + destElBox.height / 2)
-    await this.page.locator(buildLocatorString(dst)).hover({ position: { x: 10, y: 10 } })
+    await context.locator(buildLocatorString(dst)).hover({ position: { x: 10, y: 10 } })
     await this.page.waitForTimeout(_smallWaitInMs)
     await this.page.mouse.up()
   }
@@ -1603,9 +1897,9 @@ class Playwright extends Helper {
   async _locate(locator) {
     const context = await this._getContext()
 
-    if (this.frame) return findElements(this.frame, locator)
+    if (this.frame) return findElements.call(this, this.frame, locator)
 
-    const els = await findElements(context, locator)
+    const els = await findElements.call(this, context, locator)
 
     if (store.debugMode) {
       const previewElements = els.slice(0, 3)
@@ -1679,7 +1973,8 @@ class Playwright extends Helper {
    *
    */
   async grabWebElements(locator) {
-    return this._locate(locator)
+    const elements = await this._locate(locator)
+    return elements.map(element => new WebElement(element, this))
   }
 
   /**
@@ -1687,7 +1982,8 @@ class Playwright extends Helper {
    *
    */
   async grabWebElement(locator) {
-    return this._locateElement(locator)
+    const element = await this._locateElement(locator)
+    return new WebElement(element, this)
   }
 
   /**
@@ -1911,7 +2207,7 @@ class Playwright extends Helper {
    * ```
    *
    */
-  async click(locator, context = null, options = {}) {
+  async click(locator = '//body', context = null, options = {}) {
     return proceedClick.call(this, locator, context, options)
   }
 
@@ -1945,6 +2241,49 @@ class Playwright extends Helper {
     return proceedClick.call(this, locator, context, { button: 'right' })
   }
 
+  /**
+   * Performs click at specific coordinates.
+   * If locator is provided, the coordinates are relative to the element.
+   * If locator is not provided, the coordinates are global page coordinates.
+   *
+   * ```js
+   * // Click at global coordinates (100, 200)
+   * I.clickXY(100, 200);
+   *
+   * // Click at coordinates (50, 30) relative to element
+   * I.clickXY('#someElement', 50, 30);
+   * ```
+   *
+   * @param {CodeceptJS.LocatorOrString|number} locator Element to click on or X coordinate if no element.
+   * @param {number} [x] X coordinate relative to element, or Y coordinate if locator is a number.
+   * @param {number} [y] Y coordinate relative to element.
+   * @returns {Promise<void>}
+   */
+  async clickXY(locator, x, y) {
+    // If locator is a number, treat it as global X coordinate
+    if (typeof locator === 'number') {
+      const globalX = locator
+      const globalY = x
+      await this.page.mouse.click(globalX, globalY)
+      return this._waitForAction()
+    }
+
+    // Locator is provided, click relative to element
+    const el = await this._locateElement(locator)
+    assertElementExists(el, locator, 'Element to click')
+
+    const box = await el.boundingBox()
+    if (!box) {
+      throw new Error(`Element ${locator} is not visible or has no bounding box`)
+    }
+
+    const absoluteX = box.x + x
+    const absoluteY = box.y + y
+
+    await this.page.mouse.click(absoluteX, absoluteY)
+    return this._waitForAction()
+  }
+
   /**
    *
    * [Additional options](https://playwright.dev/docs/api/class-elementhandle#element-handle-check) for check available as 3rd argument.
@@ -2020,7 +2359,7 @@ class Playwright extends Helper {
 
   /**
    *
-   * _Note:_ Shortcuts like `'Meta'` + `'A'` do not work on macOS ([GoogleChrome/Puppeteer#1313](https://github.com/GoogleChrome/puppeteer/issues/1313)).
+   * _Note:_ Shortcuts like `'Meta'` + `'A'` do not work on macOS ([puppeteer/puppeteer#1313](https://github.com/puppeteer/puppeteer/issues/1313)).
    *
    * {{> pressKeyWithKeyNormalization }}
    */
@@ -2053,11 +2392,15 @@ class Playwright extends Helper {
    * {{> type }}
    */
   async type(keys, delay = null) {
+    // Always use page.keyboard.type for any string (including single character and national characters).
     if (!Array.isArray(keys)) {
       keys = keys.toString()
-      keys = keys.split('')
+      const typeDelay = typeof delay === 'number' ? delay : this.options.pressKeyDelay
+      await this.page.keyboard.type(keys, { delay: typeDelay })
+      return
     }
 
+    // For array input, treat each as a key press to keep working combinations such as ['Control', 'A'] or ['T', 'e', 's', 't'].
     for (const key of keys) {
       await this.page.keyboard.press(key)
       if (delay) await this.wait(delay / 1000)
@@ -2360,6 +2703,30 @@ class Playwright extends Helper {
     }
   }
 
+  /**
+   * Grab the current storage state (cookies, localStorage, etc.) via Playwright's `browserContext.storageState()`.
+   * Returns the raw object that Playwright provides.
+   *
+   * Security: The returned object can contain authentication tokens, session cookies
+   * and (when `indexedDB: true` is used) data that may include user PII. Treat it as a secret.
+   * Avoid committing it to source control and prefer storing it in a protected secrets store / CI artifact vault.
+   *
+   * @param {object} [options]
+   * @param {boolean} [options.indexedDB] set to true to include IndexedDB in snapshot (Playwright >=1.51)
+   *
+   * ```js
+   * // basic usage
+   * const state = await I.grabStorageState();
+   * require('fs').writeFileSync('authState.json', JSON.stringify(state));
+   *
+   * // include IndexedDB when using Firebase Auth, etc.
+   * const stateWithIDB = await I.grabStorageState({ indexedDB: true });
+   * ```
+   */
+  async grabStorageState(options = {}) {
+    return this.browserContext.storageState(options)
+  }
+
   /**
    * {{> clearCookie }}
    */
@@ -2409,11 +2776,25 @@ class Playwright extends Helper {
    * @param {*} locator
    */
   _contextLocator(locator) {
-    locator = buildLocatorString(new Locator(locator, 'css'))
+    const locatorObj = new Locator(locator, 'css')
+
+    // Handle custom locators differently
+    if (locatorObj.isCustom()) {
+      return buildCustomLocatorString(locatorObj)
+    }
+
+    locator = buildLocatorString(locatorObj)
 
     if (this.contextLocator) {
-      const contextLocator = buildLocatorString(new Locator(this.contextLocator, 'css'))
-      locator = `${contextLocator} >> ${locator}`
+      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}`
+      }
     }
 
     return locator
@@ -2424,30 +2805,44 @@ class Playwright extends Helper {
    *
    */
   async grabTextFrom(locator) {
-    const originalLocator = locator
-    const matchedLocator = new Locator(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 locatorObj = new Locator(locator, 'css')
 
-    if (!matchedLocator.isFuzzy()) {
-      const els = await this._locate(matchedLocator)
-      assertElementExists(els, locator)
-      const text = await els[0].innerText()
+    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())
       this.debugSection('Text', text)
       return text
-    }
-
-    const contextAwareLocator = this._contextLocator(matchedLocator.value)
-    let text
-    try {
-      text = await this.page.textContent(contextAwareLocator)
-    } catch (err) {
-      if (err.message.includes('Timeout') || err.message.includes('exceeded')) {
-        throw new Error(`Element ${new Locator(originalLocator).toString()} was not found by text|CSS|XPath`)
+    } 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
       }
-      throw err
     }
-    assertElementExists(text, contextAwareLocator)
-    this.debugSection('Text', text)
-    return text
   }
 
   /**
@@ -2460,7 +2855,6 @@ class Playwright extends Helper {
     for (const el of els) {
       texts.push(await el.innerText())
     }
-    this.debug(`Matched ${els.length} elements`)
     return texts
   }
 
@@ -2479,7 +2873,6 @@ class Playwright extends Helper {
    */
   async grabValueFromAll(locator) {
     const els = await findFields.call(this, locator)
-    this.debug(`Matched ${els.length} elements`)
     return Promise.all(els.map(el => el.inputValue()))
   }
 
@@ -2498,7 +2891,6 @@ class Playwright extends Helper {
    */
   async grabHTMLFromAll(locator) {
     const els = await this._locate(locator)
-    this.debug(`Matched ${els.length} elements`)
     return Promise.all(els.map(el => el.innerHTML()))
   }
 
@@ -2519,7 +2911,6 @@ class Playwright extends Helper {
    */
   async grabCssPropertyFromAll(locator, cssProperty) {
     const els = await this._locate(locator)
-    this.debug(`Matched ${els.length} elements`)
     const cssValues = await Promise.all(els.map(el => el.evaluate((el, cssProperty) => getComputedStyle(el).getPropertyValue(cssProperty), cssProperty)))
 
     return cssValues
@@ -2630,7 +3021,6 @@ class Playwright extends Helper {
    */
   async grabAttributeFromAll(locator, attr) {
     const els = await this._locate(locator)
-    this.debug(`Matched ${els.length} elements`)
     const array = []
 
     for (let index = 0; index < els.length; index++) {
@@ -2640,6 +3030,33 @@ class Playwright extends Helper {
     return array
   }
 
+  /**
+   * Retrieves the ARIA snapshot for an element using Playwright's [`locator.ariaSnapshot`](https://playwright.dev/docs/api/class-locator#locator-aria-snapshot).
+   * This method returns a YAML representation of the accessibility tree that can be used for assertions.
+   * If no locator is provided, it captures the snapshot of the entire page body.
+   *
+   * ```js
+   * const snapshot = await I.grabAriaSnapshot();
+   * expect(snapshot).toContain('heading "Sign up"');
+   *
+   * const formSnapshot = await I.grabAriaSnapshot('#login-form');
+   * expect(formSnapshot).toContain('textbox "Email"');
+   * ```
+   *
+   * [Learn more about ARIA snapshots](https://playwright.dev/docs/aria-snapshots)
+   *
+   * @param {string|object} [locator='//body'] element located by CSS|XPath|strict locator. Defaults to body element.
+   * @return {Promise<string>} YAML representation of the accessibility tree
+   */
+  async grabAriaSnapshot(locator = '//body') {
+    const matchedLocator = new Locator(locator)
+    const els = await this._locate(matchedLocator)
+    assertElementExists(els, locator)
+    const snapshot = await els[0].ariaSnapshot()
+    this.debugSection('Aria Snapshot', snapshot)
+    return snapshot
+  }
+
   /**
    * {{> saveElementScreenshot }}
    *
@@ -2647,16 +3064,10 @@ class Playwright extends Helper {
   async saveElementScreenshot(locator, fileName) {
     const outputFile = screenshotOutputFolder(fileName)
 
-    try {
-      const res = await this._locateElement(locator)
-      assertElementExists(res, locator)
-      const elem = res
-      this.debug(`Screenshot of ${new Locator(locator)} element has been saved to ${outputFile}`)
-      return elem.screenshot({ path: outputFile, type: 'png' })
-    } catch (err) {
-      this.debug(`Failed to take element screenshot: ${err.message}`)
-      throw err
-    }
+    const res = await this._locateElement(locator)
+    assertElementExists(res, locator)
+    const elem = res
+    return elem.screenshot({ path: outputFile, type: 'png' })
   }
 
   /**
@@ -2795,15 +3206,19 @@ class Playwright extends Helper {
     if (this.options.recordVideo && this.page && this.page.video()) {
       test.artifacts.video = saveVideoForPage(this.page, `${test.title}.failed`)
       for (const sessionName in this.sessionPages) {
-        test.artifacts[`video_${sessionName}`] = saveVideoForPage(this.sessionPages[sessionName], `${test.title}_${sessionName}.failed`)
+        if (sessionName === '') continue
+        test.artifacts[`video_${sessionName}`] = saveVideoForPage(this.sessionPages[sessionName], `${sessionName}_${test.title}.failed`)
       }
     }
 
     if (this.options.trace) {
       test.artifacts.trace = await saveTraceForContext(this.browserContext, `${test.title}.failed`)
       for (const sessionName in this.sessionPages) {
-        if (!this.sessionPages[sessionName].context) continue
-        test.artifacts[`trace_${sessionName}`] = await saveTraceForContext(this.sessionPages[sessionName].context, `${test.title}_${sessionName}.failed`)
+        if (sessionName === '') continue
+        const sessionPage = this.sessionPages[sessionName]
+        const sessionContext = sessionPage.context()
+        if (!sessionContext || !sessionContext.tracing) continue
+        test.artifacts[`trace_${sessionName}`] = await saveTraceForContext(sessionContext, `${sessionName}_${test.title}.failed`)
       }
     }
 
@@ -2817,7 +3232,8 @@ class Playwright extends Helper {
       if (this.options.keepVideoForPassedTests) {
         test.artifacts.video = saveVideoForPage(this.page, `${test.title}.passed`)
         for (const sessionName of Object.keys(this.sessionPages)) {
-          test.artifacts[`video_${sessionName}`] = saveVideoForPage(this.sessionPages[sessionName], `${test.title}_${sessionName}.passed`)
+          if (sessionName === '') continue
+          test.artifacts[`video_${sessionName}`] = saveVideoForPage(this.sessionPages[sessionName], `${sessionName}_${test.title}.passed`)
         }
       } else {
         this.page
@@ -2832,8 +3248,11 @@ class Playwright extends Helper {
         if (this.options.trace) {
           test.artifacts.trace = await saveTraceForContext(this.browserContext, `${test.title}.passed`)
           for (const sessionName in this.sessionPages) {
-            if (!this.sessionPages[sessionName].context) continue
-            test.artifacts[`trace_${sessionName}`] = await saveTraceForContext(this.sessionPages[sessionName].context, `${test.title}_${sessionName}.passed`)
+            if (sessionName === '') continue
+            const sessionPage = this.sessionPages[sessionName]
+            const sessionContext = sessionPage.context()
+            if (!sessionContext || !sessionContext.tracing) continue
+            test.artifacts[`trace_${sessionName}`] = await saveTraceForContext(sessionContext, `${sessionName}_${test.title}.passed`)
           }
         }
       } else {
@@ -2987,7 +3406,16 @@ class Playwright extends Helper {
 
     const context = await this._getContext()
     try {
-      await context.locator(buildLocatorString(locator)).first().waitFor({ timeout: waitTimeout, state: 'attached' })
+      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' })
+      }
     } catch (e) {
       throw new Error(`element (${locator.toString()}) still not present on page after ${waitTimeout / 1000} sec\n${e.message}`)
     }
@@ -3001,9 +3429,30 @@ class Playwright extends Helper {
   async waitForVisible(locator, sec) {
     const waitTimeout = sec ? sec * 1000 : this.options.waitForTimeout
     locator = new Locator(locator, 'css')
+
     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) {
@@ -3030,6 +3479,7 @@ class Playwright extends Helper {
   async waitForInvisible(locator, sec) {
     const waitTimeout = sec ? sec * 1000 : this.options.waitForTimeout
     locator = new Locator(locator, 'css')
+
     const context = await this._getContext()
     let waiter
     let count = 0
@@ -3060,6 +3510,7 @@ class Playwright extends Helper {
   async waitToHide(locator, sec) {
     const waitTimeout = sec ? sec * 1000 : this.options.waitForTimeout
     locator = new Locator(locator, 'css')
+
     const context = await this._getContext()
     let waiter
     let count = 0
@@ -3181,52 +3632,77 @@ 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.isCustom() ? `${locator.type}=${locator.value}` : locator.simplify()} >> text=${text}`)
+            .locator(`${locator.simplify()} >> text=${text}`)
             .first()
             .waitFor({ timeout: waitTimeout, state: 'visible' })
+            .catch(e => {
+              throw new Error(errorMessage)
+            })
         }
 
         if (locator.isXPath()) {
-          return contextObject.waitForFunction(
-            ([locator, text, $XPath]) => {
-              eval($XPath)
-              const el = $XPath(null, locator)
-              if (!el.length) return false
-              return el[0].innerText.indexOf(text) > -1
-            },
-            [locator.value, text, $XPath.toString()],
-            { timeout: waitTimeout },
-          )
+          return contextObject
+            .waitForFunction(
+              ([locator, text, $XPath]) => {
+                eval($XPath)
+                const el = $XPath(null, locator)
+                if (!el.length) return false
+                return el[0].innerText.indexOf(text) > -1
+              },
+              [locator.value, text, $XPath.toString()],
+              { timeout: waitTimeout },
+            )
+            .catch(e => {
+              throw new Error(errorMessage)
+            })
         }
       } catch (e) {
         throw new Error(`${errorMessage}\n${e.message}`)
       }
     }
 
+    // Based on original implementation but fixed to check title text and remove problematic promiseRetry
+    // Original used timeoutGap for waitForFunction to give it slightly more time than the locator
     const timeoutGap = waitTimeout + 1000
 
-    // We add basic timeout to make sure we don't wait forever
-    // We apply 2 strategies here: wait for text as innert text on page (wide strategy) - older
-    // or we use native Playwright matcher to wait for text in element (narrow strategy) - newer
-    // If a user waits for text on a page they are mostly expect it to be there, so wide strategy can be helpful even PW strategy is available
     return Promise.race([
-      new Promise((_, reject) => {
-        setTimeout(() => reject(errorMessage), waitTimeout)
-      }),
-      this.page.waitForFunction(text => document.body && document.body.innerText.indexOf(text) > -1, text, { timeout: timeoutGap }),
-      promiseRetry(
-        async retry => {
-          const textPresent = await contextObject
-            .locator(`:has-text(${JSON.stringify(text)})`)
-            .first()
-            .isVisible()
-          if (!textPresent) retry(errorMessage)
+      // Strategy 1: waitForFunction that checks both body AND title text
+      // Use this.page instead of contextObject because FrameLocator doesn't have waitForFunction
+      // Original only checked document.body.innerText, missing title text like "TestEd"
+      this.page.waitForFunction(
+        function (text) {
+          // Check body text (original behavior)
+          if (document.body && document.body.innerText && document.body.innerText.indexOf(text) > -1) {
+            return true
+          }
+          // Check document title (fixes the TestEd in title issue)
+          if (document.title && document.title.indexOf(text) > -1) {
+            return true
+          }
+          return false
         },
-        { retries: 1000, minTimeout: 500, maxTimeout: 500, factor: 1 },
+        text,
+        { timeout: timeoutGap },
       ),
-    ])
+      // Strategy 2: Native Playwright text locator (replaces problematic promiseRetry)
+      contextObject
+        .locator(`:has-text(${JSON.stringify(text)})`)
+        .first()
+        .waitFor({ timeout: waitTimeout }),
+    ]).catch(err => {
+      throw new Error(errorMessage)
+    })
   }
 
   /**
@@ -3356,7 +3832,7 @@ class Playwright extends Helper {
   /**
    * Waits for navigation to finish. By default, it takes configured `waitForNavigation` option.
    *
-   * See [Playwright's reference](https://playwright.dev/docs/api/class-page?_highlight=waitfornavi#pagewaitfornavigationoptions)
+   * See [Playwright's reference](https://playwright.dev/docs/api/class-page#page-wait-for-navigation)
    *
    * @param {*} options
    */
@@ -3832,6 +4308,195 @@ 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)
+  }
+  if (locator.isXPath()) {
+    return `xpath=${locator.value}`
+  }
+  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
+ * Returns elements array if role locator, null otherwise
+ */
+async function handleRoleLocator(context, locator) {
+  if (!isRoleLocatorObject(locator)) return null
+  
+  const options = {}
+  if (locator.text) options.name = locator.text
+  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})
+  const roleElements = await handleRoleLocator(matcher, locator)
+  if (roleElements) return roleElements
+
+  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')
+
+  return matcher.locator(buildLocatorString(locator)).first()
+}
+
+async function getVisibleElements(elements) {
+  const visibleElements = []
+  for (const element of elements) {
+    if (await element.isVisible()) {
+      visibleElements.push(element)
+    }
+  }
+  if (visibleElements.length === 0) {
+    return elements
+  }
+  return visibleElements
+}
+
 async function proceedClick(locator, context = null, options = {}) {
   let matcher = await this._getContext()
   if (context) {
@@ -3941,6 +4606,10 @@ async function findCheckable(locator, context) {
     contextEl = contextEl[0]
   }
 
+  // Handle role locators with text/exact options
+  const roleElements = await handleRoleLocator(contextEl, locator)
+  if (roleElements) return roleElements
+
   const matchedLocator = new Locator(locator)
   if (!matchedLocator.isFuzzy()) {
     return findElements.call(this, contextEl, matchedLocator)
@@ -3967,6 +4636,13 @@ async function proceedIsChecked(assertType, option) {
 }
 
 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
+  }
+
   const matchedLocator = new Locator(locator)
   if (!matchedLocator.isFuzzy()) {
     return this._locate(matchedLocator)
@@ -4145,9 +4821,7 @@ async function targetCreatedHandler(page) {
   if (this.options.windowSize && this.options.windowSize.indexOf('x') > 0 && this._getType() === 'Browser') {
     try {
       await page.setViewportSize(parseWindowSize(this.options.windowSize))
-    } catch (err) {
-      this.debug('Target can be already closed, ignoring...')
-    }
+    } catch (err) {}
   }
 }
 
@@ -4289,6 +4963,11 @@ async function refreshContextSession() {
   }
 
   try {
+    if (!this.page || !this.browserContext) {
+      this.debugSection('Session', 'Skipping storage cleanup - no active page/context')
+      return
+    }
+    
     const currentUrl = await this.grabCurrentUrl()
 
     if (currentUrl.startsWith('http')) {
@@ -4322,9 +5001,18 @@ function saveVideoForPage(page, name) {
 async function saveTraceForContext(context, name) {
   if (!context) return
   if (!context.tracing) return
-  const fileName = `${`${global.output_dir}${pathSeparator}trace${pathSeparator}${uuidv4()}_${clearString(name)}`.slice(0, 245)}.zip`
-  await context.tracing.stop({ path: fileName })
-  return fileName
+  try {
+    const fileName = `${`${global.output_dir}${pathSeparator}trace${pathSeparator}${uuidv4()}_${clearString(name)}`.slice(0, 245)}.zip`
+    await context.tracing.stop({ path: fileName })
+    return fileName
+  } catch (err) {
+    // Handle the case where tracing was not started or context is invalid
+    if (err.message && err.message.includes('Must start tracing before stopping')) {
+      // Tracing was never started on this context, silently skip
+      return null
+    }
+    throw err
+  }
 }
 
 async function highlightActiveElement(element) {