Playwright · Reliable end-to-end tests

How do you interact with iframes?

Mediumiframesframe locatornested framesUpdated Oct 2026

Short answer

Use page.frameLocator() to scope locators into an iframe without leaving the locator API. It supports nesting and auto-waiting, unlike manually switching into a Frame object.

An iframe has its own document, so a locator on the main page will not find elements inside it. frameLocator returns a frame-scoped locator factory. Every locator created from it is resolved inside that frame and keeps the usual waiting behaviour.

const payment = page.frameLocator("#payment-frame");

await payment.getByLabel("Card number").fill("4242424242424242");
await payment.getByLabel("Expiry").fill("12/30");
await payment.getByRole("button", { name: "Pay" }).click();

await expect(page.getByRole("heading", { name: "Receipt" })).toBeVisible();

Locators from frameLocator are scoped to the iframe, while assertions on the page remain outside it.

const checkout = page.frameLocator("#checkout-frame");
const cardForm = checkout.frameLocator("#card-frame");

await cardForm.getByLabel("Card number").fill("4242424242424242");

Nested frames are handled by chaining frameLocator calls.

frameLocator versus frame

frameLocator returns a lazy, auto-waiting locator scope and is the preferred API
page.frame() returns a Frame object for lower-level frame operations
Frame locators do not need a manual wait for the iframe to attach
An iframe can be cross-origin; Playwright still controls it through the browser
Use the frame's own URL or name only when a DOM locator cannot identify it

If the iframe is created lazily, create the frame locator after the element that triggers it, or simply rely on the locator to wait. Avoid storing a Frame object across a navigation, because the frame may be replaced and the old reference will be stale.

A frame locator is a scope, not an assertion target by itself. Assert on elements inside it, or on the iframe element in the parent page if you need to check that the frame is present.

Follow-ups you should expect

Interviewers use these to check whether the first answer was understanding or memorisation.

1Why can't a normal page locator find elements inside an iframe?
2How do you handle nested iframes?
3When would you use page.frame instead of frameLocator?
4Does Playwright support cross-origin iframes?

Say it in the interview

I use the frame locator for iframe content because it keeps the locator API, supports nesting and waits automatically. I scope every interaction through that frame locator, and I can still assert on the parent page outside the frame. I avoid holding a raw Frame object across navigations because it can go stale. For nested frames I chain frame locator calls.

Use this as a model, not a script. Saying it in your own words is what makes it survive follow-up pressure.

Now say it out loud.

Understanding an answer and delivering it under pressure are different skills. Rehearse this topic in a live Playwright mock interview and get scored feedback on depth, clarity and confidence.

Start a free Playwright interview Browse all questions

frameLocator versus frame

Follow-ups you should expect

Related questions

Now say it out loud.