playwright-multi-tab-window-handling

name	Playwright Multi-Tab & Window Handling
description	Teaches the agent to handle popups, new tabs, and multiple browser windows in Playwright using waitForEvent('page'), context pages, and reliable tab switching for OAuth and target=_blank links.
version	1.0.0
author	thetestingacademy
license	MIT
tags	["playwright","multi-tab","popup","new-window","oauth","browser-context","target-blank","automation"]
testingTypes	["e2e","integration"]
frameworks	["playwright"]
languages	["typescript"]
domains	["web"]
agents	["claude-code","cursor","github-copilot","windsurf","codex","aider","continue","cline","zed","bolt","gemini-cli","amp"]

Playwright Multi-Tab & Window Handling

This skill makes the agent write correct, race-free code for any flow that opens a second tab or popup: target="_blank" links, "Open in new window" buttons, OAuth/SSO consent screens, payment redirects, and PDF preview tabs. The central rule is that a new page is an event you must subscribe to before the click, never a thing you poll for afterward.

Use this skill whenever a test clicks something and a new tab/window appears, or whenever the agent sees page.waitForTimeout being used to "wait for the popup."

Core Principles

1. Subscribe before you click. Register context.waitForEvent('page') (or page.waitForEvent('popup')) before the action that triggers the popup, then await both together. Subscribing after the click is a race.
2. A tab belongs to a BrowserContext, not a Page. All tabs in one context share cookies/storage. context.pages() is the live list of open tabs.
3. Always await newPage.waitForLoadState() before asserting — the page object resolves the moment the tab exists, not when it has loaded.
4. Switch by holding a reference, never by index. Index order is not guaranteed across browsers. Capture the returned Page object.
5. Close popups you opened. Leaked tabs slow the suite and can hold modal focus. Close them or rely on context teardown.
6. Cross-origin popups are fine within a context. OAuth on a different domain still arrives as a page event; you do not need a new context.

Workflow / Patterns

Pattern 1 — Capture a popup from a target="_blank" link

The canonical, race-free shape uses Promise.all: start listening, then click, in one expression.

import { test, expect } from '@playwright/test';

test('opens docs in a new tab', async ({ context, page }) => {
  await page.goto('https://example.com/app');

  
   [newPage] =  .([
    context.(),
    page.(, { :  }).(),
  ]);

  
   newPage.();

   (newPage).();
   (newPage.(, { :  })).();

   newPage.();
  
   (page.(, { :  })).();
});