From 2db02c9a05fa78b67e71aa243fe79360ec289dc7 Mon Sep 17 00:00:00 2001 From: Dmitry Gozman Date: Sat, 16 Jan 2021 06:42:40 -0800 Subject: [PATCH] docs(python): update installation docs (#5039) --- .../{installation.md => installation-js.md} | 6 +- docs/src/installation-python.md | 126 ++++++++++++++++++ docs/src/why-playwright.md | 11 +- 3 files changed, 139 insertions(+), 4 deletions(-) rename docs/src/{installation.md => installation-js.md} (95%) create mode 100644 docs/src/installation-python.md diff --git a/docs/src/installation.md b/docs/src/installation-js.md similarity index 95% rename from docs/src/installation.md rename to docs/src/installation-js.md index 4c28c22f74..505ee7def9 100644 --- a/docs/src/installation.md +++ b/docs/src/installation-js.md @@ -14,13 +14,13 @@ Each version of Playwright needs specific versions of browser binaries to operat - `~/.cache/ms-playwright` on Linux ```sh -npm i -D playwright +$ npm i -D playwright ``` These browsers will take few hundreds of megabytes of the disk space when installed: ```sh -du -hs ./Library/Caches/ms-playwright/* +$ du -hs ./Library/Caches/ms-playwright/* 281M chromium-XXXXXX 187M firefox-XXXX 180M webkit-XXXX @@ -52,9 +52,11 @@ Or you can opt into the hermetic install and place binaries under the `node_modu ```sh # Linux/macOS +# Places binaries to node_modules/playwright $ PLAYWRIGHT_BROWSERS_PATH=0 npm i -D playwright # Windows +# Places binaries to node_modules\playwright $ set PLAYWRIGHT_BROWSERS_PATH=0 $ npm i -D playwright ``` diff --git a/docs/src/installation-python.md b/docs/src/installation-python.md new file mode 100644 index 0000000000..1adc5cb06a --- /dev/null +++ b/docs/src/installation-python.md @@ -0,0 +1,126 @@ +--- +id: installation +title: "Installation" +--- + + + +## Managing browser binaries + +Each version of Playwright needs specific versions of browser binaries to operate. By default Playwright downloads Chromium, WebKit and Firefox browsers into the OS-specific cache folders: + +- `%USERPROFILE%\AppData\Local\ms-playwright` on Windows +- `~/Library/Caches/ms-playwright` on MacOS +- `~/.cache/ms-playwright` on Linux + +```sh +$ pip install playwright +$ python -m playwright install +``` + +These browsers will take few hundreds of megabytes of the disk space when installed: + +```sh +$ du -hs ./Library/Caches/ms-playwright/* +281M chromium-XXXXXX +187M firefox-XXXX +180M webkit-XXXX +``` + +You can override default behavior using environment variables. When installing Playwright, ask it to download browsers into a specific location: + +```sh +# Linux/macOS +$ pip install playwright +$ PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers python -m playwright install + +# Windows +$ set PLAYWRIGHT_BROWSERS_PATH=%USERPROFILE%\pw-browsers +$ pip install playwright +$ python -m playwright install +``` + +When running Playwright scripts, ask it to search for browsers in a shared location: + +```sh +# Linux/macOS +$ PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers python playwright_script.js + +# Windows +$ set PLAYWRIGHT_BROWSERS_PATH=%USERPROFILE%\pw-browsers +$ python playwright_script.py +``` + +Or you can opt into the hermetic install and place binaries under the `site-packages/playwright` folder: + +```sh +# Linux/macOS +$ pip install playwright +$ PLAYWRIGHT_BROWSERS_PATH=0 python -m playwright install + +# Windows +$ set PLAYWRIGHT_BROWSERS_PATH=0 +$ pip install playwright +$ python -m playwright install +``` + +Playwright keeps track of packages that need those browsers and will garbage collect them as you update Playwright to the newer versions. + +:::note +Developers can opt-in in this mode via exporting `PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers` in their `.bashrc`. +::: + +## Download from artifact repository + +By default, Playwright downloads browsers from Microsoft and Google public CDNs. + +Sometimes companies maintain an internal artifact repository to host browser +binaries. In this case, Playwright can be configured to download from a custom +location using the `PLAYWRIGHT_DOWNLOAD_HOST` env variable. + +```sh +# Linux/macOS +$ pip install playwright +$ PLAYWRIGHT_DOWNLOAD_HOST=192.168.1.78 python -m playwright install + +# Windows +$ set PLAYWRIGHT_DOWNLOAD_HOST=192.168.1.78 +$ pip install playwright +$ python -m playwright install +``` + +It is also possible to use a per-browser download hosts using `PLAYWRIGHT_CHROMIUM_DOWNLOAD_HOST`, `PLAYWRIGHT_FIREFOX_DOWNLOAD_HOST` and `PLAYWRIGHT_WEBKIT_DOWNLOAD_HOST` env variables that +take precedence over `PLAYWRIGHT_DOWNLOAD_HOST`. + +```sh +# Linux/macOS +$ pip install playwright +$ PLAYWRIGHT_FIREFOX_DOWNLOAD_HOST=192.168.1.1 PLAYWRIGHT_DOWNLOAD_HOST=192.168.1.78 python -m playwright install +``` + +## Skip browser downloads + +In certain cases, it is desired to avoid browser downloads altogether because +browser binaries are managed separately. + +This can be done by setting `PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD` variable before installation. + +```sh +# Linux/macOS +$ pip install playwright +$ PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 python -m playwright install + +# Windows +$ set PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 +$ pip install playwright +$ python -m playwright install +``` + +## Download single browser binary + +Playwright downloads Chromium, Firefox and WebKit browsers by default. To install a specific browser, pass it as an argument during installation. + +```sh +$ pip install playwright +$ python -m playwright install firefox +``` diff --git a/docs/src/why-playwright.md b/docs/src/why-playwright.md index 3f5084f49f..c8c7f25499 100644 --- a/docs/src/why-playwright.md +++ b/docs/src/why-playwright.md @@ -30,12 +30,19 @@ Playwright enables fast, reliable and capable automation across all modern brows * **Powerful network control**. Playwright introduces context-wide [network interception](./network.md) to stub and mock network requests. -* **Modern web features**. Playwright supports web components through [shadow-piercing selectors](./selectors.md), [geolocation, permissions](./emulation.md), web workers and other modern web APIs. +* **Modern web features**. Playwright supports web components through [shadow-piercing selectors](./selectors.md), [geolocation, permissions](./emulation.md), web workers and other modern web APIs. * **Capabilities to cover all scenarios**. Support for [file downloads](./network.md) and [uploads](./input.md), out-of-process iframes, native [input events](./input.md), and even [dark mode](./emulation.md). ## Integrates with your workflow -* **One-line installation**. Running `npm i playwright` auto-downloads browser dependencies for your team to be onboarded quickly. +* **One-line installation**. Installing Playwright auto-downloads browser dependencies for your team to be onboarded quickly. + ```sh js + $ npm i playwright + ``` + ```sh python + $ pip install playwright + $ python -m playwright install + ``` * **TypeScript support**. Playwright ships with built-in types for auto-completion and other benefits.