Interact Inside an iFrame

The concept

An <iframe> embeds a whole separate document in the page: payment forms, rich-text editors, maps and chat widgets often live in one. Locators on page search the main document only, so they cannot see elements inside the frame.

Playwright's page.frameLocator(selector) (or locator.contentFrame() in newer versions) returns a scope that searches inside the frame. You chain normal locators onto it, such as getByRole('textbox'), and Playwright handles waiting for the frame to load.

Choose a stable way to identify the frame itself: a title attribute or a meaningful name is better than its position on the page.

The fragile version

await page.getByRole('textbox', { name: 'Message' }).fill('Hello');

Why it breaks: If the textbox lives inside an iframe, this locator searches the parent page, never finds it, and times out with a misleading “element not found”.

A robust Playwright version

const editor = page.frameLocator('iframe[title="Message editor"]');
await editor.getByRole('textbox').fill('Hello from Playwright');
await expect(editor.getByRole('textbox')).toHaveText('Hello from Playwright');

The locator is scoped into the right frame, identified by its title, and the assertion checks inside the same frame.

This is a general example on a made-up page, not the challenge’s reference solution.

Common mistakes

• Searching the main page for elements that are inside a frame.
• Selecting the frame with iframe >> nth=0 when several frames exist.
• Using fill on a contenteditable editor without checking what role it exposes.

FAQ