fix(docs): fix snippets, integrate navigations to ToC and core concepts (#1884)

docs/README.md

@@ -34,6 +34,11 @@
 1. Scraping and verification
     - Screenshots
     - Evaluation
+1. [Navigation and loading](./loading.md)
+    - [Common scenarios](./loading.md#common-scenarios)
+    - [Loading a popup](./loading.md#loading-a-popup)
+    - [Client-side redirects](./loading.md#unusual-client-side-redirects)
+    - [Navigation after a timeout](./loading.md#click-triggers-navigation-after-a-timeout)
 1. [Continuous integration](./ci.md)
     - [Docker](./ci.md#docker)
     - [GitHub Actions](./ci.md#github-actions)
@@ -46,8 +51,7 @@
     - Mocha
     - Karma
     - Jasmine
-    - Jasmine
     - Storybooks
 1. [Extensibility](./extensibility.md)
     - [Custom selector engines](./extensibility.md#custom-selector-engines)
-
+1. [API Reference](./api.md)

docs/core-concepts.md

@@ -78,13 +78,30 @@ const context = await browser.newContext({
 ## Pages and frames
 
 A Browser context can have multiple pages. A [`Page`](../api.md#class-page)
-refers to a single tab or a popup window within a browser context. A page can be used to navigate
-to URLs and then interact with elements.
+refers to a single tab or a popup window within a browser context. It should be used to navigate to URLs and interact with the page content.
 
 ```js
+// Create a page.
 const page = await context.newPage();
+```
+
+```js
+// Navigate explicitly, similar to entering a URL in the browser.
 await page.goto('http://example.com');
+// Fill an input.
+await page.fill('#search', 'query');
+```
+
+```js
+// Navigate implicitly by clicking a link.
 await page.click('#submit');
+// Expect a new url.
+console.log(page.url());
+```
+
+```js
+// Page can navigate from the script - this will be picked up by Playwright.
+window.location.href = 'https://example.com';
 ```
 
 A page can have one or more [Frame](../api.md#class-frame) objects attached to
@@ -105,6 +122,8 @@ await frame.fill('#username-input', 'John');
 - [class `Page`](./api.md#class-page)
 - [class `Frame`](./api.md#class-frame)
 
+To learn more about navigation and loading, read [this document](loading.md).
+
 <br/>
 
 ## Selectors

docs/emulation.md

@@ -46,7 +46,6 @@ Create a context with custom viewport size:
     height: 1024
   }
 });
-
 ```
 Resize viewport for individual pages:
 
@@ -144,6 +143,7 @@ Grant notifications access from a specific domain:
 ```js
 await context.grantPermissions(['notifications'], {origin: 'https://skype.com'} );
 ```
+
 Revoke all permissions:
 ```js
 await context.clearPermissions();
@@ -170,6 +170,7 @@ Change the location later:
 ```js
 await context.setGeolocation({ longitude: 29.979097, latitude: 31.134256 };
 ```
+
 **Note** you can only change geolocation for all pages in the context.
 
 #### API reference

docs/input.md

@@ -31,7 +31,6 @@ await page.fill('#time', '13-15');
 
 // <input id=local type=datetime-local>
 await page.fill('#local', '2020-03-02T05:15');
-
 ```
 
 #### API reference
@@ -131,7 +130,7 @@ await page.dblclick('#item');
 await page.click('#item', { button: 'right' });
 
 // Shift click element
-await page.click('#item', { modifiers: 'Shift' });
+await page.click('#item', { modifiers: ['Shift'] });
 
 // Hover over element without clicking
 await page.hover('#item');

docs/loading.md

@@ -8,23 +8,23 @@ Page navigation can be either initiated by the Playwright call:
 
 ```js
 // Load a page
-await page.goto('https://example.com')
+await page.goto('https://example.com');
 
 // Reload a page
-await page.reload()
+await page.reload();
 
 // Click a link
-await page.click('text="Continue"')
+await page.click('text="Continue"');
 ```
 
 or by the page itself:
 
 ```js
 // Programmatic navigation
-window.location.href = 'https://example.com'
+window.location.href = 'https://example.com';
 
 // Single page app navigation
-history.pushState({}, 'title', '#deep-link')
+history.pushState({}, 'title', '#deep-link');
 ```
 
 Navigation intent may result in being canceled, for example transformed into a download or hitting an unresolved DNS address. Only when the navigation succeeds, page starts **loading** the document.
@@ -66,9 +66,9 @@ Explicit loading handling may be required for more complicated scenarios though.
 
 When popup is opened, explicitly calling [`page.waitForLoadState()`](#pagewaitforloadstatestate-options) ensures that popup is loaded to the desired state.
 ```js
-const { popup } = await Promise.all([
+const [ popup ] = await Promise.all([
   page.waitForEvent('popup'),
-  page.click('a[target="_blank"]')  // <-- opens popup
+  page.click('a[target="_blank"]'),  // <-- opens popup
 ]);
 await popup.waitForLoadState('load');
 await popup.evaluate(() => window.globalVariableInitializedByOnLoadHandler);

docs/network.md

@@ -24,7 +24,7 @@ const context = await browser.newContext({
   },
 });
 const page = await context.newPage();
-awat page.goto('https://example.com');
+await page.goto('https://example.com');
 ```
 
 You can also use [`browserContext.setHTTPCredentials`](./api.md#browsercontextsethttpcredentialshttpcredentials) to update HTTP credentials of an existing context.
@@ -77,7 +77,7 @@ const { chromium, webkit, firefox } = require('playwright');
   const browser = await chromium.launch();
   const page = await browser.newPage();
 
-  // Subscribe to 'request' and 'response' events.S
+  // Subscribe to 'request' and 'response' events.
   page.on('request', request =>
       console.log('>>', request.method(), request.url()));
   page.on('response', response =>
@@ -91,8 +91,9 @@ const { chromium, webkit, firefox } = require('playwright');
 Or wait for a network response after the button click:
 
 ```js
+// Use a glob URL pattern
 const [response] = await Promise.all([
-  page.waitForResponse('/api/fetch_data'),
+  page.waitForResponse('**/api/fetch_data'),
   page.click('button#update'),
 ]);
 ```
@@ -100,15 +101,15 @@ const [response] = await Promise.all([
 #### Variations
 
 ```js
-// User glob URL pattern
+// Use a RegExp
 const [response] = await Promise.all([
-  page.waitForResponse('**/*'),
+  page.waitForResponse(/\.jpeg$/),
   page.click('button#update'),
 ]);
 
-// User pattern predicate
+// Use a predicate taking a Response object
 const [response] = await Promise.all([
-  page.waitForResponse(url => url.includes(token)),
+  page.waitForResponse(response => response.url().includes(token)),
   page.click('button#update'),
 ]);
 ```
@@ -129,7 +130,7 @@ const [response] = await Promise.all([
 You can mock API endpoints via handling the network quests in your Playwright script.
 
 ```js
-await page.route('/api/fetch_data', route => route.fulfill({
+await page.route('**/api/fetch_data', route => route.fulfill({
   status: 200,
   body: testData,
 }));
@@ -142,7 +143,7 @@ await page.goto('https://example.com');
 // Set up route on the entire browser context.
 // It will apply to popup windows and opened links.
 
-await browserContext.route('/api/login', route => route.fulfill({
+await browserContext.route('**/api/login', route => route.fulfill({
   status: 200,
   body: 'accept',
 }));
@@ -177,8 +178,7 @@ You can continue requests with modifications. Example above removes an HTTP head
 ```js
 // Continue requests as POST.
 
-await page.route('**/*', route =>
-    route.continue({method: 'POST'}));
+await page.route('**/*', route => route.continue({method: 'POST'}));
 await page.goto('https://chromium.org');
 ```