chore: improve docs (#9105)

This PR makes some improvements to the documentation. It migrates
docker, debugging, and chrome extension documentation to the `guides`
folder and also updates some of the terminology.

.prettierignore

@@ -44,5 +44,5 @@ assets/
 CHANGELOG.md
 package-lock.json
 test/assets/
-docs/
+docs/api
 versioned_*/

docs/guides/chrome-extensions.md

@@ -0,0 +1,44 @@
+# Chrome Extensions
+
+Puppeteer can be used for testing Chrome Extensions.
+
+:::caution
+
+Extensions in Chrome/Chromium currently only work in non-headless mode and experimental Chrome headless mode.
+
+:::
+
+The following is code for getting a handle to the [background page](https://developer.chrome.com/extensions/background_pages) of an extension whose source is located in `./my-extension`:
+
+```ts
+const puppeteer = require('puppeteer');
+
+(async () => {
+  const pathToExtension = require('path').join(__dirname, 'my-extension');
+  const browser = await puppeteer.launch({
+    headless: 'chrome',
+    args: [
+      `--disable-extensions-except=${pathToExtension}`,
+      `--load-extension=${pathToExtension}`,
+    ],
+  });
+  const backgroundPageTarget = await browser.waitForTarget(
+    target => target.type() === 'background_page'
+  );
+  const backgroundPage = await backgroundPageTarget.page();
+  // Test the background page as you would any other page.
+  await browser.close();
+})();
+```
+
+:::note
+
+Chrome Manifest V3 extensions have a background ServiceWorker of type 'service_worker', instead of a page of type 'background_page'.
+
+:::
+
+:::note
+
+It is not yet possible to test extension popups or content scripts.
+
+:::

docs/guides/debugging.md

@@ -0,0 +1,122 @@
+# Debugging
+
+Debugging with Puppeteer can be an arduous task. There is no _single_ method for debugging all possible issues since Puppeteer touches many distinct components of a browser such as network requests and Web APIs. On a high note, Puppeteer provides _several_ methods for debugging which hopefully does cover all possible issues.
+
+## Background
+
+In general, there are two possible sources of an issue: Code running on Node.js (which we call _server code_), and [code running in the browser](<[`Page.evaluate()`](https://pptr.dev/api/puppeteer.page.evaluate)>) (which we call _client code_). There is also a third possible source being the browser itself (which we call _internal code_), but if you suspect this is the source **after attempting the methods below**, we suggest [searching existing issues](https://github.com/puppeteer/puppeteer/issues) before [filing an issue](https://github.com/puppeteer/puppeteer/issues/new/choose).
+
+## Debugging methods for all situations
+
+These methods can be used to debug any situation. These should be used as a quick sanity check before diving into more complex methods.
+
+### Turn off [`headless`](https://pptr.dev/api/puppeteer.browserlaunchargumentoptions.headless)
+
+Sometimes it's useful to see what the browser is displaying. Instead of launching in [`headless`](https://pptr.dev/api/puppeteer.browserlaunchargumentoptions.headless) mode, launch a full version of the browser with [`headless`](https://pptr.dev/api/puppeteer.browserlaunchargumentoptions.headless) set to `false`:
+
+```ts
+const browser = await puppeteer.launch({headless: false});
+```
+
+### Puppeteer "slow-mo"
+
+The [`slowMo`](https://pptr.dev/api/puppeteer.browserconnectoptions.slowmo) option slows down Puppeteer operations by a specified amount of milliseconds. It's another way to help see what's going on.
+
+```ts
+const browser = await puppeteer.launch({
+  headless: false,
+  slowMo: 250, // slow down by 250ms
+});
+```
+
+## Debugging methods for client code
+
+### Capture `console.*` output
+
+Since client code runs in the browser, doing `console.*` in client code will not directly log to Node.js. However, you can [listen](https://pptr.dev/api/puppeteer.page.on) for the [`console`](https://pptr.dev/api/puppeteer.pageeventobject.console) event which returns a payload with the logged text.
+
+```ts
+page.on('console', msg => console.log('PAGE LOG:', msg.text()));
+
+await page.evaluate(() => console.log(`url is ${location.href}`));
+```
+
+### Use the debugger in the browser
+
+1. Set [`devtools`](https://pptr.dev/api/puppeteer.browserlaunchargumentoptions.devtools) to `true` when launching Puppeteer:
+
+   ```ts
+   const browser = await puppeteer.launch({devtools: true});
+   ```
+
+2. Add `debugger` inside any client code you want debugged. For example,
+
+   ```ts
+   await page.evaluate(() => {
+     debugger;
+   });
+   ```
+
+   The Browser will now stop in the location the `debugger` word is found in debug mode.
+
+## Debugging methods for server code
+
+### Use the debugger in Node.js (Chrome/Chromium-only)
+
+Since server code intermingles with client code, this method of debugging is closely tied with the browser. For example, you can step over `await page.click()` in the server script and see the click happen in the browser.
+
+Note that you won't be able to run `await page.click()` in DevTools console due to this [Chromium bug](https://bugs.chromium.org/p/chromium/issues/detail?id=833928), so if
+you want to try something out, you have to add it to your test file.
+
+1. Set [`headless`](https://pptr.dev/api/puppeteer.browserlaunchargumentoptions.headless) to `false`.
+2. Add `debugger` to any server code you want debugged. For example,
+
+   ```ts
+   debugger;
+   await page.click('a[target=_blank]');
+   ```
+
+3. Run your server code with `--inspect-brk`. For example,
+
+   ```sh
+   node --inspect-brk path/to/script.js
+   ```
+
+4. In the opened Chrome/Chromium browser, open `chrome://inspect/#devices` and click `inspect`.
+5. In the newly opened test browser, press `F8` to resume test execution.
+6. Now your `debugger` statement will be hit and you can debug in the test browser.
+
+### Use [ndb](https://github.com/GoogleChromeLabs/ndb)
+
+1. Install `ndb`:
+
+   ```sh
+   npm install -g ndb
+   ```
+
+2. Add `debugger` to any server code you want debugged. For example,
+
+   ```ts
+   debugger;
+   await page.click('a[target=_blank]');
+   ```
+
+3. Add `ndb` before your test command. For example,
+
+   ```sh
+   ndb node path/to/script.js
+   ```
+
+4. Debug your test inside chromium like a boss!
+
+### Log DevTools protocol traffic
+
+If all else fails, it's possible there may be an issue between Puppeteer and the DevTools protocol. You can debug this by setting the `DEBUG` environment variable before running your script. This will log internal traffic via [`debug`](https://github.com/visionmedia/debug) under the `puppeteer` namespace.
+
+```sh
+# Basic verbose logging
+env DEBUG="puppeteer:*" node script.js
+
+# Protocol traffic can be rather noisy. This example filters out all Network domain messages
+env DEBUG="puppeteer:*" env DEBUG_COLORS=true node script.js 2>&1 | grep -v '"Network'
+```

docs/guides/docker.md

@@ -0,0 +1,22 @@
+# Docker
+
+Puppeteer offers a Docker image that includes Chromium along with the required dependencies and a pre-installed Puppeteer version. The image is available via the [GitHub Container Registry](https://github.com/puppeteer/puppeteer/pkgs/container/puppeteer). The latest image is tagged as `latest` and other tags match Puppeteer versions. For example,
+
+```sh
+docker pull ghcr.io/puppeteer/puppeteer:latest # pulls the latest
+docker pull ghcr.io/puppeteer/puppeteer:16.1.0 # pulls the image that contains Puppeteer v16.1.0
+```
+
+The image is meant for running the browser in sandbox mode and therefore, running the image requires the `SYS_ADMIN` capability.
+
+## Usage
+
+To use the docker image directly, run:
+
+```sh
+docker run -i --init --cap-add=SYS_ADMIN --rm ghcr.io/puppeteer/puppeteer:latest node -e "$(cat path/to/script.js)"
+```
+
+where `path/to/script.js` is the path relative to your working directory. Note the image requires the `SYS_ADMIN` capability since the browser runs in sandbox mode.
+
+If you need to build an image based on a different base image, you can use our [`Dockerfile`](https://github.com/puppeteer/puppeteer/blob/main/docker/Dockerfile) as the starting point.