From e2241596833a74f86860d6e4ed05afde5490b74e Mon Sep 17 00:00:00 2001
From: Ross Wollman <rwoll@users.noreply.github.com>
Date: Thu, 4 Aug 2022 22:12:05 -0700
Subject: [PATCH] docs(python): pytest-xdist reference (#16231)

Partially resolves https://github.com/microsoft/playwright-python/issues/1442.

Tests: https://github.com/microsoft/playwright-pytest/pull/128.
---
 docs/src/running-tests-python.md |  8 ++++++++
 docs/src/test-runners-python.md  | 15 +++++++++++++++
 2 files changed, 23 insertions(+)

diff --git a/docs/src/running-tests-python.md b/docs/src/running-tests-python.md
index 4978556f1a..d53be9a927 100644
--- a/docs/src/running-tests-python.md
+++ b/docs/src/running-tests-python.md
@@ -47,6 +47,14 @@ You can run a single test, a set of tests or all tests. Tests can be run on one
   pytest test_login.py --browser webkit --browser firefox
   ```
 
+- Running Tests in parallel
+
+  ```bash
+  pytest --numprocesses auto
+  ```
+
+  (This assumes `pytest-xdist` is installed. For more information see [here](./test-runners.md#parallelism-running-multiple-tests-at-once).)
+
 For more information see [Playwright Pytest usage](./test-runners.md) or the Pytest documentation for [general CLI usage](https://docs.pytest.org/en/stable/usage.html).
 
 ## Running Tests
diff --git a/docs/src/test-runners-python.md b/docs/src/test-runners-python.md
index 2370a5c8e0..1057182ee6 100644
--- a/docs/src/test-runners-python.md
+++ b/docs/src/test-runners-python.md
@@ -63,6 +63,21 @@ def test_my_app_is_working(fixture_name):
 - `browser_type_launch_args`: Override launch arguments for [`method: BrowserType.launch`]. It should return a Dict.
 - `browser_context_args`: Override the options for [`method: Browser.newContext`]. It should return a Dict.
 
+## Parallelism: Running Multiple Tests at Once
+
+If your tests are running on a machine with a lot of CPUs, you can speed up the overall execution time of your test suite by using [`pytest-xdist`](https://pypi.org/project/pytest-xdist/) to run multiple tests at once:
+
+```bash
+# install dependency
+pip install pytest-xdist
+# use the --numprocesses flag
+pytest --numprocesses auto
+```
+
+Depending on the hardware and nature of your tests, you can set `numprocesses` to be anywhere from `2` to the number of CPUs on the machine. If set too high, you may notice unexpected behavior.
+
+See [Running Tests](./running-tests.md) for general information on `pytest` options.
+
 ## Examples
 
 ### Configure Mypy typings for auto-completion