What do Playwright's locator.contentFrame() and frameLocator.owner() do?

## An iframe has two addresses Any embedded document on an issue tracker -- the comment composer, a preview pane, a partner board widget -- can be talked about in two different ways, and Playwright gives each its own type: - the **`<iframe>` element** living in the parent document, addressed by a `Locator`: you can count it, assert it is visible, screenshot it, scroll it into view, read its `src`; - the **document inside it**, addressed by a `FrameLocator`: you chain element locators onto it and they resolve within that document. The two conversion methods are the bridge between those views, both added in Playwright 1.43 and current in 1.63: | Call | Direction | Returns | |---|---|---| | `locator.contentFrame()` | element -> contents | a `FrameLocator` for the document that iframe hosts | | `frameLocator.owner()` | contents -> element | a `Locator` for the `<iframe>` element itself | ## Why contentFrame() exists `page.frameLocator(selector)` already enters an iframe from a raw selector. `contentFrame()` matters when you have a **locator** rather than a selector -- because you built it, filtered it, indexed it, or were handed it by a helper. ```ts const previews = page.locator('iframe.preview'); await expect(previews).toHaveCount(2); await previews.nth(1).contentFrame().getByRole('link', { name: 'Open issue' }).click(); ``` That indexing form is also the supported way to disambiguate several matching iframes. `FrameLocator.first()`, `last()` and `nth()` still exist but are **deprecated**: the documented replacement is `locator.nth(i).contentFrame()`, which keeps all the indexing on the `Locator` side where the rest of the API lives. ## Why owner() exists Web-first assertions take a `Locator`, not a `FrameLocator`. When the thing under test is the embed itself, `owner()` is how you get back to it: ```ts const composer = page.frameLocator('iframe[title="Comment composer"]'); await expect(composer.owner()).toBeVisible(); await composer.owner().scrollIntoViewIfNeeded(); ``` Typical uses: 1. asserting the embed rendered at all before blaming its contents for a failure, 2. reading an attribute on the iframe element, such as the `src` a lazy loader swapped in, 3. taking a screenshot bounded to the embed rather than the whole issue view, 4. handing a helper one object it can both assert on and step into. ## Round trips and what stays lazy `page.locator('#composer').contentFrame().owner()` addresses the same element as `page.locator('#composer')`. Neither hop performs a query: both types are lazy descriptions, so a round trip costs nothing at build time and every use re-resolves the selector against the live DOM. That is why holding a `FrameLocator` across a re-render is safe in a way that holding a captured element is not. ## Choosing between them - Reaching **into** the embed from a plain selector: `page.frameLocator(selector)` is the shortest path. - Reaching **into** the embed from a locator you already narrowed: `contentFrame()`. - Asserting or acting **on** the embed element: `owner()`, or simply keep the original iframe locator around. - Picking one of several matching embeds: index the `Locator`, then convert -- `page.locator('iframe.preview').nth(1).contentFrame()`. ## Common mistakes - Passing a `FrameLocator` to `expect()` and expecting a visibility assertion; the matcher wants the `Locator` that `owner()` returns. - Reading `owner()` as "the parent frame". It is the iframe element this frame locator points at, not the frame above it. - Reaching for the deprecated `frameLocator.nth(1)` instead of `locator.nth(1).contentFrame()`. - Calling `owner()` on a frame locator built by the selector-less `page.frameLocator()`, which points at no particular iframe and does not support it.