What does calling Playwright's page.frameLocator() with no selector do?

## What the selector-less form does `page.frameLocator(selector)` has always taken a selector matching the `<iframe>` element you want to enter. Playwright 1.63 made that argument **optional**. Called with no selector, `page.frameLocator()` -- and `frame.frameLocator()` for a subtree -- starts the search in **any frame of the subtree**: the main frame or any iframe inside it, at any depth. ```ts // Finds the button whether it is on the page or inside an embed. await page.frameLocator().getByRole('button', { name: 'Add comment' }).click(); ``` The point is not to change how locators resolve. It is to remove the step where you name the iframe first, which matters when the markup around the embed is not yours to depend on. ## Only the start of the search changes This is the sentence to say in an interview: **only the start of the search is affected; the rest of the locator resolves inside a single frame, exactly like any other locator.** The chain does not roam across documents mid-way. Two consequences follow: - The usual one-match rule still applies within whichever frame supplied the match. - If the chain matches elements in **more than one frame**, the action fails rather than picking one. The error says the frame locator matched elements in multiple frames. That second case is the trap on an issue tracker: two card-preview embeds on a board, each with an "Open issue" link, and the any-frame search reports ambiguity only once both embeds have actually rendered -- which is a timing-dependent failure, not a deterministic one. ## What is not supported on it Because a selector-less frame locator does not point at a particular `<iframe>`, the members that describe *that* element are unavailable on it: | Member | On `page.frameLocator('#embed')` | On `page.frameLocator()` | |---|---|---| | `owner()` | returns the iframe element locator | not supported | | `first()` / `last()` / `nth(i)` | supported but deprecated | not supported | | `locator()`, `getByRole()`, other getters | supported | supported | If you need to narrow afterwards, do it the ordinary way: search for the iframe element anywhere, then convert. ```ts await page.frameLocator() .locator('#board-embed') .contentFrame() .getByRole('link', { name: 'Open issue' }) .click(); ``` ## When to reach for it 1. **Exploration and one-off reaches.** A quick check against an unfamiliar page, where you do not yet know which document holds the control. 2. **Markup you do not own.** A vendor embed whose wrapper attributes change between releases, while the control inside it is stable and accessibly named. 3. **A page with exactly one embed**, where naming the iframe adds a selector to maintain and buys nothing. And when not to: - Pages that render several similar embeds, where an explicit iframe selector turns a possible runtime ambiguity into an intention stated in the test. - Assertions about the embed element itself, which need `owner()` and therefore a frame locator that knows its iframe. - Hot paths in a large suite where an ambiguity that surfaces only under a particular render order is an expensive class of flake. ## Version notes The selector-less form is new in 1.63. Two practical implications: - A test using `page.frameLocator()` will not run on an older Playwright, so pin the version in the project rather than assuming a shared CI image is current. - Existing `page.frameLocator('#composer')` code is unaffected; the parameter became optional, and nothing about the explicit form changed. ## Failure signatures to recognise - `frameLocator() matched elements in multiple frames` -- the chain resolved in more than one document; narrow with an iframe selector or a more specific element locator. - A plain action timeout naming the chain -- nothing matched in any frame, so the target genuinely is not there yet. - A strict-mode error naming the chain -- several matches inside one frame, which is the ordinary one-match rule and has nothing to do with frames.