docs(readme): update structure (#9)

Author: arjunattam

CONTRIBUTING.md

@@ -0,0 +1,13 @@
+# Contributing
+
+This project welcomes contributions and suggestions.  Most contributions require you to agree to a
+Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
+the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
+
+When you submit a pull request, a CLA bot will automatically determine whether you need to provide
+a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions
+provided by the bot. You will only need to do this once across all repos using our CLA.
+
+This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
+For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
+contact [[email protected]](mailto:[email protected]) with any additional questions or comments.

README.md

@@ -1,78 +1,80 @@
-# Pytest Playwright Plugin
+# Pytest plugin for Playwright [![PyPI](https://img.shields.io/pypi/v/pytest-playwright)](https://pypi.org/project/pytest-playwright/)
 
-![CI](https://github.com/microsoft/playwright-pytest/workflows/CI/badge.svg)
-[![PyPI](https://img.shields.io/pypi/v/pytest-playwright)](https://pypi.org/project/pytest-playwright/)
-[![black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/python/black)
+Write end-to-end tests for your web apps with [Playwright](https://github.com/microsoft/playwright-python) and [pytest](https://docs.pytest.org/en/stable/).
 
-> A Pytest wrapper for [Playwright](https://github.com/microsoft/playwright-python) to automate web browsers (Chromium, Firefox, WebKit).
+- Support for **all modern browsers** including Chromium, WebKit and Firefox.
+- Support for **headless and headful** execution.
+- **Built-in fixtures** that provide browser primitives to test functions.
 
-## Features
-
-- Have a separate new page and context for each test with Pytest fixtures
-- Run your end-to-end tests on multiple browsers by a CLI argument
-- Run them headful with the `--headful` argument to debug them easily
-- Using [base-url](https://github.com/pytest-dev/pytest-base-url) to only use the relative URL in your `Page.goto` calls
-
-## Installation
+## Usage
 
 ```
 pip install pytest-playwright
 ```
 
-Basic example for more see the [examples sections](#examples) as a reference.
+Use the `page` fixture to write a basic test. See [more examples](#examples).
 
 ```py
 def test_example_is_working(page):
     page.goto("https://example.com")
-    page.waitForSelector("text=Example Domain")
+    assert page.innerText('h1') == 'Example Domain'
     page.click("text=More information")
 ```
 
-## Fixtures
-
-### `browser_name` - session scope
-
-A string that contains the current browser name.
+To run your tests, use pytest CLI.
 
-### `browser` - session scope
+```sh
+# Run tests (Chromium and headless by default)
+pytest
 
-A Playwright browser instance for the session.
+# Run tests in headful mode
+pytest --headful
 
-### `context` - function scope
+# Run tests in a different browser (chromium, firefox, webkit)
+pytest --browser firefox
 
-A separate Playwright context instance for each new test.
-
-### `page` - function scope
-
-A separate Playwright page instance for each new test.
-
-### `browser_type_launch_args` - session scope
+# Run tests in multiple browsers
+pytest --browser chromium --browser webkit
+```
 
-A fixture that you can define to overwrite the launch arguments for [`launch()`](https://playwright.dev/#path=docs%2Fapi.md&q=browsertypelaunchoptions). It should return a Dict.
+## Fixtures
+This plugin configures Playwright-specific [fixtures for pytest](https://docs.pytest.org/en/latest/fixture.html). To use these fixtures, use the fixture name as an argument to the test function.
 
-### `browser_context_args` - session scope
+```py
+def test_my_app_is_working(fixture_name):
+    # Test using fixture_name
+    # ...
+```
 
-A fixture that you can define to overwrite the context arguments for [`newContext()`](https://playwright.dev/#path=docs%2Fapi.md&q=browsernewcontextoptions). It should return a Dict.
+**Function scope**: These fixtures are created when requested in a test function and destroyed when the test ends.
 
-### `is_chromium`, `is_firefox`, `is_webkit` - session scope
+- `context`: New [browser context](https://playwright.dev/#path=docs%2Fcore-concepts.md&q=browser-contexts) for a test.
+- `page`: New [browser page](https://playwright.dev/#path=docs%2Fcore-concepts.md&q=pages-and-frames) for a test.
 
-A fixture which is a boolean if a specific execution is made by the specified browser.
+**Session scope**: These fixtures are created when requested in a test function and destroyed when all tests end.
 
-## CLI arguments
+- `browser`: Browser instance launched by Playwright.
+- `browser_name`: Browser name as string.
+- `is_chromium`, `is_webkit`, `is_firefox`: Booleans for the respective browser types.
 
-### `--browser`
+**Customizing fixture options**: For `browser` and `context` fixtures, use the the following fixtures to define custom launch options.
 
-By default, the tests run on the Chromium browser. You can pass multiple times the `--browser` flag to run it on different browsers or a single time to run it only on a specific browser.
+- `browser_type_launch_args`: Override launch arguments for [`browserType.launch()`](https://playwright.dev/#path=docs%2Fapi.md&q=browsertypelaunchoptions). It should return a Dict.
+- `browser_context_args`: Override the options for [`browser.newContext()`](https://playwright.dev/#path=docs%2Fapi.md&q=browsernewcontextoptions). It should return a Dict.
 
-Possible values: `chromium`, `firefox`, `webkit`
+## Examples
 
-### `--headful`
+#### Configure Mypy typings for auto-completion
 
-By default, the tests run in headless mode. You can pass the `--headful` CLI flag to run the browser in headful mode.
+```py
+from playwright.sync_api import Page
 
-## Examples
+def test_visit_admin_dashboard(page: Page):
+    page.goto("/admin")
+    # ...
+```
 
-### Skipping by browser type
+#### Skip test by browser
 
 ```py
 import pytest
@@ -83,7 +85,7 @@ def test_visit_example(page):
     # ...
 ```
 
-### Running only on a specific browser
+#### Run on a specific browser
 
 ```py
 import pytest
@@ -94,37 +96,40 @@ def test_visit_example(page):
     # ...
 ```
 
-### Handle base-url
+#### Configure base-url
 
-Start Pytest with the `base-url` argument. Example: `pytest --base-url http://localhost:8080`
+Start Pytest with the `base-url` argument. 
+
+```sh
+pytest --base-url http://localhost:8080
+```
 
 ```py
 def test_visit_example(page):
     page.goto("/admin")
     # -> Will result in http://localhost:8080/admin
 ```
 
-### Using Mypy types for auto completion
+## Debugging
 
-```py
-from playwright.sync_api import Page
+#### Use with pdb
+Use the `breakpoint()` statement in your test code to pause execution and get a [pdb](https://docs.python.org/3/library/pdb.html) REPL.
 
-def test_visit_admin_dashboard(page: Page):
-    page.goto("/admin")
+```py
+def test_bing_is_working(page):
+    page.goto("https://bing.com")
+    breakpoint()
     # ...
 ```
 
-## Debugging
-
-To pause the Pytest test execution and interact with the browser (if its launched with `headless=False`) via the developer tools or call Playwright interactively, you can use the `breakpoint()` statement in your code to get a [pdb](https://docs.python.org/3/library/pdb.html) inline REPL.
+#### Screenshot on test failure
 
-### Create a screenshot if a test fails
+You can capture screenshots for failed tests with a [pytest runtest hook](https://docs.pytest.org/en/6.1.0/reference.html?highlight=pytest_runtest_makereport#test-running-runtest-hooks). Add this to your `conftest.py` file.
 
-On the CI it's useful to have screenshots if a test is failing, this can be implemented by adding the following in your `conftest.py` which will store the screenshots in the `.playwright-screenshots` directory which can be uploaded e.g. in your CI as an artifact.
-
-This snippet requires `slugify` to convert test names to file paths, which can be installed with `pip install python-slugify`.
+Note that this snippet uses `slugify` to convert test names to file paths, which can be installed with `pip install python-slugify`.
 
 ```py
+# In conftest.py
 from slugify import slugify
 from pathlib import Path
 
@@ -137,20 +142,9 @@ def pytest_runtest_makereport(item, call) -> None:
             page.screenshot(path=str(screenshot_dir / f"{slugify(item.nodeid)}.png"))
 ```
 
-## Special thanks
+## Deploy to CI
+Use the [Playwright GitHub Action](https://github.com/microsoft/playwright-github-action) or [guides for other CI providers](https://playwright.dev/#path=docs%2Fci.md&q=) to deploy your tests to CI/CD
 
-[Max Schmitt](https://github.com/mxschmitt) for creating and maintaining the Pytest Playwright plugin.
-
-## Contributing
-
-This project welcomes contributions and suggestions.  Most contributions require you to agree to a
-Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
-the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.
-
-When you submit a pull request, a CLA bot will automatically determine whether you need to provide
-a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions
-provided by the bot. You will only need to do this once across all repos using our CLA.
+## Special thanks
 
-This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
-For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
-contact [[email protected]](mailto:[email protected]) with any additional questions or comments.
+Thanks to [Max Schmitt](https://github.com/mxschmitt) for creating and maintaining this project.