docs(api.md): expand on testing Chrome Extensions (#2893)

Fixes #2823

README.md

@@ -20,6 +20,7 @@ Most things that you can do manually in the browser can be done using Puppeteer!
 * Automate form submission, UI testing, keyboard input, etc.
 * Create an up-to-date, automated testing environment. Run your tests directly in the latest version of Chrome using the latest JavaScript and browser features.
 * Capture a [timeline trace](https://developers.google.com/web/tools/chrome-devtools/evaluate-performance/reference) of your site to help diagnose performance issues.
+* Test Chrome Extensions.
 <!-- [END usecases] -->
 
 Give it a spin: https://try-puppeteer.appspot.com/
@@ -199,13 +200,13 @@ Explore the [API documentation](docs/api.md) and [examples](https://github.com/G
       `const browser = await puppeteer.launch({devtools: true});`
 
   - Change default test timeout:
-      
+
       jest: `jest.setTimeout(100000);`
-      
+
       jasmine: `jasmine.DEFAULT_TIMEOUT_INTERVAL = 100000;`
-      
+
       mocha: `this.timeout(100000);` (don't forget to change test to use [function and not '=>'](https://stackoverflow.com/a/23492442))
-    
+
   - Add an evaluate statement with `debugger` inside / add  `debugger` to an existing evaluate statement:
 
     `await page.evaluate(() => {debugger;});`
@@ -276,7 +277,7 @@ We see Puppeteer as an **indivisible entity** with Chromium. Each version of Pup
 
 This is not an artificial constraint: A lot of work on Puppeteer is actually taking place in the Chromium repository. Here’s a typical story:
 - A Puppeteer bug is reported: https://github.com/GoogleChrome/puppeteer/issues/2709
-- It turned out this is an issue with the DevTools protocol, so we’re fixing it in Chromium: https://chromium-review.googlesource.com/c/chromium/src/+/1102154 
+- It turned out this is an issue with the DevTools protocol, so we’re fixing it in Chromium: https://chromium-review.googlesource.com/c/chromium/src/+/1102154
 - Once the upstream fix is landed, we roll updated Chromium into Puppeteer: https://github.com/GoogleChrome/puppeteer/pull/2769
 
 However, oftentimes it is desirable to use Puppeteer with the official Google Chrome rather than Chromium. For this to work, you should pick the version of Puppeteer that uses the Chromium version close enough to Chrome.

docs/api.md

@@ -12,6 +12,7 @@ Next Release: **Aug 9, 2018**
 <!-- GEN:toc -->
 - [Overview](#overview)
 - [Environment Variables](#environment-variables)
+- [Working with Chrome Extensions](#working-with-chrome-extensions)
 - [class: Puppeteer](#class-puppeteer)
   * [puppeteer.connect(options)](#puppeteerconnectoptions)
   * [puppeteer.createBrowserFetcher([options])](#puppeteercreatebrowserfetcheroptions)
@@ -309,6 +310,35 @@ If puppeteer doesn't find them in environment, lowercased variant of these varia
 - `PUPPETEER_DOWNLOAD_HOST` - overwrite host part of URL that is used to download Chromium
 - `PUPPETEER_CHROMIUM_REVISION` - specify a certain version of chrome you'd like puppeteer to use during the installation step.
 
+### Working with Chrome Extensions
+
+Puppeteer can be used for testing Chrome Extensions.
+
+> **NOTE** Extensions in Chrome / Chromium currently only work in non-headless mode.
+
+The following is the code for getting a handle to a [background page](https://developer.chrome.com/extensions/background_pages) of an extension whose source is located in `./my-extension`:
+```js
+const puppeteer = require('puppeteer');
+
+(async () => {
+  const pathToExtension = require('path').join(__dirname, 'my-extension');
+  const browser = puppeteer.launch({
+    headless: false,
+    args: [
+      `--disable-extensions-except=${pathToExtension}`,
+      `--load-extension=${pathToExtension}`
+    ]
+  });
+  const targets = await browser.targets();
+  const backgroundPageTarget = targets.find(target => target.type() === 'background_page');
+  const backgroundPage = await backgroundPageTarget.page();
+  // Test the background page as you would any other page.
+  await browser.close();
+})();
+```
+
+> **NOTE** It is not yet possible to test extension popups or content scripts.
+
 ### class: Puppeteer
 
 Puppeteer module provides a method to launch a Chromium instance.
@@ -631,7 +661,7 @@ An array of all active targets inside the browser context.
 
 * extends: [`EventEmitter`](https://nodejs.org/api/events.html#events_class_eventemitter)
 
-Page provides methods to interact with a single tab in Chromium. One [Browser] instance might have multiple [Page] instances.
+Page provides methods to interact with a single tab or [extension background page](https://developer.chrome.com/extensions/background_pages) in Chromium. One [Browser] instance might have multiple [Page] instances.
 
 This example creates a page, navigates it to a URL, and then saves a screenshot:
 ```js

examples/README.md

@@ -10,23 +10,6 @@ NODE_PATH=../ node examples/search.js
 
 More complex and use case driven examples can be found at [github.com/GoogleChromeLabs/puppeteer-examples](https://github.com/GoogleChromeLabs/puppeteer-examples).
 
-# Tips & Tricks
-
-## Load a Chrome extension
-
-By default, Puppeteer disables extensions when launching Chrome. You can load a specific
-extension using:
-
-```js
-const browser = await puppeteer.launch({
-  headless: false,
-  args: [
-    '--disable-extensions-except=/path/to/extension/',
-    '--load-extension=/path/to/extension/',
-  ]
-});
-```
-
 # Other resources
 
 > Other useful tools, articles, and projects that use Puppeteer.