docs: updated for the Pytest usage (microsoft#135)

Author: mxschmitt

README.md

@@ -1,4 +1,4 @@
-# 🎭 Playwright for Python
+# 🎭 [Playwright](https://github.com/microsoft/playwright) for Python
 
 [![PyPI version](https://badge.fury.io/py/playwright.svg)](https://pypi.python.org/pypi/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-86.0.4217.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-78.0b5-blue.svg?logo=mozilla-firefox)](https://www.mozilla.org/en-US/firefox/new/)<!-- GEN:stop --> [![WebKit version](https://img.shields.io/badge/webkit-14.0-blue.svg?logo=safari)](https://webkit.org/)
 [![Coverage Status](https://coveralls.io/repos/github/microsoft/playwright-python/badge.svg?branch=master)](https://coveralls.io/github/microsoft/playwright-python?branch=master)
@@ -15,12 +15,11 @@ Playwright is a Python library to automate [Chromium](https://www.chromium.org/H
 
 Headless execution is supported for all the browsers on all platforms.
 
-This is a Python 3 version of the [https://github.com/microsoft/playwright](https://github.com/microsoft/playwright) project.
-
-## Usage
+## Installation
 
 ```
 pip install playwright
+python -m playwright install
 ```
 
 This installs Playwright and browser binaries for Chromium, Firefox and WebKit. Once installed, you can `import` Playwright in a Python script and automate web browser interactions.
@@ -41,6 +40,57 @@ Playwright is built to automate the broad and growing set of web browser capabil
 * Native input events for mouse and keyboard
 * Upload and download files
 
+## Usage
+
+### Pytest
+
+For writing end-to-end tests we recommend to use the official [Pytest plugin](https://github.com/microsoft/playwright-pytest#readme) for Playwright. It contains utilities for running it on multiple browsers, having a new page instance on every test or base-url support via a command-line argument. This will in the end look like that:
+
+```py
+def test_playwright_is_visible_on_google(page):
+    page.goto("https://www.google.com")
+    page.type("input[name=q]", "Playwright GitHub")
+    page.click("input[type=submit]")
+    page.waitForSelector("text=microsoft/Playwright")
+```
+
+For more information checkout the project on [GitHub](https://github.com/microsoft/playwright-pytest#readme).
+
+### Standalone
+
+For using Playwright standalone, you can either use the sync version or the async variant (async/await). In most cases the sync variant is the right choice to automate the web browsers e.g. for writing end-to-end tests. Both will get initialized with a context manager.
+
+#### Sync variant
+
+```py
+from playwright import sync_playwright
+
+with sync_playwright() as p:
+    for browser_type in [p.chromium, p.firefox, p.webkit]:
+        browser = browser_type.launch()
+        page = browser.newPage()
+        page.goto('http://whatsmyuseragent.org/')
+        page.screenshot(path=f'example-{browser_type.name}.png')
+        browser.close()
+```
+
+#### Async variant
+
+```py
+import asyncio
+from playwright import async_playwright
+
+async def main():
+    async with async_playwright() as p:
+        browser = await p.webkit.launch()
+        page = await browser.newPage()
+        await page.goto('http://whatsmyuseragent.org/')
+        await page.screenshot(path=f'example-{browser_type.name}.png')
+        await browser.close()
+
+asyncio.get_event_loop().run_until_complete(main())
+```
+
 ## Examples
 
 #### Page screenshot
@@ -83,7 +133,7 @@ with sync_playwright() as p:
     browser.close()
 ```
 
-... or, if you are comfortable using asyncio, you can do the following:
+The asyncio variant:
 
 ```py
 import asyncio
@@ -131,7 +181,7 @@ with sync_playwright() as p:
     browser.close()
 ```
 
-... and again, async version:
+The asyncio variant:
 
 ```py
 import asyncio
@@ -177,7 +227,7 @@ with sync_playwright() as p:
     browser.close()
 ```
 
-... async version:
+The asyncio variant:
 
 ```py
 import asyncio
@@ -201,9 +251,9 @@ async def main():
 asyncio.get_event_loop().run_until_complete(main())
 ```
 
-# Is Playwright for Python ready?
+## Is Playwright for Python ready?
 
-We are ready for your feedback, but we are still covering Playwright Python with the tests, so expect a bumpy ride and don't use for production.
+We are ready for your feedback, but we are still covering Playwright Python with the tests, so expect some API changes and don't use for production.
 
 ## Resources