Playwright frameLocator() searches across frames without a selector
Introduced 2026-09-04 · score 0.99
HOW TO USE IT
If the target may be in any frame in the page subtree, call `page.frameLocator()` without a selector, then chain the locator for the element and act on it. The locator resolves inside one frame; matches in multiple frames throw an error.
const locator = page.frameLocator().getByRole('button');
await locator.click();const locator = frame.frameLocator().getByRole('button');
await locator.click();WHY THIS HELPS
Locate an element that may appear in a frame anywhere in a page's frame subtree.
BEFORE THIS CHANGE
Locate the iframe first, then use its frame locator to search within it.
REQUIREMENTS AND LIMITATIONS
- Version: v1.63.0
- selector: Selector for the frame element. If omitted, search any frame on the page; for `frame.frameLocator()`, search this frame or any iframe inside it.
- getByRole(role) (required): Role used to locate the element; this usage example passes `button`.
- Prerequisite: `page.frameLocator` and `frame.frameLocator` were added in v1.17; use Playwright v1.17 or later.
- The rest of the locator resolves inside a single frame; an error is thrown when it matches elements in several frames.
FIRST-PARTY EVIDENCE
- https://github.com/microsoft/playwright/releases/tag/v1.63.0
- https://playwright.dev/docs/api/class-page#page-frame-locator
- https://playwright.dev/docs/api/class-frame#frame-frame-locator
Check the installed version and the source before using it. Entry JSON