feat: add pierceFrames() locator API

[Dmitry Gozman (dgozman)]

Summary

• New page.pierceFrames() and frame.pierceFrames() return a FrameLocator that searches for elements in the main frame and in all iframes on the page, based on the recently introduced pierce-frames selector.
• frameLocator() and first()/last()/nth() throw immediately when piercing frames; locator generators and parser render the new token as pierceFrames() / pierce_frames / PierceFrames.
• New EvaluationStalledError distinguishes stalled-frame evaluations: pierce mode skips stalled frames but propagates real errors such as strict mode violations; assertions now report non-recoverable errors like "matched elements from multiple frames".

References #12201.

[github-actions]

Test results for "MCP"

2 failed
❌ [firefox] › mcp/dashboard.spec.ts:108 › should activate session when show is called with -s @mcp-windows-latest-firefox
❌ [webkit] › mcp/video.spec.ts:23 › should work with recordVideo (persistent) @mcp-windows-latest-webkit

7793 passed, 1266 skipped

---

Merge workflow run.

[github-actions]

Test results for "tests 1"

9 flaky

⚠️ [chromium-library] › library/chromium/chromium.spec.ts:371 › should produce network events, routing, and annotations for Service Worker `@chromium-ubuntu-22.04-arm-node20`
⚠️ [chromium-library] › library/video.spec.ts:495 › screencast › should capture static page in persistent context Radoslav Kirilov (@smoke) `@chromium-ubuntu-22.04-arm-node20`
⚠️ [chromium-library] › library/video.spec.ts:664 › screencast › should capture full viewport `@chromium-ubuntu-22.04-arm-node20`
⚠️ [chromium-library] › library/video.spec.ts:294 › screencast › should capture navigation `@chromium-ubuntu-22.04-node24`
⚠️ [chromium-library] › library/video.spec.ts:736 › screencast › should work with video+trace `@chromium-ubuntu-22.04-node24`
⚠️ [chromium-library] › library/video.spec.ts:495 › screencast › should capture static page in persistent context Radoslav Kirilov (@smoke) `@chromium-ubuntu-22.04-node20`
⚠️ [chromium-library] › library/video.spec.ts:495 › screencast › should capture static page in persistent context Radoslav Kirilov (@smoke) `@chromium-ubuntu-22.04-node22`
⚠️ [firefox-page] › page/page-event-request.spec.ts:181 › should return response body when Cross-Origin-Opener-Policy is set `@firefox-ubuntu-22.04-node20`
⚠️ [webkit-library] › library/browsertype-connect.spec.ts:714 › run-server › should record trace with sources `@webkit-ubuntu-22.04-node20`

50624 passed, 1190 skipped

---

Merge workflow run.

[github-actions]

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

🟢 Both failures are pre-existing flakes — the PR looks clear

The two reds are MCP tests, and this PR only touches the pierceFrames() selector/locator path — no MCP code. I found both failing the same way on SHAs this PR can't be responsible for.

Details

This PR adds pierceFrames() (selector parsing, locator generators, frameSelectors.ts, client locator/frame/page, and server errors.ts/dialog.ts/frames.ts). None of that is exercised by the MCP dashboard or video flows.

Pre-existing flake / infra

• [firefox] › mcp/dashboard.spec.ts:108 › should activate session when show is called with -s (mcp-windows-latest-firefox) — pre-existing flake. Same test, same project, same expect(locator).toHaveAccessibleName(...) signature failed on 7 other unrelated runs in the test-results DB: PRs 41862, 41949, 41959 and three push builds (SHAs 244a1ffdd, 1299d0f6c, 3e14efd6b), across 2026-07-22/23. It passed 1262 times on firefox otherwise.

• [webkit] › mcp/video.spec.ts:23 › should work with recordVideo (persistent) (mcp-windows-latest-webkit) — infra flake. It timed out with MCP error -32000: Connect..., an MCP server connection timeout. That signature is not test-specific: it hits whatever MCP spec happens to be running, and shows up across many unrelated SHAs/PRs on webkit-windows (e.g. 41736, 41882, 41770, plus push builds — cookies, core, tabs, storage, tracing, annotate, etc.). Here it happened to land on video.spec.ts. The test itself passed 1308 times on webkit.

I'm a first pass, not the final word — but there's no evidence either failure is caused by this change.

_{Triaged by the Playwright bot - agent run}