From 0a3dd4e72708b34a9a4c799f4e9c1400849a1e91 Mon Sep 17 00:00:00 2001
From: Eric Bidelman <ebidel@gmail.com>
Date: Mon, 14 Aug 2017 17:55:40 -0700
Subject: [PATCH] readme: faq entries (#254)

* readme: faq entries

* Feedback
---
 README.md | 51 +++++++++++++++++++++++++++++++++++++++++++++------
 1 file changed, 45 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 8933940f87a..b0196973381 100644
--- a/README.md
+++ b/README.md
@@ -87,7 +87,7 @@ See [`Page.pdf()`](https://github.com/GoogleChrome/puppeteer/blob/master/docs/ap
 
 ## Default runtime settings
 
-**Uses Headless mode**
+**1. Uses Headless mode**
 
 Puppeteer launches Chromium in [headless mode](https://developers.google.com/web/updates/2017/04/headless-chrome). To launch a full version of Chromium, set the ['headless' option](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#new-browseroptions) when creating a browser:
 
@@ -95,11 +95,19 @@ Puppeteer launches Chromium in [headless mode](https://developers.google.com/web
 const browser = new Browser({headless: false});
 ```
 
-**Runs a bundled version of Chromium**
+**2. Runs a bundled version of Chromium**
 
-By default, Puppeteer downloads and uses a specific version of Chromium but it can be configured to [use another install of Chrome](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#new-browseroptions)
+By default, Puppeteer downloads and uses a specific version of Chromium so its API
+is guaranteed to work out of the box. To use Puppeteer with a different version of Chrome,
+pass in the executable's path when creating a `Browser` instance:
 
-**Creates a fresh user profile**
+```js
+const browser = new Browser({executablePath: '/path/to/Chrome'});
+```
+
+See [`Browser`](https://github.com/GoogleChrome/puppeteer/blob/master/docs/api.md#new-browseroptions) for more information.
+
+**3. Creates a fresh user profile**
 
 Puppeteer creates its own Chromium user profile which it **cleans up on every run**.
 
@@ -131,8 +139,39 @@ Yes. Puppeteer runs Chromium in [headless mode](https://developers.google.com/we
 
 Since Puppeteer's code is run by Node, it exists out-of-process to the controlled Chromium instance. This requires most of the API calls to be asynchronous to allow the necessary roundtrips to the browser.
 
-#### Q: What is the difference between Puppeteer and Selenium / WebDriver?
+#### Q: What is the difference between Puppeteer, Selenium / WebDriver, and PhantomJS?
 
 Selenium / WebDriver is a well-established cross-browser API that is useful for testing cross-browser support.
 
-Puppeteer is useful for single-browser testing. For example, many teams only run unit tests with a single browser (e.g. Phantom). In non-testing use cases, Puppeteer provides a powerful but simple API because it's only targeting one browser that enables you to rapidly develop automation scripts.
+Puppeteer works only with Chrome. However, many teams only run unit tests with a single browser (e.g. Phantom). In non-testing use cases, Puppeteer provides a powerful but simple API because it's only targeting one browser that enables you to rapidly develop automation scripts.
+
+PhantomJS uses an older version of WebKit as it's browser rendering engine. Puppeteer uses the latest
+versions of Chromium, which use the Blink rendering engine.
+
+#### Q: How is this different than Chromeless?
+
+[Chromeless](https://github.com/graphcool/chromeless) and Puppeteer are similar projects.
+Both are Node libraries that provide a high-level JS APIs to control headless Chrome.
+
+Chromeless is intended to work well with AWS Lambda to deploy parallel testing in a serverless setup.
+Under the hood, it uses [chrome-remote-interface](https://www.npmjs.com/package/chrome-remote-interface) to interface with the DevTools Protocol. In the future, it could use Puppeteer's API.
+
+Puppeteer is smaller in size (ignoring the bundled version of Chrome) and does not use
+dependencies to interface with Chrome. It's API is inspired by other popular automated testing
+libraries like PhantomJS and [NightmareJS](http://www.nightmarejs.org/).
+
+#### Q: Who maintains Puppeteer?
+
+The Chrome DevTools team maintains the library, but we'd love your help and expertise on the project!
+See [Contributing](https://github.com/GoogleChrome/puppeteer/blob/master/CONTRIBUTING.md).
+
+#### Q: Why is the Chrome team building Puppeteer?
+
+The goals are the project are simple:
+
+- Provide a slim (1.7 Mb), canonical library that highlights the capabilities of the [DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/).
+- Provide a reference implementation for similar testing libraries. Eventually, these
+other frameworks could adopt Puppeteer as their foundational layer.
+- Grow the adoption of headless/automated browser testing.
+- Help dogfood new DevTools Protocol features...and catch bugs!
+- Learn more about the pain points of automated browser testing and help fill those gaps.