docs(readme): update readme and intro docs (#1963)

microsoft · Apr 24, 2020 · 28f98ac · 28f98ac
1 parent 4b263d6
commit 28f98ac
Show file tree

Hide file tree

Showing 3 changed files with 51 additions and 53 deletions.
diff --git a/README.md b/README.md
@@ -1,35 +1,43 @@
-# 🎭 Playwright
-[![npm version](https://img.shields.io/npm/v/playwright.svg?style=flat)](https://www.npmjs.com/package/playwright) <!-- GEN:chromium-version-badge -->[![Chromium version](https://img.shields.io/badge/chromium-84.0.4125.0-blue.svg?logo=google-chrome)](https://www.chromium.org/Home)<!-- GEN:stop --> <!-- GEN:firefox-version-badge -->[![Firefox version](https://img.shields.io/badge/firefox-76.0b5-blue.svg?logo=mozilla-firefox)](https://www.mozilla.org/en-US/firefox/new/)<!-- GEN:stop --> [![WebKit version](https://img.shields.io/badge/webkit-13.0.4-blue.svg?logo=safari)](https://webkit.org/) [![Join Slack](https://img.shields.io/badge/join-slack-infomational)](https://join.slack.com/t/playwright/shared_invite/enQtOTEyMTUxMzgxMjIwLThjMDUxZmIyNTRiMTJjNjIyMzdmZDA3MTQxZWUwZTFjZjQwNGYxZGM5MzRmNzZlMWI5ZWUyOTkzMjE5Njg1NDg)
+# 🎭 Playwright 
 
-###### [Docs](https://github.com/microsoft/playwright/blob/master/docs/README.md) | [API](https://github.com/microsoft/playwright/blob/master/docs/api.md) | [Changelog](https://github.com/microsoft/playwright/releases) | [Contributing](#contributing)
+[![npm version](https://img.shields.io/npm/v/playwright.svg?style=flat)](https://www.npmjs.com/package/playwright) [![Join Slack](https://img.shields.io/badge/join-slack-infomational)](https://join.slack.com/t/playwright/shared_invite/enQtOTEyMTUxMzgxMjIwLThjMDUxZmIyNTRiMTJjNjIyMzdmZDA3MTQxZWUwZTFjZjQwNGYxZGM5MzRmNzZlMWI5ZWUyOTkzMjE5Njg1NDg) <!-- GEN:chromium-version-badge -->[![Chromium version](https://img.shields.io/badge/chromium-84.0.4125.0-blue.svg?logo=google-chrome)](https://www.chromium.org/Home)<!-- GEN:stop --> <!-- GEN:firefox-version-badge -->[![Firefox version](https://img.shields.io/badge/firefox-76.0b5-blue.svg?logo=mozilla-firefox)](https://www.mozilla.org/en-US/firefox/new/)<!-- GEN:stop --> [![WebKit version](https://img.shields.io/badge/webkit-13.0.4-blue.svg?logo=safari)](https://webkit.org/)
 
+##### [Docs](docs/README.md) | [API reference](docs/api.md) | [Changelog](https://github.com/microsoft/playwright/releases)
 
-Playwright is a Node library to automate the [Chromium](https://www.chromium.org/Home), [WebKit](https://webkit.org/) and [Firefox](https://www.mozilla.org/en-US/firefox/new/) browsers with a single API. It enables **cross-browser** web automation that is **ever-green**, **capable**, **reliable** and **fast**.
+Playwright is a Node library to automate [Chromium](https://www.chromium.org/Home), [Firefox](https://www.mozilla.org/en-US/firefox/new/) and [WebKit](https://webkit.org/) with a single API. Playwright is built to enable cross-browser web automation that is **ever-green**, **capable**, **reliable** and **fast**.
 
-|          | Linux | macOS | Win |
-|   ---:   | :---: | :---:  | :---: |
+|          | Linux | macOS | Windows |
+|   :---   | :---: | :---: | :---:   |
 | Chromium <!-- GEN:chromium-version -->84.0.4125.0<!-- GEN:stop --> | :white_check_mark: | :white_check_mark: | :white_check_mark: |
 | WebKit 13.0.4 | :white_check_mark: | :white_check_mark: | :white_check_mark: |
 | Firefox <!-- GEN:firefox-version -->76.0b5<!-- GEN:stop --> | :white_check_mark: | :white_check_mark: | :white_check_mark: |
-- Headless is supported for all the browsers on all platforms.
 
+Headless execution is supported for all the browsers on all platforms.
 
-Our primary goal with Playwright is to improve automated UI testing by eliminating flakiness, improving the speed of execution and offering insights into the browser operation.
-
-### Usage
+## Usage
 
 ```
 npm i playwright
 ```
 
-This installs Playwright along with its dependencies and the browser binaries. Browser binaries are about 50-100MB each, so expect the installation network traffic to be substantial.
-
-Once installed, Playwright can be used to create a browser instance, open pages and then automate interactions.
+This installs Playwright and browser binaries for Chromium, Firefox and WebKit. Once installed, you can `require` Playwright in a Node.js script and automate web browser interactions.
 
-* [Documentation](docs/README.md)
+* [Getting started](docs/intro.md)
+* [Installation configuration](docs/installation.md).
 * [API reference](docs/api.md)
 
-### Examples
+## Capabilities
+
+Playwright is built to automate the broad and growing set of web browser capabilities used by Single Page Apps and Progressive Web Apps.
+
+* Scenarios that span multiple page, domains and iframes
+* Auto-wait for elements to be ready before executing actions (like click, fill)
+* Intercept network activity for stubbing and mocking network requests
+* Emulate mobile devices, geolocation, permissions
+* Native input events for mouse and keyboard
+* Upload and download files
+
+## Examples
 
 #### Page screenshot
 
@@ -122,13 +130,10 @@ const { webkit } = require('playwright');
 })();
 ```
 
-## Contributing
-
-Check out our [contributing guide](https://github.com/microsoft/playwright/blob/master/CONTRIBUTING.md).
-
 ## Resources
 
 * [Documentation](docs/README.md)
-* [Example recipes](docs/examples/README.md)
 * [API reference](docs/api.md)
+* [Example recipes](docs/examples/README.md)
+* [Contributing](CONTRIBUTING.md)
 * [Community showcase](docs/showcase.md)
diff --git a/docs/README.md b/docs/README.md
@@ -1,7 +1,10 @@
+# Documentation
+
 ### Table of contents
 
-1. [Introduction](./intro.md)
-1. [Core concepts](./core-concepts.md)
+1. [Getting Started](./intro.md)
+    - [Installation](./installation.md)
+1. [Core Concepts](./core-concepts.md)
     - [Browser](./core-concepts.md#browser)
     - [Browser contexts](./core-concepts.md#browser-contexts)
     - [Pages and frames](./core-concepts.md#pages-and-frames)
@@ -32,31 +35,31 @@
     - [Handle requests](./network.md#handle-requests)
     - [Modify requests](./network.md#modify-requests)
     - [Abort requests](./network.md#abort-requests)
-1. [Scraping and verification](./verification.md)
+1. [Scraping and Verification](./verification.md)
     - [Evaluating JavaScript](./verification.md#evaluating-javascript)
     - [Capturing screenshot](./verification.md#capturing-screenshot)
     - [Page events](./verification.md#page-events)
     - [Handling exceptions](./verification.md#handling-exceptions)
-1. [Navigation and loading](./loading.md)
+1. [Navigation and Loading](./loading.md)
     - [Common scenarios](./loading.md#common-scenarios)
     - [Loading a popup](./loading.md#loading-a-popup)
     - [Client-side redirects](./loading.md#unusual-client-side-redirects)
     - [Navigation after a timeout](./loading.md#click-triggers-navigation-after-a-timeout)
-1. [Continuous integration](./ci.md)
+1. [Continuous Integration](./ci.md)
     - [Docker](./ci.md#docker)
     - [GitHub Actions](./ci.md#github-actions)
     - [Azure Pipelines](./ci.md#azure-pipelines)
     - [Travis CI](./ci.md#travis-ci)
     - [CircleCI](./ci.md#circleci)
     - [AppVeyor](./ci.md#appveyor)
-    - Troubleshooting
+    - [Troubleshooting](./troubleshooting.md)
 1. Test runners
     - Jest
     - Mocha
     - Karma
     - Jasmine
     - Storybooks
+1. [Selector engines](./selectors.md)
 1. [Extensibility](./extensibility.md)
     - [Custom selector engines](./extensibility.md#custom-selector-engines)
-1. [Installation](./installation.md)
-1. [API Reference](./api.md)
+1. [API Reference](./api.md)
diff --git a/docs/intro.md b/docs/intro.md
@@ -1,36 +1,24 @@
-# Introduction
+# Getting Started
 
-## What is Playwright?
+<!-- GEN:toc -->
+- [Installation](#installation)
+- [Usage](#usage)
+- [Writing your first script](#writing-your-first-script)
+- [Debugging scripts](#debugging-scripts)
+- [Deploying to CI](#deploying-to-ci)
+<!-- GEN:stop -->
 
-Playwright is a cross-browser automation driver for end-to-end testing. Playwright provides an API to launch web browsers, navigate to web pages and manipulate page contents in JavaScript.
-
-The Playwright API is cross-browser: it works across **Chromium** (used in Chrome, Edge, and many other browsers), **Firefox** and **WebKit** (used in Safari) engines.
-
-Playwright is free and open source. Playwright is also modular, and works with any JavaScript test runner framework.
-
-### Capabilities
-
-Playwright can run automation scenarios that span multiple tabs, domains and iframes. More specifically, Playwright can:
-
-* Auto-wait for elements to be ready before executing actions (like click, fill)
-* Intercept network activity for stubbing and mocking network requests
-* Emulate mobile devices, geolocation, permissions
-* Native input events for mouse and keyboard
-* Upload and download files
-
-## Getting started
-
-### Installation
+## Installation
 
 Use npm or Yarn to install Playwright in your Node.js project. Playwright requires Node.js 10 or higher.
 
 ```
 npm i playwright
 ```
 
-During installation, Playwright downloads browser binaries for Chromium, Firefox and WebKit. This sets up your environment for browser automation with just one command. It is possible to modify this default behavior for monorepos and other scenarios through [environment variables](api.md#environment-variables).
+During installation, Playwright downloads browser binaries for Chromium, Firefox and WebKit. This sets up your environment for browser automation with just one command. It is possible to modify this default behavior for monorepos and other scenarios. See [installation](installation.md).
 
-### Usage
+## Usage
 
 Once installed, you can `require` Playwright in a Node.js script, and launch any of the 3 browsers (`chromium`, `firefox` and `webkit`).
 
@@ -53,7 +41,7 @@ Playwright APIs are asynchronous and return Promise objects. Our code examples u
 })(); // End of the function and () to invoke itself
 ```
 
-### Writing your first script
+## Writing your first script
 
 In our first script, we will navigate to `whatsmyuseragent.org` and take a screenshot in WebKit.
 
@@ -75,10 +63,12 @@ By default, Playwright runs the browsers in headless mode. To see the browser UI
 firefox.launch({ headless: false, slowMo: 50 });
 ```
 
-### Debugging scripts
+## Debugging scripts
 
 <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="300" alt="Chromium Developer Tools" align="right"></a>
 
 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.
 
 It is also possible to open **browser developer tools** during execution, to inspect the DOM tree or network activity.
+
+## Deploying to CI