feat(locator): add locator.within()

[Yury Semikhatsky (yury-s)]

Summary

• locator.within(parent) is parent.locator(locator) in reading order, so relative locators like nth() resolve inside each parent element
• page.getByRole('cell').nth(2).within(page.getByRole('row')) matches the third cell of every row

Fixes #42842

[github-actions]

Test results for "tests 1"

1 failed
❌ [chromium-page] › page/page-event-request.spec.ts:281 › resource should have type image @realtime-time-library-chromium-linux

6 flaky

⚠️ [chromium-library] › library/chromium/chromium.spec.ts:213 › should intercept service worker requests (main and within) `@frozen-time-library-chromium-linux`
⚠️ [chromium-library] › library/video.spec.ts:762 › screencast › should work with video+trace `@chromium-ubuntu-22.04-arm-node20`
⚠️ [chromium-library] › library/video.spec.ts:725 › screencast › should capture full viewport on hidpi `@chromium-ubuntu-22.04-node20`
⚠️ [chromium-library] › library/browsercontext-page-event.spec.ts:173 › should work with Ctrl-clicking `@chromium-ubuntu-22.04-node22`
⚠️ [firefox-library] › library/browsercontext-cookies-third-party.spec.ts:257 › third party 'Partitioned;' cookies `@firefox-ubuntu-22.04-node20`
⚠️ [firefox-library] › library/browsercontext-cookies-third-party.spec.ts:470 › top level 'Partitioned;' cookie and same origin iframe `@firefox-ubuntu-22.04-node20`

52097 passed, 1241 skipped

---

Merge workflow run.

[github-actions]

🟢 The one failure is a pre-existing flake — this PR is clear

Hi, I'm the Playwright bot and I took a first look at the CI failures here.

page-event-request.spec.ts:281 times out in page.setContent on the same three SHAs that have nothing to do with locator.within(), including two runs on main.

Details

The diff is locator.within() — a client-side selector concatenation in client/locator.ts, plus docs, generated types, and a new test in tests/page/locator-query.spec.ts. Nothing in it touches navigation, setContent, or request/resource-type reporting, so there's no path from the change to the failing test. The 6 flaky results (service worker interception, screencast, third-party cookies) are likewise unrelated and all passed on retry.

Pre-existing flake / infra

• [chromium-page] › page/page-event-request.spec.ts:281 › <picture> resource should have type image — timed out on all 4 attempts with Error: page.setContent: Test timeout of 30000ms exceeded. Call log: - setting frame content, waiting until "load". The identical failure, same error text, appears in the results DB on runs this PR can't be responsible for:

  • 8dfd42c on main, run 31852438041 (chromium-macos-15-xlarge)
  • d506664 on main, run 32881822696 (chromium-macos-14-xlarge)
  • d1ead3e on main, run 34656353099 (firefox-macos-15-xlarge)

  It's a rare one: across the window the DB covers, chromium-page ran it 7871 times and it failed in 2 of them, and firefox-page 1900 times for 1 failure. setContent never completing is a hang in the harness, not something the test's <picture> subject would explain.

_{Triaged by the Playwright bot - agent run}

[github-actions]

Test results for "MCP"

4 failed
❌ [chrome] › mcp/cli-webmcp.spec.ts:162 › webmcp-call disambiguates duplicate tool names by frame @mcp-macos-latest-chrome
❌ [chrome] › mcp/cli-save-as.spec.ts:56 › screenshot --filename infers webp from extension @mcp-ubuntu-latest-chrome
❌ [chrome] › mcp/cli-webmcp.spec.ts:188 › webmcp-call disambiguates same-name tools in identical same-origin frames @mcp-ubuntu-latest-chrome
❌ [firefox] › mcp/cli-core.spec.ts:115 › hover @mcp-windows-latest-firefox

8701 passed, 1474 skipped

---

Merge workflow run.

[github-actions]

🟢 All four MCP failures are pre-existing flakes — this PR is clear

Hi, I'm the Playwright bot and I took a first look at the CI failures here.

Every failing test has failed the same way on SHAs that predate locator.within(), including several on main. The diff is a one-method client-side change plus docs, generated types, and a page test — it doesn't reach the MCP CLI at all.

Details

within() is four lines in packages/playwright-core/src/client/locator.ts that delegate to locator.locator(this), and the rest of the PR is docs/src/api/class-locator.md, the two generated types.d.ts, and one new test in tests/page/locator-query.spec.ts. Nothing in it touches WebMCP tool discovery, screenshot saving, or mouse input.

Pre-existing flake / infra

• [chrome] › mcp/cli-webmcp.spec.ts:162 › webmcp-call disambiguates duplicate tool names by frame and [chrome] › mcp/cli-webmcp.spec.ts:188 › webmcp-call disambiguates same-name tools in identical same-origin frames — both are a known race in frame enumeration: the second frame's tools aren't registered yet, so the run sees one echo instead of two. :162 has failed 6 of 106 chrome runs, :188 2 of 106, on SHAs this PR can't be responsible for:

  • :162 — 0a2a33c and 724115f on main (run 35754542981, run 35785374310), plus fix(network): resolve response.finished() when the request fails after the response #42787, fix(mcp): rebind page-registered WebMCP tools when the tab or frame changes #42821 and feat(webkit): roll to r2366 #42879.
  • :188 — 07f1a61 on main (run 35414323273), plus feat(test-runner): support locks in test.describe.configure #42792 and fix(firefox): preserve response header field boundaries #42832.

• [firefox] › mcp/cli-core.spec.ts:115 › hover — fails only on mcp-windows-latest-firefox, always with Expected substring: "mouse move 50 50" / Received string: "", i.e. the hover never lands. 5 of 722 firefox runs, including bee00ad and 3eb0ce9 on main (run 32426604698, run 34253996606), plus test(webkit): reenable WebSocket handshake HAR coverage #42513 and fix(clock): make Temporal.Now follow page.clock #42838.

• [chrome] › mcp/cli-save-as.spec.ts:56 › screenshot --filename infers webp from extension — the same test failed on 938796c (feat(mcp): add browser_emulate_media tool and --color-scheme option #42244, unrelated) with a 5s screenshot timeout while waiting for fonts. This is the thinnest of the four: that precedent is on firefox/Windows, and chrome itself is 734-for-734 in the results DB. mcp/cli-save-as.spec.ts flakes as a file though — screenshot <ref> fails periodically on main and unrelated PRs with TypeError: Cannot read properties of undefined (reading 'name') — and a screenshot-timing flake has no connection to a locator selector change, so I'm calling it flake rather than uncertain.

_{Triaged by the Playwright bot - agent run}