fix: make XPath relative in buildLocatorString for within() scope (#5473)

Playwright's XPath engine auto-converts "//..." to ".//..." when searching
within an element, but only when the selector starts with "/". Locator methods
like at(), first(), last() wrap XPath in parentheses (e.g. "(//...)[position()=1]"),
bypassing that auto-conversion and causing XPath to search from the document root
instead of the within() scope.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: mirao

lib/helper/Playwright.js

@@ -4134,9 +4134,15 @@ class Playwright extends Helper {
 
 export default Playwright
 
-function buildLocatorString(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

test/unit/helper/Playwright_buildLocatorString_test.js

@@ -0,0 +1,49 @@
+import { expect } from 'chai'
+import Locator from '../../../lib/locator.js'
+import { buildLocatorString } from '../../../lib/helper/Playwright.js'
+
+describe('buildLocatorString', () => {
+  it('should make plain XPath relative', () => {
+    const locator = new Locator({ xpath: '//div' })
+    expect(buildLocatorString(locator)).to.equal('xpath=.//div')
+  })
+
+  it('should make XPath with parentheses (from at()) relative', () => {
+    const locator = new Locator('.item').at(1)
+    const result = buildLocatorString(locator)
+    expect(result).to.match(/^xpath=\(\.\/\//)
+  })
+
+  it('should make XPath from at().find() relative', () => {
+    const locator = new Locator('.item').at(1).find('.label')
+    const result = buildLocatorString(locator)
+    expect(result).to.match(/^xpath=\(\.\/\//)
+  })
+
+  it('should make XPath from first() relative', () => {
+    const locator = new Locator('.item').first()
+    const result = buildLocatorString(locator)
+    expect(result).to.match(/^xpath=\(\.\/\//)
+  })
+
+  it('should make XPath from last() relative', () => {
+    const locator = new Locator('.item').last()
+    const result = buildLocatorString(locator)
+    expect(result).to.match(/^xpath=\(\.\/\//)
+  })
+
+  it('should not double-prefix already relative XPath', () => {
+    const locator = new Locator({ xpath: './/div' })
+    expect(buildLocatorString(locator)).to.equal('xpath=.//div')
+  })
+
+  it('should handle XPath that was already relative inside parentheses', () => {
+    const locator = new Locator({ xpath: '(.//div)[1]' })
+    expect(buildLocatorString(locator)).to.equal('xpath=(.//div)[1]')
+  })
+
+  it('should return CSS locators unchanged', () => {
+    const locator = new Locator('.my-class')
+    expect(buildLocatorString(locator)).to.equal('.my-class')
+  })
+})