Fix custom locator registration timing issue

Co-authored-by: kobenguyent <[email protected]>

Author: Copilot

lib/helper/Playwright.js

@@ -37,6 +37,7 @@ const { findReact, findVue, findByPlaywrightLocator } = require('./extras/Playwr
 let playwright
 let perfTiming
 let defaultSelectorEnginesInitialized = false
+let registeredCustomLocatorStrategies = new Set()
 
 const popupStore = new Popup()
 const consoleLogStore = new Console()
@@ -345,6 +346,7 @@ class Playwright extends Helper {
     this.recordedWebSocketMessagesAtLeastOnce = false
     this.cdpSession = null
     this.customLocatorStrategies = typeof config.customLocatorStrategies === 'object' && config.customLocatorStrategies !== null ? config.customLocatorStrategies : null
+    this._customLocatorsRegistered = false
 
     // override defaults with config
     this._setConfig(config)
@@ -470,9 +472,6 @@ class Playwright extends Helper {
       await playwright.selectors.register('__value', createValueEngine)
       await playwright.selectors.register('__disabled', createDisabledEngine)
       if (process.env.testIdAttribute) await playwright.selectors.setTestIdAttribute(process.env.testIdAttribute)
-
-      // Register custom locator strategies
-      await this._registerCustomLocatorStrategies()
     } catch (e) {
       console.warn(e)
     }
@@ -862,6 +861,10 @@ class Playwright extends Helper {
       this.debugSection('Url', target.url())
     })
 
+    // Register custom locator strategies for this helper instance
+    await this._registerCustomLocatorStrategies()
+    this._customLocatorsRegistered = true
+
     this.isRunning = true
     return this.browser
   }
@@ -893,6 +896,11 @@ class Playwright extends Helper {
   async _registerCustomLocatorStrategies() {
     if (this._isCustomLocatorStrategyDefined()) {
       for (const [strategyName, strategyFunction] of Object.entries(this.customLocatorStrategies)) {
+        // Skip if already registered
+        if (registeredCustomLocatorStrategies.has(strategyName)) {
+          continue
+        }
+
         try {
           this.debugSection('Playwright', `registering custom locator strategy: ${strategyName}`)
 
@@ -928,6 +936,7 @@ class Playwright extends Helper {
           `
 
           await playwright.selectors.register(strategyName, { content: selectorEngine })
+          registeredCustomLocatorStrategies.add(strategyName)
         } catch (error) {
           console.warn(`Failed to register custom locator strategy '${strategyName}':`, error)
         }
@@ -1167,6 +1176,9 @@ class Playwright extends Helper {
     const src = new Locator(srcElement)
     const dst = new Locator(destElement)
 
+    // Ensure custom locators are registered
+    await this._ensureCustomLocatorsRegistered()
+
     if (options) {
       return this.page.dragAndDrop(buildLocatorString(src), buildLocatorString(dst), options)
     }
@@ -1336,7 +1348,31 @@ class Playwright extends Helper {
    * const elements = await this.helpers['Playwright']._locate({name: 'password'});
    * ```
    */
+  async _ensureCustomLocatorsRegistered() {
+    // Only register once, and only if we have strategies defined
+    if (this._customLocatorsRegistered || !this._isCustomLocatorStrategyDefined()) {
+      return
+    }
+
+    try {
+      // If browser isn't running yet, start it to register selectors
+      if (!this.isRunning && !this.options.manualStart) {
+        await this._startBrowser()
+      } else {
+        // If browser is running but custom locators not registered, register them now
+        await this._registerCustomLocatorStrategies()
+      }
+      this._customLocatorsRegistered = true
+    } catch (error) {
+      console.warn('Failed to register custom locators:', error.message)
+      // Continue execution - the error will surface when the locator is actually used
+    }
+  }
+
   async _locate(locator) {
+    // Ensure custom locators are registered before any locator operations
+    await this._ensureCustomLocatorsRegistered()
+
     const context = await this._getContext()
 
     if (this.frame) return findElements(this.frame, locator)
@@ -1368,6 +1404,9 @@ class Playwright extends Helper {
    * ```
    */
   async _locateElement(locator) {
+    // Ensure custom locators are registered before any locator operations
+    await this._ensureCustomLocatorsRegistered()
+
     const context = await this._getContext()
     return findElement(context, locator)
   }
@@ -2649,6 +2688,9 @@ class Playwright extends Helper {
     const waitTimeout = sec ? sec * 1000 : this.options.waitForTimeout
     locator = new Locator(locator, 'css')
 
+    // Ensure custom locators are registered
+    await this._ensureCustomLocatorsRegistered()
+
     const context = await this._getContext()
     try {
       await context.locator(buildLocatorString(locator)).first().waitFor({ timeout: waitTimeout, state: 'attached' })
@@ -2665,6 +2707,10 @@ class Playwright extends Helper {
   async waitForVisible(locator, sec) {
     const waitTimeout = sec ? sec * 1000 : this.options.waitForTimeout
     locator = new Locator(locator, 'css')
+
+    // Ensure custom locators are registered
+    await this._ensureCustomLocatorsRegistered()
+
     const context = await this._getContext()
     let count = 0
 
@@ -2694,6 +2740,10 @@ class Playwright extends Helper {
   async waitForInvisible(locator, sec) {
     const waitTimeout = sec ? sec * 1000 : this.options.waitForTimeout
     locator = new Locator(locator, 'css')
+
+    // Ensure custom locators are registered
+    await this._ensureCustomLocatorsRegistered()
+
     const context = await this._getContext()
     let waiter
     let count = 0
@@ -2724,6 +2774,10 @@ class Playwright extends Helper {
   async waitToHide(locator, sec) {
     const waitTimeout = sec ? sec * 1000 : this.options.waitForTimeout
     locator = new Locator(locator, 'css')
+
+    // Ensure custom locators are registered
+    await this._ensureCustomLocatorsRegistered()
+
     const context = await this._getContext()
     let waiter
     let count = 0
@@ -2840,6 +2894,9 @@ class Playwright extends Helper {
     const waitTimeout = sec ? sec * 1000 : this.options.waitForTimeout
     const errorMessage = `Text "${text}" was not found on page after ${waitTimeout / 1000} sec.`
 
+    // Ensure custom locators are registered
+    await this._ensureCustomLocatorsRegistered()
+
     const contextObject = await this._getContext()
 
     if (context) {
@@ -3061,6 +3118,9 @@ class Playwright extends Helper {
     const waitTimeout = sec ? sec * 1000 : this.options.waitForTimeout
     locator = new Locator(locator, 'css')
 
+    // Ensure custom locators are registered
+    await this._ensureCustomLocatorsRegistered()
+
     let waiter
     const context = await this._getContext()
     if (!locator.isXPath()) {