docs: various doc improvements (#9396)

See commits for details.

Closes #1837, #5880, #7822, #8101, #8821, #9367, #9382, #9378, #4731

docs/api/index.md

@@ -35,7 +35,7 @@ sidebar_label: API
 | [Puppeteer](./puppeteer.puppeteer.md)             | <p>The main Puppeteer class.</p><p>IMPORTANT: if you are using Puppeteer in a Node environment, you will get an instance of [PuppeteerNode](./puppeteer.puppeteernode.md) when you import or require <code>puppeteer</code>. That class extends <code>Puppeteer</code>, so has all the methods documented below as well as all that are defined on [PuppeteerNode](./puppeteer.puppeteernode.md).</p>                                                                                                                                                                                                                                                                                                                   |
 | [PuppeteerNode](./puppeteer.puppeteernode.md)     | <p>Extends the main [Puppeteer](./puppeteer.puppeteer.md) class with Node specific behaviour for fetching and downloading browsers.</p><p>If you're using Puppeteer in a Node environment, this is the class you'll get when you run <code>require('puppeteer')</code> (or the equivalent ES <code>import</code>).</p>                                                                                                                                                                                                                                                                                                                                                                                                  |
 | [SecurityDetails](./puppeteer.securitydetails.md) | The SecurityDetails class represents the security details of a response that was received over a secure connection.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
-| [Target](./puppeteer.target.md)                   |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| [Target](./puppeteer.target.md)                   | Target represents a [CDP target](https://chromedevtools.github.io/devtools-protocol/tot/Target/). In CDP a target is something that can be debugged such a frame, a page or a worker.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | [TimeoutError](./puppeteer.timeouterror.md)       | TimeoutError is emitted whenever certain operations are terminated due to timeout.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
 | [Touchscreen](./puppeteer.touchscreen.md)         | The Touchscreen class exposes touchscreen events.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | [Tracing](./puppeteer.tracing.md)                 | The Tracing class exposes the tracing audit interface.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |

docs/api/puppeteer.browser.md

@@ -25,7 +25,7 @@ The constructor for this class is marked as internal. Third-party code should no
 An example of using a [Browser](./puppeteer.browser.md) to create a [Page](./puppeteer.page.md):
 
 ```ts
-const puppeteer = require('puppeteer');
+import puppeteer from 'puppeteer';
 
 (async () => {
   const browser = await puppeteer.launch();
@@ -40,7 +40,7 @@ const puppeteer = require('puppeteer');
 An example of disconnecting from and reconnecting to a [Browser](./puppeteer.browser.md):
 
 ```ts
-const puppeteer = require('puppeteer');
+import puppeteer from 'puppeteer';
 
 (async () => {
   const browser = await puppeteer.launch();

docs/api/puppeteer.dialog.md

@@ -19,7 +19,7 @@ The constructor for this class is marked as internal. Third-party code should no
 ## Example
 
 ```ts
-const puppeteer = require('puppeteer');
+import puppeteer from 'puppeteer';
 
 (async () => {
   const browser = await puppeteer.launch();

docs/api/puppeteer.elementhandle.md

@@ -19,7 +19,7 @@ export declare class ElementHandle<ElementType extends Node = Element> extends J
 ElementHandles can be created with the [Page.$()](./puppeteer.page._.md) method.
 
 ```ts
-const puppeteer = require('puppeteer');
+import puppeteer from 'puppeteer';
 
 (async () => {
   const browser = await puppeteer.launch();

docs/api/puppeteer.elementhandle.waitforselector.md

@@ -39,7 +39,7 @@ Throws if an element matching the given selector doesn't appear.
 ## Example
 
 ```ts
-const puppeteer = require('puppeteer');
+import puppeteer from 'puppeteer';
 
 (async () => {
   const browser = await puppeteer.launch();

docs/api/puppeteer.elementhandle.waitforxpath.md

@@ -19,7 +19,7 @@ sidebar_label: ElementHandle.waitForXPath
 > This method works across navigation.
 >
 > ```ts
-> const puppeteer = require('puppeteer');
+> import puppeteer from 'puppeteer';
 > (async () => {
 >   const browser = await puppeteer.launch();
 >   const page = await browser.newPage();

docs/api/puppeteer.frame.md

@@ -31,7 +31,7 @@ At any point in time, [pages](./puppeteer.page.md) expose their current frame tr
 An example of dumping frame tree:
 
 ```ts
-const puppeteer = require('puppeteer');
+import puppeteer from 'puppeteer';
 
 (async () => {
   const browser = await puppeteer.launch();

docs/api/puppeteer.frame.waitforfunction.md

@@ -38,7 +38,7 @@ the promise which resolve when the `pageFunction` returns a truthy value.
 The `waitForFunction` can be used to observe viewport size change:
 
 ```ts
-const puppeteer = require('puppeteer');
+import puppeteer from 'puppeteer';
 
 (async () => {
 .  const browser = await puppeteer.launch();

docs/api/puppeteer.frame.waitforselector.md

@@ -39,7 +39,7 @@ Throws if an element matching the given selector doesn't appear.
 ## Example
 
 ```ts
-const puppeteer = require('puppeteer');
+import puppeteer from 'puppeteer';
 
 (async () => {
   const browser = await puppeteer.launch();

docs/api/puppeteer.page.emulatevisiondeficiency.md

@@ -29,7 +29,7 @@ Promise<void>
 ## Example
 
 ```ts
-const puppeteer = require('puppeteer');
+import puppeteer from 'puppeteer';
 
 (async () => {
   const browser = await puppeteer.launch();

docs/api/puppeteer.page.exposefunction.md

@@ -45,8 +45,8 @@ Promise<void>
 An example of adding an `md5` function into the page:
 
 ```ts
-const puppeteer = require('puppeteer');
-const crypto = require('crypto');
+import puppeteer from 'puppeteer';
+import crypto from 'crypto';
 
 (async () => {
   const browser = await puppeteer.launch();
@@ -70,8 +70,8 @@ const crypto = require('crypto');
 An example of adding a `window.readfile` function into the page:
 
 ```ts
-const puppeteer = require('puppeteer');
-const fs = require('fs');
+import puppeteer from 'puppeteer';
+import fs from 'fs';
 
 (async () => {
   const browser = await puppeteer.launch();

docs/api/puppeteer.page.md

@@ -29,7 +29,7 @@ The constructor for this class is marked as internal. Third-party code should no
 This example creates a page, navigates it to a URL, and then saves a screenshot:
 
 ```ts
-const puppeteer = require('puppeteer');
+import puppeteer from 'puppeteer';
 
 (async () => {
   const browser = await puppeteer.launch();
@@ -157,7 +157,7 @@ page.off('request', logRequest);
 | [waitForSelector(selector, options)](./puppeteer.page.waitforselector.md)                   |           | <p>Wait for the <code>selector</code> to appear in page. If at the moment of calling the method the <code>selector</code> already exists, the method will return immediately. If the <code>selector</code> doesn't appear after the <code>timeout</code> milliseconds of waiting, the function will throw.</p><p>This method works across navigations:</p>                                                                                                                                                                                                                                              |
 
 ```ts
-const puppeteer = require('puppeteer');
+import puppeteer from 'puppeteer';
 (async () => {
   const browser = await puppeteer.launch();
   const page = await browser.newPage();
@@ -181,7 +181,7 @@ const puppeteer = require('puppeteer');
 | [waitForXPath(xpath, options)](./puppeteer.page.waitforxpath.md) | | <p>Wait for the <code>xpath</code> to appear in page. If at the moment of calling the method the <code>xpath</code> already exists, the method will return immediately. If the <code>xpath</code> doesn't appear after the <code>timeout</code> milliseconds of waiting, the function will throw.</p><p>This method works across navigation</p>
 
 ```ts
-const puppeteer = require('puppeteer');
+import puppeteer from 'puppeteer';
 (async () => {
   const browser = await puppeteer.launch();
   const page = await browser.newPage();

docs/api/puppeteer.page.setrequestinterception.md

@@ -33,7 +33,7 @@ Promise<void>
 An example of a naïve request interceptor that aborts all image requests:
 
 ```ts
-const puppeteer = require('puppeteer');
+import puppeteer from 'puppeteer';
 (async () => {
   const browser = await puppeteer.launch();
   const page = await browser.newPage();

docs/api/puppeteer.page.waitforfunction.md

@@ -38,7 +38,7 @@ Promise<[HandleFor](./puppeteer.handlefor.md)<Awaited<ReturnType<Fun
 The [Page.waitForFunction()](./puppeteer.page.waitforfunction.md) can be used to observe viewport size change:
 
 ```ts
-const puppeteer = require('puppeteer');
+import puppeteer from 'puppeteer';
 (async () => {
   const browser = await puppeteer.launch();
   const page = await browser.newPage();

docs/api/puppeteer.page.waitforselector.md

@@ -9,7 +9,7 @@ Wait for the `selector` to appear in page. If at the moment of calling the metho
 This method works across navigations:
 
 ```ts
-const puppeteer = require('puppeteer');
+import puppeteer from 'puppeteer';
 (async () => {
   const browser = await puppeteer.launch();
   const page = await browser.newPage();

docs/api/puppeteer.page.waitforxpath.md

@@ -9,7 +9,7 @@ Wait for the `xpath` to appear in page. If at the moment of calling the method t
 This method works across navigation
 
 ```ts
-const puppeteer = require('puppeteer');
+import puppeteer from 'puppeteer';
 (async () => {
   const browser = await puppeteer.launch();
   const page = await browser.newPage();

docs/api/puppeteer.puppeteernode.md

@@ -29,7 +29,7 @@ The constructor for this class is marked as internal. Third-party code should no
 The following is a typical example of using Puppeteer to drive automation:
 
 ```ts
-const puppeteer = require('puppeteer');
+import puppeteer from 'puppeteer';
 
 (async () => {
   const browser = await puppeteer.launch();

docs/api/puppeteer.target.md

@@ -4,6 +4,8 @@ sidebar_label: Target
 
 # Target class
 
+Target represents a [CDP target](https://chromedevtools.github.io/devtools-protocol/tot/Target/). In CDP a target is something that can be debugged such a frame, a page or a worker.
+
 #### Signature:
 
 ```typescript

docs/guides/chrome-extensions.md

@@ -14,10 +14,11 @@ The following is code for getting a handle to the
 an extension whose source is located in `./my-extension`:
 
 ```ts
-const puppeteer = require('puppeteer');
+import puppeteer from 'puppeteer';
+import path from 'path';
 
 (async () => {
-  const pathToExtension = require('path').join(__dirname, 'my-extension');
+  const pathToExtension = path.join(process.cwd(), 'my-extension');
   const browser = await puppeteer.launch({
     headless: 'chrome',
     args: [

docs/guides/configuration.mdx

@@ -17,6 +17,12 @@ as `HTTPS_PROXY`).
 
 :::
 
+:::caution
+
+Puppeteer's configuration files and environment variables are ignored by `puppeteer-core`.
+
+:::
+
 ## Configuration files
 
 Configuration files are the **recommended** choice for configuring Puppeteer.

docs/guides/evaluate-javascript.md

@@ -0,0 +1,107 @@
+# Evaluate JavaScript
+
+Puppeteer allows evaluating JavaScript functions in the context of the page
+driven by Puppeteer:
+
+```ts
+// Import puppeteer
+import puppeteer from 'puppeteer';
+
+(async () => {
+  // Launch the browser
+  const browser = await puppeteer.launch();
+
+  // Create a page
+  const page = await browser.newPage();
+
+  // Go to your site
+  await page.goto('YOUR_SITE');
+
+  // Evaluate JavaScript
+  const three = await page.evaluate(() => {
+    return 1 + 2;
+  });
+
+  console.log(three);
+
+  // Close browser.
+  await browser.close();
+})();
+```
+
+:::caution
+
+Although the function is defined in your script context, it actually gets
+stringified by Puppeteer, sent to the target page over Chrome DevTools protocol
+and evaluated there. It means that the function cannot access scope variables in
+your script.
+
+:::
+
+Alternatively, you can provide a function body as a string:
+
+```ts
+// Evaluate JavaScript
+const three = await page.evaluate(`
+    1 + 2
+`);
+```
+
+:::caution
+
+The example above produces the equivalent results but it also illustrates that
+the types and global variables available to the evaluated function cannot be
+known. Especially, in TypeScript you should be careful to make sure that objects
+referenced by the evaluated function are correct.
+
+:::
+
+## Return types
+
+The functions you evaluate can return values. If the returned value is of a
+primitive type, it gets automatically converted by Puppeteer to a primitive type
+in the script context like in the previous example.
+
+If the script returns an object, Puppeteer serializes it to a JSON and reconstructs it on the script side. This process might not always yield correct results, for example, when you return a DOM node:
+
+```ts
+const body = await page.evaluate(() => {
+  return document.body;
+});
+console.log(body); // {}, unexpected!
+```
+
+To work with the returned objects, Puppeteer offers a way to return objects by reference:
+
+```ts
+const body = await page.evaluateHandle(() => {
+  return document.body;
+});
+console.log(body instanceof ElementHandle); // true
+```
+
+The returned object is either a `JSHandle` or a `ElementHandle`. `ElementHandle` extends `JSONHandle` and it is only created for DOM elements.
+
+See the [API documentation](https://pptr.dev/api) for more details about what methods are available for handles.
+
+## Passing arguments to the evaluate function
+
+You can provide arguments to your function:
+
+```ts
+const three = await page.evaluate(
+  (a, b) => {
+    return 1 + 2;
+  },
+  1,
+  2
+);
+```
+
+The arguments can primitive values or `JSHandle`s.
+
+:::note
+
+Page, JSHandle and ElementHandle offer several different helpers to evaluate JavaScript but they all follow the basic principles outlined in this guide.
+
+:::

docs/guides/request-interception.md

@@ -6,7 +6,7 @@ continued, responded or aborted.
 An example of a naïve request interceptor that aborts all image requests:
 
 ```js
-const puppeteer = require('puppeteer');
+import puppeteer from 'puppeteer';
 
 (async () => {
   const browser = await puppeteer.launch();

docs/troubleshooting.md

@@ -1,5 +1,12 @@
 # Troubleshooting
 
+:::caution
+
+Chromium currently does not provide arm64 binaries for Linux. There are only binaries
+for [Mac ARM with experimental support from Puppeteer](https://pptr.dev/contributing#macos-arm-and-custom-executables).
+
+:::
+
 ## `Cannot find module 'puppeteer-core/internal/...'`
 
 This can occur is your Node.js version is lower than 14 or you are using a
@@ -75,7 +82,6 @@ missing. The common ones are provided below.
 ```
 ca-certificates
 fonts-liberation
-libappindicator3-1
 libasound2
 libatk-bridge2.0-0
 libatk1.0-0
@@ -275,6 +281,19 @@ script:
   - npm test
 ```
 
+## Running Puppeteer on WSL (Windows subsystem for Linux)
+
+See [this thread](https://github.com/puppeteer/puppeteer/issues/1837) with some tips specific to WSL. In a nutshell, you need to install missing dependencies by either:
+
+1. [Installing Chrome on WSL to install all dependencies](https://learn.microsoft.com/en-us/windows/wsl/tutorials/gui-apps#install-google-chrome-for-linux)
+2. Installing required dependencies manually: `sudo apt install libgtk-3-dev libnotify-dev libgconf-2-4 libnss3 libxss1 libasound2`.
+
+:::caution
+
+The list of required dependencies might get outdated and depend on what you already have installed.
+
+:::
+
 ## Running Puppeteer on CircleCI
 
 Running Puppeteer smoothly on CircleCI requires the following steps: