Testing iframes with Playwright
Payment forms, chat widgets, embedded editors and ads usually live in iframes: a separate document inside the page. Playwright's page locators don't look inside them, so a test that works on a normal form suddenly finds nothing.
This guide shows how to enter a frame, pick the right one when there are several, and handle frames that load late, navigate or open dialogs. All of it is practised on real embedded widgets, including a card payment form.
Enter the frame first
Find the <iframe> element with any locator, call contentFrame(), and use the usual locators from there:
const frame = page.getByTitle('Embedded Form').contentFrame();
await frame.getByLabel('Name').fill('Ada');
await frame.getByRole('button', { name: 'Submit' }).click();
await expect(frame.getByText('Hello, Ada')).toBeVisible();page.frameLocator(selector) does the same from a CSS selector: page.frameLocator('iframe[title="Newsletter signup"]').contentFrame() is usually nicer, because it starts from any locator, including getByTitle() and filtered or scoped ones.
Give your iframes a title. Screen readers announce it, and it gives your tests a stable, readable way to find the frame.
- iFrame BasicsBeginnerFill a form inside a frame and assert the result there.
The frame element and its document
An iframe has two sides. The <iframe> element belongs to the page and has attributes such as src, title and size. The document inside has the content. Assert attributes on the element, and content in the frame:
const frameElement = page.getByTitle('Newsletter signup');
await expect(frameElement).toHaveAttribute('src', '/embeds/newsletter/');
// From a frame back to its element
const frame = frameElement.contentFrame();
await expect(frame.owner()).toBeVisible();That also means a page-level getByText() can't see text inside a frame. That's useful in an assertion: it proves a message appeared inside the widget and not somewhere else on the page.
- iFrame BasicsBeginnerReach the iframe element from its frame with owner().
Nested frames and identical frames
For a frame inside a frame, chain contentFrame() calls, one per level:
const reviews = page
.getByTitle('Store').contentFrame()
.getByTitle('Reviews').contentFrame();
await reviews.getByRole('button', { name: 'Post review' }).click();When two frames have the same title, for example two payment widgets both titled "Payment", getByTitle('Payment') is a strict mode violation. Scope the frame by its surroundings, the same way you scope a button:
const proPayment = page
.getByRole('region', { name: 'Pro plan' })
.getByTitle('Payment')
.contentFrame();A frame without a title or name can still be found by its src: page.locator('iframe[src*="terms"]'). When you need the Frame object itself, for its URL or to evaluate script in it, use page.frame({ name }), page.frame({ url }) or page.frames().
- Nested & Multiple FramesIntermediateA frame inside a frame, two identical payment frames and an untitled one.
Late frames, navigation and dialogs
Locators inside a frame wait for the frame like any other locator. A chat widget that loads its iframe two seconds after you open it needs no special wait. The locator also survives navigation inside the frame, as in a multi-step checkout.
To check where the frame navigated, read the URL from the Frame object and poll it, because it changes without an event on the page:
await expect
.poll(() => page.frame({ url: /checkout/ })?.url())
.toContain('step=2');alert() and confirm() dialogs opened by a frame arrive at page.on('dialog'), the same as dialogs from the page. Register the handler before the click that opens them.
- Embedded WidgetsAdvancedA late chat frame, a checkout that navigates and a frame that opens a dialog.
Card payment forms
Payment providers put the card fields in an iframe, so your page never handles the card number. A checkout test therefore fills the address on the page, then the card inside the frame:
const payment = page.getByTitle('Secure payment').contentFrame();
await payment.getByLabel('Card number').fill('4111 1111 1111 1111');
// …then Expiry date, CVC and Name on card the same way
await payment.getByRole('button', { name: /^Pay/ }).click();
await expect(page.getByRole('heading', { name: /Thank you/ })).toBeVisible();After a declined payment, many forms reload inside the frame. The frame locator keeps working, but any value you read from it before the reload is stale. Read it again.
3-D Secure adds another layer: a bank window, often a dialog with its own iframe, opened from the payment frame. Handle it the same way: find the dialog, then enter its frame.
- First E2E TestIntermediateBuy a laptop in the Mini Shop and pay inside the payment iframe.
- Checkout Edge CasesAdvancedDeclined cards, 3-D Secure approval and a payment outage.
Mocking a frame
A third-party widget can make tests slow or unpredictable. The frame's document is an ordinary request, so page.route() can replace it. Set up the route before page.goto(), because the frame loads together with the page:
await page.route('**/embeds/weather/**', (route) =>
route.fulfill({
contentType: 'text/html',
body: '<p>Sunny, 21°C</p>',
}),
);
await page.goto('/frames/embeds');- Embedded WidgetsAdvancedReplace the Weather frame's document with your own.
Exercises in this guide
- iFrame BasicsBeginner
- Nested & Multiple FramesIntermediate
- Embedded WidgetsAdvanced
- First E2E TestIntermediate
- Checkout Edge CasesAdvanced
More guides
- Playwright practice for beginners: a four-week plan
- Playwright locators: a practical guide with exercises
- Playwright auto-waiting: how to fix flaky tests
- Playwright network mocking and API testing
- Playwright authentication: sign in once with storageState
- Playwright Page Object Model with fixtures
- File upload and download in Playwright
- Playwright Trace Viewer: how to debug failing tests
- Running Playwright tests in CI with GitHub Actions
- Playwright cheat sheet: locators, actions and assertions