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

mirao · claude · web-flow · commit c61c2e5a1a23 · 2026-03-08T01:07:58.000Z
* 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> * test: add acceptance test for locate().at().find() inside within() (#5473) Adds a Playwright acceptance test that verifies XPath from locate().at().find() is correctly scoped when used inside within(). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
diff --git a/lib/helper/Playwright.js b/lib/helper/Playwright.js
@@ -4157,9 +4157,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
diff --git a/test/acceptance/within_test.js b/test/acceptance/within_test.js
@@ -1,5 +1,12 @@
 Feature('within', { retries: 3 })
 
+Scenario('within with locate().at().find() should scope XPath @Playwright', async ({ I }) => {
+  I.amOnPage('/form/bug5473')
+  await within('#list2', async () => {
+    await I.see('Second', locate('.item').at(1).find('.label'))
+  })
+})
+
 Scenario('within on form @WebDriverIO @Puppeteer @Playwright', async ({ I }) => {
   I.amOnPage('/form/bug1467')
   I.see('TEST TEST')
diff --git a/test/data/app/view/form/bug5473.php b/test/data/app/view/form/bug5473.php
@@ -0,0 +1,14 @@
+<!doctype html>
+<html>
+    <head><title>within + locate().at() bug</title></head>
+    <body>
+        <div id="outer">
+            <ul id="list1">
+                <li class="item"><span class="label">First</span></li>
+            </ul>
+            <ul id="list2">
+                <li class="item"><span class="label">Second</span></li>
+            </ul>
+        </div>
+    </body>
+</html>
diff --git a/test/unit/helper/Playwright_buildLocatorString_test.js b/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')
+  })
+})
