From 4f9b7d5ad6995f421c0f57f0441e469660dcd990 Mon Sep 17 00:00:00 2001 From: Yury Semikhatsky Date: Tue, 23 Feb 2021 13:23:44 -0800 Subject: [PATCH] docs: add intro docs for java (#5563) --- docs/src/installation-java.md | 83 +++++++++++++++++++++++++++++++++++ docs/src/intro-java.md | 79 +++++++++++++++++++++++++++++++++ 2 files changed, 162 insertions(+) create mode 100644 docs/src/installation-java.md create mode 100644 docs/src/intro-java.md diff --git a/docs/src/installation-java.md b/docs/src/installation-java.md new file mode 100644 index 0000000000..2fe0784165 --- /dev/null +++ b/docs/src/installation-java.md @@ -0,0 +1,83 @@ +--- +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 + +Every time `Playwright.create()` is called it will check if the browsers are in the local cache and if not download them. + +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 running Playwright scripts, ask it to search for browsers in a shared location: + +```sh +# Linux/macOS +$ PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers mvn test + +# Windows +$ set PLAYWRIGHT_BROWSERS_PATH=%USERPROFILE%\pw-browsers +$ mvn test +``` + +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 +$ PLAYWRIGHT_DOWNLOAD_HOST=192.168.1.78 mvn test + +# Windows +$ set PLAYWRIGHT_DOWNLOAD_HOST=192.168.1.78 +$ mvn test +``` + +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 +$ PLAYWRIGHT_FIREFOX_DOWNLOAD_HOST=192.168.1.1 PLAYWRIGHT_DOWNLOAD_HOST=192.168.1.78 mvn test +``` + +## 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 +$ PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 mvn test + +# Windows +$ set PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 +$ mvn test +``` diff --git a/docs/src/intro-java.md b/docs/src/intro-java.md new file mode 100644 index 0000000000..90a34d9f8e --- /dev/null +++ b/docs/src/intro-java.md @@ -0,0 +1,79 @@ +--- +id: intro +title: "Getting Started" +--- + + +- [Release notes](./release-notes.md) + +## Installation + +Playwright is distributed as a set of [Maven](https://maven.apache.org/what-is-maven.html) modules. The easiest way to use it is to add one dependency to your project's `pom.xml` as described below. If you're not familiar with Maven please refer to its [documentation](https://maven.apache.org/guides/getting-started/maven-in-five-minutes.html). + +```xml + + com.microsoft.playwright + playwright + 0.180.0 + +``` + +These commands download the Playwright package and install browser binaries for Chromium, Firefox and WebKit. To modify this behavior see [installation parameters](./installation.md). + +## Usage + +Once installed, you can `import` Playwright in a Java file, and launch any of the 3 browsers (`chromium`, `firefox` and `webkit`). + +```java +import com.microsoft.playwright.*; + +public class Example { + public static void main(String[] args) { + try (Playwright playwright = Playwright.create()) { + Browser browser = playwright.chromium().launch(); + Page page = browser.newPage(); + page.navigate("http://playwright.dev"); + System.out.println(page.title()); + } + } +} +``` + +## First script + +In our first script, we will navigate to `whatsmyuseragent.org` and take a screenshot in WebKit. + +```java +import com.microsoft.playwright.*; +import java.nio.file.Paths; + +public class WebKitScreenshot { + public static void main(String[] args) { + try (Playwright playwright = Playwright.create()) { + Browser browser = playwright.webkit().launch(); + Page page = browser.newPage(); + page.navigate("http://whatsmyuseragent.org/"); + page.screenshot(new Page.ScreenshotOptions().withPath(Paths.get("example.png"))); + } + } +} +``` + +By default, Playwright runs the browsers in headless mode. To see the browser UI, pass the `headless=false` flag while launching the browser. You can also use [`option: slowMo`] to slow down execution. Learn more in the debugging tools [section](./debug.md). + +```java +playwright.firefox().launch(new BrowserType.LaunchOptions().withHeadless(false).withSlowMo(50)); +``` + +## System requirements + +Playwright requires **Java 8** or newer. The browser binaries for Chromium, +Firefox and WebKit work across the 3 platforms (Windows, macOS, Linux): + +* **Windows**: Works with Windows and Windows Subsystem for Linux (WSL). +* **macOS**: Requires 10.14 or above. +* **Linux**: Depending on your Linux distribution, you might need to install additional + dependencies to run the browsers. + * Firefox requires Ubuntu 18.04+ + * For Ubuntu 18.04, the additional dependencies are defined in [our Docker image](https://github.com/microsoft/playwright/blob/master/utils/docker/Dockerfile.bionic), + which is based on Ubuntu.