Playwright iFrames

A shopping mall sometimes rents out a small kiosk to a separate business inside its walls. The kiosk operates independently, with its own staff and its own cash register, even though it physically sits inside the larger mall. An iframe works the same way on a webpage, embedding one website's content inside another as a self-contained section.

What an iFrame Actually Is

An iframe loads a completely separate webpage inside a small window on the main page. Payment providers commonly use iframes so a merchant's website never directly touches sensitive card details, keeping that information isolated inside the payment provider's own secure iframe.

A Page Containing an iFrame

Main Page (an online store)
  |-- Header
  |-- Product Details
  |-- iFrame (Payment Provider's Page)
  |     |-- Card Number Field
  |     |-- Expiry Date Field
  |     |-- Pay Now Button
  |-- Footer

Elements inside the iframe belong to a separate document entirely. A normal locator on the main page has no way to see or reach them directly.

Accessing Elements Inside an iFrame

const paymentFrame = page.frameLocator('#payment-frame');
await paymentFrame.getByLabel('Card Number').fill('4111111111111111');
await paymentFrame.getByLabel('Expiry Date').fill('12/28');
await paymentFrame.getByRole('button', { name: 'Pay Now' }).click();

The frameLocator method switches Playwright's focus into the iframe first. Every locator built from it then searches only within that embedded document.

A Real-World Example

An online furniture store lets a customer check out directly on its own page, but the actual payment form loads inside an iframe from a separate payment company. A test fills the shipping address on the main page normally, then switches into the payment iframe to complete the card details.

Confirming Content Inside an iFrame

await expect(paymentFrame.getByText('Payment Successful')).toBeVisible();

Assertions work exactly the same way inside an iframe as they do on the main page, once the correct frameLocator points into it.

Handling Nested iFrames

const outerFrame = page.frameLocator('#outer-frame');
const innerFrame = outerFrame.frameLocator('#inner-frame');
await innerFrame.getByRole('button', { name: 'Confirm' }).click();

Some pages embed an iframe inside another iframe. Chaining frameLocator calls step by step reaches elements buried this deeply.

Why Beginners Get Confused Here

Trying to locate an iframe's inner element using a normal page locator returns no match at all, with no clear error explaining why. Recognizing an iframe on the page early saves significant confusion during debugging.

Quick Practice Task

Open a website's checkout or contact form and inspect its HTML to check for an iframe. If one exists, note which fields sit inside it.

Key Takeaways

• An iframe embeds a separate document inside the main page.
• frameLocator switches Playwright's focus into that embedded document.
• Payment forms are a very common real-world example of iframes.
• Nested iframes need chained frameLocator calls to reach deeply.