How do you handle multiple pages, tabs and popups?

Clicking a link with target=_blank or calling window.open creates another page in the same context. The new page is a separate Page object, so your locators on the original page will not see it. Wait for the event and keep the new reference.

const popupPromise = page.waitForEvent("popup");
await page.getByRole("link", { name: "Open invoice" }).click();
const popup = await popupPromise;

await popup.waitForLoadState();
await expect(popup.getByRole("heading", { name: "Invoice" })).toBeVisible();

The Promise.all pattern is equivalent and often reads better. It starts both operations together and returns the click result and the new page. Either way, the key is that the wait is set up before the action that opens the page.

const [popup] = await Promise.all([
  page.waitForEvent("popup"),
  page.getByRole("link", { name: "Open invoice" }).click(),
]);

await popup.getByRole("button", { name: "Download" }).click();
await popup.close();

Useful context methods

• context.pages() returns all open pages in the context
• context.waitForEvent("page") waits for a new page created by any action
• page.waitForEvent("popup") waits for a popup opened by that page
• page.close() closes one page without closing the context