TL;DR
- Use
frameLocator()when the control lives inside an iframe. - Capture a new tab with
page.waitForEvent('popup')when the opener is known. Use the browser context'spageevent when the opener is unknown. - Verify a known element on the returned page before using it for the next action.
Give each browser step an explicit target
A report widget lives inside an iframe. Its Open report link opens a new tab. Playwright needs the frame boundary to find the link, then a separate Page reference to check the report. The first reference changes where Playwright looks for elements. The second changes which tab receives the next command.
Many intermittently failing scripts use context.pages().at(-1) to identify the destination. That picks the last page in the current list. If another tab opened first or the target tab has yet to arrive, the script can continue on the wrong page. Tie the event to the action and verify the destination by a stable URL, heading or record identifier.
Scope selectors to the iframe
Use a stable iframe selector such as the iframe's title when you control the markup. Then write the same role- or label-based locator you would use for a top-level page. For nested widgets, chain frameLocator() at each boundary. Playwright can drive a permitted cross-origin iframe through its frame API. JavaScript evaluated in the top-level page is subject to browser origin rules when it tries to read a cross-origin frame.
If multiple frames have similar names, narrow the outer locator using the enclosing region or a stable test ID. Avoid indexing frames by their order on the page. A new hidden widget or consent panel can change that order.
Subscribe before the click
A popup opened by a known page can be captured through Playwright's popup event. Register the wait before triggering it. When the triggering page is unknown, register a page event listener on the intended browser context and assert the destination. Prefer keeping the task in its own context if multiple jobs may open pages.
The following example uses a fixture iframe that opens a new tab at about:blank and writes a known heading. Install playwright and Chromium, save it as tabs.mjs, then run node tabs.mjs.
import { chromium } from 'playwright';
const browser = await chromium.launch();
try {
const context = await browser.newContext();
const page = await context.newPage();
await page.setContent(`
<iframe title="Report picker" srcdoc="
<button onclick="const report = window.open('about:blank', '_blank');
report.document.body.innerHTML = '<h1>Monthly report</h1>';">
Open report
</button>
"></iframe>`);
const reportPicker = page.frameLocator('iframe[title="Report picker"]');
const [reportPage] = await Promise.all([
page.waitForEvent('popup', { timeout: 5000 }),
reportPicker.getByRole('button', { name: 'Open report' }).click({
timeout: 5000
})
]);
const heading = reportPage.getByRole('heading', { name: 'Monthly report' });
await heading.waitFor({ state: 'visible', timeout: 5000 });
console.log(await heading.textContent());
} finally {
await browser.close();
}
The heading is an explicit ready signal for this fixture. In a real report, check the expected origin or URL before entering data, then assert the user-facing record or heading. An event can fire while the new document is still initializing.
Try the flow in a remote session
Run an iframe-to-popup path on an authorized staging site with the Scrapeless Agent Browser free trial. Connect via the Playwright-compatible browser session and preserve the opener, frame and popup details in each action record. Scrapeless Agent Browser provides the remote Chromium session. Keep frame selection and tab routing in your Playwright code.
Handle navigation, frames and popups as distinct events
Some links navigate the same page. Others target a named tab and may reuse it. If your app opens a fresh tab on the first click and reuses it later, store the page reference and wait for the expected navigation or visible state on that page. Use the popup event for the branch that creates a new page.
A frame can also detach and remount when its parent rerenders. A frame locator resolves the target when you use it, while a stored handle can describe an earlier document. When a test fails, log which container matched, which page you observed and which assertion expired. These details help isolate the failing step in browser regression testing.
Conclusion
Model the iframe as an element scope and the new tab as a separate page. Arm the relevant event first and carry the resulting page reference forward with an explicit ready check.
FAQ
Do new tabs share login state? Pages in the same browser context use that context's cookie store. Origin-scoped storage rules and the application's login flow still apply.
When should the script use the context's page event? Use it when the opener is unknown or the workflow is deliberately listening for any new page in an isolated context.
Can a click from inside an iframe open a popup? Yes. An allowed frame interaction can open a popup associated with the containing page. Observe the popup on that page and verify the result.
How do you test a frame that never loads? Use an explicit timeout and log both the frame selector and the first required element inside it. The two checks help identify whether the iframe itself or its content failed to appear.

Top comments (0)