From 6df17c69e22e2ac58d9548cbb16dddc34779db63 Mon Sep 17 00:00:00 2001
From: Arjun Attam <arjunattam@gmail.com>
Date: Sat, 21 Mar 2020 12:05:37 -0700
Subject: [PATCH] docs(examples): setup get started with examples guide (#1441)

---
 README.md                       |  1 +
 docs/examples/README.md         | 64 +++++++++++++++++++++++++++++++++
 docs/examples/authentication.js | 54 ++++++++++++++++++++++++++++
 3 files changed, 119 insertions(+)
 create mode 100644 docs/examples/README.md
 create mode 100644 docs/examples/authentication.js

diff --git a/README.md b/README.md
index 3cda23e711..93cf7c8fa7 100644
--- a/README.md
+++ b/README.md
@@ -180,6 +180,7 @@ Playwright is being actively developed as we get to the feature parity across Ch
 
 ## Resources
 
+* [Get started with examples](examples/README.md)
 * [API documentation](docs/api.md)
 * [Getting started on CI](docs/ci.md)
 * [Community showcase](docs/showcase.md)
diff --git a/docs/examples/README.md b/docs/examples/README.md
new file mode 100644
index 0000000000..f7819e7cd1
--- /dev/null
+++ b/docs/examples/README.md
@@ -0,0 +1,64 @@
+# Get started with examples
+
+Learn how to install Playwright, set up your dev environment to author Playwright scripts, and example recipes to bootstrap your scripts.
+
+## Installing Playwright
+
+Playwright is a Node.js library and can be acquired through the npm registry. Use npm or yarn to install Playwright in your Node.js project.
+
+```
+npm i playwright
+```
+
+Once installed, you can `require` Playwright in your Node.js scripts, and launch any of the 3 browsers (`chromium`, `firefox` and `webkit`).
+
+```js
+const { chromium } = require('playwright');
+
+(async () => {
+  const browser = await chromium.launch();
+  await browser.close();
+})();
+```
+
+## Setup dev environment
+
+Playwright scripts can be developed just like any other Node.js script. For example, you can use the [Node.js debugger](https://nodejs.org/api/debugger.html) or [VS Code debugging](https://code.visualstudio.com/docs/nodejs/nodejs-debugging) to set breakpoints and get fine grained control over execution.
+
+### Running browsers for debugging
+
+By default, Playwright runs the browsers in headless mode. To see the browser UI, pass the `headless: false` flag while launching the browser. You can also use `slowMo` to slow down execution.
+
+```js
+  chromium.launch({ headless: false, slowMo: 50 });
+```
+
+It is also possible to open **browser developer tools** during execution, to inspect the DOM tree or network activity. This is possible in Chromium, Firefox and WebKit.
+
+<p align="center"><a href="https://user-images.githubusercontent.com/284612/77234134-5f21a500-6b69-11ea-92ec-1c146e1333ec.png"><img src="https://user-images.githubusercontent.com/284612/77234134-5f21a500-6b69-11ea-92ec-1c146e1333ec.png" width="500" alt="Chromium Developer Tools"></a></p>
+
+## Example recipes
+
+### [Authentication](authentication.js)
+
+This script logs in on GitHub.com through Chromium, and then reuses the login cookies state in WebKit. This recipe can be used to speed up tests by logging in once and reusing login state.
+
+<!--
+## Core concepts
+
+* Browser
+* Browser contexts
+* Pages and frames
+* Evaluate in page context
+-->
+
+<!--
+Other examples
+* Page navigation and wait for load
+* Request interception
+* Geolocation and mobile emulation
+
+* Uploading a file
+* Handling a popup, eg, accept dialog
+* Async page load (see #662)
+-->
\ No newline at end of file
diff --git a/docs/examples/authentication.js b/docs/examples/authentication.js
new file mode 100644
index 0000000000..c3bac5400d
--- /dev/null
+++ b/docs/examples/authentication.js
@@ -0,0 +1,54 @@
+const { chromium, webkit } = require('playwright');
+const assert = require('assert');
+
+/**
+ * In this script, we will login on GitHub.com through Chromium,
+ * and reuse the login cookies state inside WebKit. This recipe can be
+ * used to speed up tests by logging in once and reusing login state.
+ * 
+ * Steps summary
+ * 1. Login on GitHub.com in Chromium
+ * 2. Export cookies from Chromium browser context
+ * 3. Set cookies in WebKit browser context and verify login
+ */
+
+const account = { login: '', password: '' };
+
+(async () => {
+  // Create a Chromium browser context
+  const crBrowser = await chromium.launch();
+  const crContext = await crBrowser.newContext();
+  const crPage = await crContext.newPage();
+
+  // Navigate and auto-wait on the page to load after navigation
+  await crPage.goto('https://github.com/login');
+
+  // Fill login form elements
+  await crPage.fill('input[name="login"]', account.login);
+  await crPage.fill('input[name="password"]', account.password);
+
+  // Submit form and auto-wait for the navigation to complete
+  await crPage.click('input[type="submit"]');
+  await verifyIsLoggedIn(crPage);
+
+  // Get cookies from Chromium browser context
+  const cookies = await crContext.cookies();
+  await crBrowser.close();
+  
+  // Create WebKit browser context and load cookies
+  const wkBrowser = await webkit.launch();
+  const wkContext = await wkBrowser.newContext();
+  await wkContext.addCookies(cookies)
+
+  // Navigate to GitHub.com and verify that we are logged in
+  const wkPage = await wkContext.newPage();
+  await wkPage.goto('http://github.com');
+  await wkPage.screenshot({ path: 'webkit.png' });
+  await verifyIsLoggedIn(wkPage);
+  await wkBrowser.close();
+})();
+
+const verifyIsLoggedIn = async (page) => {
+  // Find element through text value and assert it exists.
+  assert(await page.$('text="Create repository"'));
+}