docs: multi-page scenarios

docs/README.md

@@ -59,6 +59,10 @@
     - [Client-side redirects](./loading.md#unusual-client-side-redirects)
     - [Navigation after a timeout](./loading.md#click-triggers-navigation-after-a-timeout)
 1. [Multi-page scenarios](./multi-pages.md)
+    - [Multiple contexts](./multi-pages.md#multiple-contexts)
+    - [Multiple pages](./multi-pages.md#multiple-pages)
+    - [Handling new pages](./multi-pages.md#handling-new-pages)
+    - [Handling popups](./multi-pages.md#handling-popups)
 1. [Test runners](./test-runners.md)
     - [Jest / Jasmine](./test-runners.md#jest--jasmine)
     - [AVA](./test-runners.md#ava)

docs/core-concepts.md

@@ -73,6 +73,7 @@ const context = await browser.newContext({
 #### API reference
 
 - [class `BrowserContext`](./api.md#class-browsercontext)
+- [browser.newContext([options])](./api.md#browsernewcontextoptions)
 
 <br/>
 

docs/multi-pages.md

@@ -1,68 +1,117 @@
 # Multi-page scenarios
 
-Playwright can run automation scenarios that span multiple isolated browser windows or multiple pages/tabs in a browser window.
+Playwright can automate scenarios that span multiple browser contexts or multiple
+tabs in a browser window.
 
 <!-- GEN:toc-top-level -->
 - [Multiple contexts](#multiple-contexts)
 - [Multiple pages](#multiple-pages)
-- [Popups and new pages](#popups-and-new-pages)
+- [Handling new pages](#handling-new-pages)
 - [Handling popups](#handling-popups)
 <!-- GEN:stop -->
 
 ## Multiple contexts
 
-In cases
+[Browser contexts](core-concepts.md#browser-contexts) are isolated environments
+on a single browser instance. Playwright can create multiple browser contexts
+within a single scenario. This is useful when you want to test for
+multi-user functionality, like chat.
 
 ```js
-// 
+const { chromium } = require('playwright');
+
+// Create a Chromium browser instance
+const browser = await chromium.launch();
+
+// Create two isolated browser contexts
+const userContext = await browser.newContext();
+const adminContext = await browser.newContext();
+
+// Load user and admin cookies
+await userContext.addCookies(userCookies);
+await adminContext.addCookies(adminCookies);
 ```
 
 #### API reference
 
-- [browserContext.addCookies(cookies)](api.md#browsercontextaddcookiescookies)
+- [class `BrowserContext`](./api.md#class-browsercontext)
+- [`browser.newContext([options])`](./api.md#browsernewcontextoptions)
+- [`browserContext.addCookies(cookies)`](api.md#browsercontextaddcookiescookies)
 
 ## Multiple pages
 
-* Each page created in Playwright behaves as if it was focused active page
+Each browser context can host multiple pages (tabs).
 
-## Popups and new pages
+* Each page behaves like a focused, active page. Bringing the page to front
+  is not required.
+* Pages inside a context respect context-level emulation, like viewport sizes,
+  custom network routes or browser locale.
 
 ```js
-const [popup] = await Promise.all([
-  page.waitForEvent('popup'),
-  page.click('#open')
-]);
+// Create two pages
+const pageOne = await context.newPage();
+const pageTwo = await context.newPage();
+
+// Get pages of a brower context
+const allPages = context.pages();
 ```
 
-```js
-// @ts-check
-const playwright = require("playwright");
+#### API reference
 
-(async () => {
-  const browser = await playwright.chromium.launch();
-  const context = await browser.newContext();
-  const page = await context.newPage();
+- [class `Page`](./api.md#class-page)
+- [`browserContext.newPage()`](./api.md#browsercontextnewpage)
+- [`browserContext.pages()`](./api.md#browsercontextpages)
 
-  // emulate some opening in a new tab or popup
+## Handling new pages
 
+The `page` event on browser contexts can be used to get new pages that are
+created in the context. This can be used to handle new pages opened by
+`target="_blank"` links.
 
+```js
+// Get page after a specific action (e.g. clicking a link)
 const [newPage] = await Promise.all([
   context.waitForEvent('page'),
-  // Replace this with submitting the form
   page.evaluate(() => window.open('https://google.com', '_blank'))
 ])
+await newPage.waitForLoadState();
 console.log(await newPage.title());
-// More steps with newPage
 
-  await page.waitForTimeout(2000)
-  await browser.close();
-})();
+// Get all new pages (including popups) in the context
+context.on('page', async page => {
+  await page.waitForLoadState();
+  await page.title();
+})
 ```
 
 #### API reference
 
-- [event: 'popup'](./api.md#event-popup)
+- [event: 'page'](./api.md#event-page)
 
 ## Handling popups
 
-https://github.com/microsoft/playwright/issues/2603
+If the page opens a pop-up, you can get a reference to it by listening to the
+`popup` event on the page.
+
+This event is emitted in addition to the `browserContext.on('page')` event, but
+only for popups relevant to this page.
+
+```js
+// Get popup after a specific action (e.g., click)
+const [popup] = await Promise.all([
+  page.waitForEvent('popup'),
+  page.click('#open')
+]);
+await popup.waitForLoadState();
+await popup.title();
+
+// Get all popups when they open
+page.on('popup', async popup => {
+  await popup.waitForLoadState();
+  await popup.title();
+})
+```
+
+#### API reference
+
+- [event: 'popup'](./api.md#event-popup)