Testing iframes with Playwright

7 min read · TypeScript · 5 linked exercises

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.

Practise it
  • 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.

Practise it
  • 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().

Practise it

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.

Practise it
  • 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.

Practise it
  • 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');
Practise it

Exercises in this guide

More guides