From 28f98ac278e805194bceac80b8a9251281763cca Mon Sep 17 00:00:00 2001 From: Arjun Attam Date: Fri, 24 Apr 2020 12:19:31 -0700 Subject: [PATCH] docs(readme): update readme and intro docs (#1963) --- README.md | 45 +++++++++++++++++++++++++-------------------- docs/README.md | 19 +++++++++++-------- docs/intro.md | 40 +++++++++++++++------------------------- 3 files changed, 51 insertions(+), 53 deletions(-) diff --git a/README.md b/README.md index 64d88cd10525b..fa7f534ea5ecf 100644 --- 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) [![Chromium version](https://img.shields.io/badge/chromium-84.0.4125.0-blue.svg?logo=google-chrome)](https://www.chromium.org/Home) [![Firefox version](https://img.shields.io/badge/firefox-76.0b5-blue.svg?logo=mozilla-firefox)](https://www.mozilla.org/en-US/firefox/new/) [![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) [![Chromium version](https://img.shields.io/badge/chromium-84.0.4125.0-blue.svg?logo=google-chrome)](https://www.chromium.org/Home) [![Firefox version](https://img.shields.io/badge/firefox-76.0b5-blue.svg?logo=mozilla-firefox)](https://www.mozilla.org/en-US/firefox/new/) [![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 84.0.4125.0 | :white_check_mark: | :white_check_mark: | :white_check_mark: | | WebKit 13.0.4 | :white_check_mark: | :white_check_mark: | :white_check_mark: | | Firefox 76.0b5 | :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 index dd3fe2ef0d06e..a5521a04f8342 100644 --- 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) \ No newline at end of file diff --git a/docs/intro.md b/docs/intro.md index ffeaac09e3271..6130e444e0eb3 100644 --- a/docs/intro.md +++ b/docs/intro.md @@ -1,26 +1,14 @@ -# Introduction +# Getting Started -## What is Playwright? + +- [Installation](#installation) +- [Usage](#usage) +- [Writing your first script](#writing-your-first-script) +- [Debugging scripts](#debugging-scripts) +- [Deploying to CI](#deploying-to-ci) + -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. @@ -28,9 +16,9 @@ Use npm or Yarn to install Playwright in your Node.js project. Playwright requir 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 Chromium Developer Tools 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