How to Handle Playwright iFrames: A Complete Tutorial

What Are iFrames in Playwright?

In Playwright, an iFrame (inline frame) is an HTML element that embeds another webpage inside the current one. Each iFrame runs its own isolated browsing context, means it has its own DOM and JavaScript environment, separate from the main page.

When you're automating with Playwright, you often need to interact with elements inside these iFrames. For example, a payment form or a third-party widget. So, Playwright provides APIs to handle these types of use cases.

What Are Different Methods to Handle Playwright iFrames?

There are various methods to handle Playwright iFrames such as page.frame() that lets you access a specific frame in Playwright. Next is the page.frameLocator() that creates a locator that waits for the frame to load, making interactions with dynamic or nested frames more reliable.

page.frame()

This function returns a frame matching the specified criteria. To locate the frame using the frame() method, the name or URL of the frame must be supplied to this method. In the example below, you can locate the CodePen <iframe> name or the page URL.

Example:

frame = page.frame(name='codepen')
frame = page.frame(url=r'.*https://codepen.io/jaydeepkarale/pen/dygvXbm')

page.frame_locator()

When working with iframes in Playwright, you can create a frame locator that will enter the iframe and allow selecting of elements in that iframe.

The below code snippet will select the frame with '#iframe-window' and search for the text element 'LAMBDATEST BLOG'.

Example:

page.frame_locator('#iframe-window').get_by_text('LAMBDATEST BLOG')

The page.frame() and page.frame_locator() methods are available in all language APIs, but their naming convention might differ slightly. For example, in TypeScript API, frame_locator() is called frameLocator() by the language naming convention. But the functionality and use case remains the same.

How to Handle Playwright iFrames?

iFrames can be tricky to work with because they load separate browsing contexts inside a web page. In Playwright, you can handle both single and nested iFrames using methods like frame_locator() and frame(). This lets you locate, interact, and assert elements within embedded frames just like you would in a regular page.

We will use the Python programming language to write Playwright tests. For more information, check out this Playwright Python tutorial.

Test Scenario:

In this example, we'll test how Playwright handles iFrames using a custom CodePen page. The scenario involves:

• Loading a CodePen that embeds another site using nested iFrames.
• Rendering the TestMu AI blog inside the embedded frame.
• Searching for a specific blog titled “How To Use Playwright For Web Scraping with Python.”
• Verifying that the correct blog link and author profile URL appear in the rendered page.

Implementation:

The test uses frame_locator() to navigate through multiple iFrame layers and locate elements within them.

Below is the complete test code:

from playwright.sync_api import expect, Keyboard
from utilities.utilities import set_test_status
import re

def test_nested_iframe_can_be_loaded_correctly(page):
    """
    Test nested iframes can be rendered correctly with the {BrandName} blog website.
    Search for blog 'How To Use Playwright For Web Scraping with Python' by author Jaydeep Karale.
    Verify that the blog exists and author profile link is correct.
    """
    try:
        # Step 1: Navigate to CodePen containing nested iFrames
        page.goto('https://codepen.io/jaydeepkarale/pen/dygvXbm')

        # Step 2: Access the base iframe using frame_locator
        base_frame_locator = page.frame_locator("iframe[name="CodePen"]").frame_locator("#frame1")

        # Step 3: Fill blog URL and render
        base_frame_locator.get_by_placeholder("Enter a url").fill("https://www.lambdatest.com/blog")
        base_frame_locator.get_by_role("button", name="Render iframe").click()

        # Step 4: Search for the blog within the nested iframe
        base_frame_locator.frame_locator('#iframe-window').get_by_placeholder("Search …").fill('How To Use Playwright For Web Scraping with Python')
        page.keyboard.press('Enter')

        # Step 5: Locate blog title and author links
        blog_link_locator = base_frame_locator.frame_locator('#iframe-window').get_by_role('link', name='How To Use Playwright For Web Scraping with Python').first
        blog_author_locator = base_frame_locator.frame_locator('#iframe-window').get_by_role('link', name='Jaydeep Karale').first

        # Step 6: Validate attributes
        expect(blog_link_locator).to_have_attribute('href', re.compile('/blog/playwright-for-web-scraping/'))
        expect(blog_author_locator).to_have_attribute('href', 'https://www.lambdatest.com/learning-hub/author/jaydkarale/')

        # Step 7: Set test status and clean up
        set_test_status(page, 'Passed', 'Blog exists')
        page.pause()
        page.close()
    except Exception as ex:
        set_test_status(page, 'Failed', str(ex))

Code Walkthrough:

• Navigation: The test begins by visiting the CodePen URL using page.goto(). This page contains multiple nested iFrames.
• Frame Locator: The first frame_locator() identifies the main frame with the name "CodePen", followed by another frame identified by #frame1. This becomes the base frame for all further interactions.
• Render Blog: Within the base frame, the test fills in the TestMu AI blog URL in the input box labeled Enter a URL and clicks the Render iframe button to load the blog site.
• Search Action: Inside the nested iFrame (#iframe-window), it finds the search input and enters the target blog title, then simulates pressing Enter using page.keyboard.press().
• Element Verification: Once the blog results appear, the test locates the blog title and author link using getbyrole().
• Assertions: The expect() assertions confirm that the blog and author URLs are correct.
• Status Update: After validations, the test calls set_test_status() to record the outcome.

When running locally, this function doesn't affect anything; when you later switch to the cloud grid, it automatically updates the test status in your TestMu AI Web Automation dashboard. Finally, the test pauses for debugging and then closes the page.

Test Execution:

To run the test, execute the command below in your terminal:

pytest -v test_iframe_handling.py

LT_USERNAME=your-lambdatest-username
LT_ACCESS_KEY=your-lambdatest-access-key
RUN_ON=cloud
BROWSER=Chrome
PLATFORM=Windows 11

lt_cdp_url = 'wss://cdp.lambdatest.com/playwright?capabilities=' + urllib.parse.quote(json.dumps(capabilities))
browser = playwright.chromium.connect(lt_cdp_url)

pytest -v test_iframe_handling.py

Citations

• Playwright Official Documentation: https://playwright.dev/docs/intro
• Playwright Frame: https://playwright.dev/docs/api/class-frame