Filip/playwright
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity

docs: refresh getting started docs (#8054)

Browse source
This commit is contained in:
Pavel Feldman 2021-08-06 14:02:41 -07:00 committed by GitHub
parent 80cccfd837
commit 79e8592146
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
16 changed files with 949 additions and 845 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
docs/src/api/class-android.md
View file

@ -1,7 +1,7 @@
# class: Android
* langs: js
Playwright has **experimental** support for Android automation. This includes Chrome for Android and Android WebView. You can access android namespace via:
Playwright has **experimental** support for Android automation. This includes Chrome for Android and Android WebView.
*Requirements*

454
docs/src/browsers.md
View file

@ -3,7 +3,7 @@ id: browsers
title: "Browsers"
---
Each version of Playwright needs specific versions of browser binaries to operate. Depending on the language you use, Playwright will either download these browsers at package install time for you or will require you to use [Playwright CLI](./cli.md) to install the browsers. Please refer to the [getting started](./intro.md) to see what your platform port does.
Each version of Playwright needs specific versions of browser binaries to operate. Depending on the language you use, Playwright will either download these browsers at package install time for you will use [Playwright CLI](./cli.md) to install these browsers.
With every release, Playwright updates the versions of the browsers it supports, so that the latest Playwright would support the latest browsers at any moment. It means that every time you update playwright, you might need to re-run the `install` CLI command.
@ -12,9 +12,8 @@ With every release, Playwright updates the versions of the browsers it supports,
## Chromium
For Google Chrome, Microsoft Edge and other Chromium-based browsers, by default, Playwright uses open source Chromium builds.
Since Chromium project is ahead of the branded browsers,
when the world is on Google Chrome 89, Playwright already supports Chromium 91 that will hit Google Chrome and Microsoft Edge
in a few weeks.
Since Chromium project is ahead of the branded browsers, when the world is on Google Chrome N, Playwright already supports
Chromium N+1 that will be released in Google Chrome and Microsoft Edge in a few weeks.
There is also a way to opt into using Google Chrome's or Microsoft Edge's branded builds for testing. For details
on when to opt into stable channels, refer to the [Google Chrome & Microsoft Edge](#google-chrome--microsoft-edge) section below.
@ -31,11 +30,34 @@ other WebKit-based browsers. This gives a lot of lead time to react on the poten
## Google Chrome & Microsoft Edge
While Playwright will download and use the recent Chromium build by default, it can operate against the stock Google
Chrome and Microsoft Edge browsers available on the machine. In particular, current Playwright version will support Stable and Beta channels
of these browsers. Here is how you can opt into using the stock browser:
While Playwright can download and use the recent Chromium build, it can operate against the stock Google
Chrome and Microsoft Edge browsers available on the machine. In particular, current Playwright version will
support Stable and Beta channels of these browsers. Here is how you can opt into using the stock browser:
```js
```js js-flavor=js
// @ts-check
/** @type {import('@playwright/test').PlaywrightTestConfig} */
const config = {
use: {
channel: 'chrome',
},
};
module.exports = config;
```
```js js-flavor=ts
import { PlaywrightTestConfig } from '@playwright/test';
const config: PlaywrightTestConfig = {
use: {
channel: 'chrome',
},
};
export default config;
```
```js js-flavor=library
const { chromium } = require('playwright');
const browser = await chromium.launch({
channel: 'chrome' // or 'msedge', 'chrome-beta', 'msedge-beta', 'msedge-dev', etc.
@ -82,10 +104,6 @@ class Program
}
```
:::note
Playwright bundles a recent Chromium build, but not Google Chrome or Microsoft Edge browsers - these should be installed manually before use. You can use Playwright [Command Line Interface](./cli.md#install-browsers) to install the browsers.
:::
### When to use Google Chrome & Microsoft Edge and when not to?
**Defaults**
@ -114,3 +132,415 @@ Google Chrome and Microsoft Edge respect enterprise policies, which include limi
network proxy, mandatory extensions that stand in the way of testing. So if you are a part of the
organization that uses such policies, it is the easiest to use bundled Chromium for your local testing,
you can still opt into stable channels on the bots that are typically free of such restrictions.
## Installing browsers
### Prerequisites for .NET
This conversation was marked as resolved by pavelfeldman
* langs: csharp
All examples require the `Microsoft.Playwright.CLI` to be installed. You only have to do this once:
```bash
dotnet tool install -g Microsoft.Playwright.CLI
```
Playwright can install supported browsers by means of the CLI tool.
```bash js
# Running without arguments will install all browsers
npx playwright install
```
```bash java
# Running without arguments will install all browsers
mvn exec:java -e -Dexec.mainClass=com.microsoft.playwright.CLI -Dexec.args="install"
```
```bash python
# Running without arguments will install all browsers
playwright install
```
```bash csharp
# Running without arguments will install all browsers
playwright install
```
You can also install specific browsers by providing an argument:
```bash js
# Install WebKit
npx playwright install webkit
```
```bash java
# Install WebKit
mvn exec:java -e -Dexec.mainClass=com.microsoft.playwright.CLI -Dexec.args="install webkit"
```
```bash python
# Install WebKit
playwright install webkit
```
```bash csharp
# Install WebKit
playwright install webkit
```
See all supported browsers:
```bash js
npx playwright install --help
```
```bash java
mvn exec:java -e -Dexec.mainClass=com.microsoft.playwright.CLI -Dexec.args="install --help"
```
```bash python
playwright install --help
```
```bash csharp
playwright install --help
```
## Managing browser binaries
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
These browsers will take a few hundred megabytes of disk space when installed:
```bash
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:
```bash js
# Linux/macOS
PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers npx playwright install
# Windows with cmd.exe
set PLAYWRIGHT_BROWSERS_PATH=%USERPROFILE%\pw-browsers
npx playwright install
# Windows with PowerShell
$env:PLAYWRIGHT_BROWSERS_PATH="$env:USERPROFILE\pw-browsers"
npx playwright install
```
```bash python
# Linux/macOS
pip install playwright
PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers python -m playwright install
# Windows with cmd.exe
set PLAYWRIGHT_BROWSERS_PATH=%USERPROFILE%\pw-browsers
pip install playwright
playwright install
# Windows with PowerShell
$env:PLAYWRIGHT_BROWSERS_PATH="$env:USERPROFILE\pw-browsers"
pip install playwright
playwright install
```
```bash java
# Linux/macOS
PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers mvn test
# Windows with cmd.exe
set PLAYWRIGHT_BROWSERS_PATH=%USERPROFILE%\pw-browsers
mvn test
# Windows with PowerShell
$env:PLAYWRIGHT_BROWSERS_PATH="$env:USERPROFILE\pw-browsers"
mvn test
```
```bash csharp
# Linux/macOS
PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers
playwright install
# Windows with cmd.exe
set PLAYWRIGHT_BROWSERS_PATH=%USERPROFILE%\pw-browsers
playwright install
# Windows with PowerShell
$env:PLAYWRIGHT_BROWSERS_PATH="$env:USERPROFILE\pw-browsers"
playwright install
```
When running Playwright scripts, ask it to search for browsers in a shared location.
```bash js
# Linux/macOS
PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers npx playwright test
# Windows with cmd.exe
set PLAYWRIGHT_BROWSERS_PATH=%USERPROFILE%\pw-browsers
npx playwright test
# Windows with PowerShell
$env:PLAYWRIGHT_BROWSERS_PATH="$env:USERPROFILE\pw-browsers"
npx playwright test
```
```bash python
# Linux/macOS
PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers python playwright_script.py
# Windows with cmd.exe
set PLAYWRIGHT_BROWSERS_PATH=%USERPROFILE%\pw-browsers
python playwright_script.py
# Windows with PowerShell
$env:PLAYWRIGHT_BROWSERS_PATH="$env:USERPROFILE\pw-browsers"
python playwright_script.py
```
```bash java
# Windows with cmd.exe
set PLAYWRIGHT_BROWSERS_PATH=%USERPROFILE%\pw-browsers
mvn test
# Windows with PowerShell
$env:PLAYWRIGHT_BROWSERS_PATH="$env:USERPROFILE\pw-browsers"
mvn test
```
```bash csharp
# Linux/macOS
PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers dotnet test
# Windows with cmd.exe
set PLAYWRIGHT_BROWSERS_PATH=%USERPROFILE%\pw-browsers
dotnet test
# Windows with PowerShell
$env:PLAYWRIGHT_BROWSERS_PATH="$env:USERPROFILE\pw-browsers"
dotnet 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`.
:::
### Managing browser binaries
* lang: js
You can opt into the hermetic install and place binaries in the local folder:
```bash
# Linux/macOS
# Places binaries to node_modules/@playwright/test
PLAYWRIGHT_BROWSERS_PATH=0 npx playwright install
# Windows with cmd.exe
# Places binaries to node_modules\@playwright\test
set PLAYWRIGHT_BROWSERS_PATH=0
npx playwright install
# Windows with PowerShell
# Places binaries to node_modules\@playwright\test
$env:PLAYWRIGHT_BROWSERS_PATH=0
npx playwright install
```
## Install behind a firewall or a proxy
By default, Playwright downloads browsers from Microsoft CDN.
Sometimes companies maintain an internal proxy that blocks direct access to the public
resources. In this case, Playwright can be configured to download browsers via a proxy server.
```bash python
# Linux/macOS
pip install playwright
HTTPS_PROXY=https://192.0.2.1 playwright install
# Windows with cmd.exe
set HTTPS_PROXY=https://192.0.2.1
pip install playwright
playwright install
# Windows with PowerShell
$env:HTTPS_PROXY="https://192.0.2.1"
pip install playwright
playwright install
```
```bash java
# Linux/macOS
HTTPS_PROXY=https://192.0.2.1 mvn test
# Windows with cmd.exe
set HTTPS_PROXY=https://192.0.2.1
mvn test
# Windows with PowerShell
$env:HTTPS_PROXY="https://192.0.2.1"
mvn test
```
```bash csharp
# Linux/macOS
HTTPS_PROXY=https://192.0.2.1 playwright install
# Windows with cmd.exe
set HTTPS_PROXY=https://192.0.2.1
playwright install
# Windows with PowerShell
$env:HTTPS_PROXY="https://192.0.2.1"
playwright install
```
## Download from artifact repository
By default, Playwright downloads browsers from Microsoft CDN.
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.
```bash python
# Linux/macOS
pip install playwright
PLAYWRIGHT_DOWNLOAD_HOST=192.0.2.1 playwright install
# Windows with cmd.exe
set PLAYWRIGHT_DOWNLOAD_HOST=192.0.2.1
pip install playwright
playwright install
# Windows with PowerShell
$env:PLAYWRIGHT_DOWNLOAD_HOST="192.0.2.1"
pip install playwright
playwright install
```
```bash java
# Linux/macOS
PLAYWRIGHT_DOWNLOAD_HOST=192.0.2.1 mvn test
# Windows with cmd.exe
set PLAYWRIGHT_DOWNLOAD_HOST=192.0.2.1
mvn test
# Windows with PowerShell
$env:PLAYWRIGHT_DOWNLOAD_HOST="192.0.2.1"
mvn test
```
```bash csharp
# Linux/macOS
PLAYWRIGHT_DOWNLOAD_HOST=192.0.2.1 playwright install
# Windows with cmd.exe
set PLAYWRIGHT_DOWNLOAD_HOST=192.0.2.1
playwright install
# Windows with PowerShell
$env:PLAYWRIGHT_DOWNLOAD_HOST="192.0.2.1"
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`.
```bash python
# Linux/macOS
pip install playwright
PLAYWRIGHT_FIREFOX_DOWNLOAD_HOST=203.0.113.3 PLAYWRIGHT_DOWNLOAD_HOST=192.0.2.1 python -m playwright install
```
```bash java
# Linux/macOS
PLAYWRIGHT_FIREFOX_DOWNLOAD_HOST=203.0.113.3 PLAYWRIGHT_DOWNLOAD_HOST=192.0.2.1 mvn test
```
```bash csharp
# Linux/macOS
PLAYWRIGHT_FIREFOX_DOWNLOAD_HOST=203.0.113.3 PLAYWRIGHT_DOWNLOAD_HOST=192.0.2.1 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.
```bash python
# Linux/macOS
pip install playwright
PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 python -m playwright install
# Windows with cmd.exe
set PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1
pip install playwright
playwright install
# Windows with PowerShell
$env:PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1
pip install playwright
playwright install
```
```bash java
# Linux/macOS
PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 mvn test
# Windows with cmd.exe
set PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1
mvn test
# Windows with PowerShell
$env:PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1
mvn test
```
```bash csharp
# Linux/macOS
PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 playwright install
# Windows with cmd.exe
set PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1
playwright install
# Windows with PowerShell
$env:PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1
playwright install
```
## Download single browser binary
* langs: python
Playwright downloads Chromium, Firefox and WebKit browsers by default. To install a specific browser, pass it as an argument during installation.
```bash
pip install playwright
playwright install firefox
```
## Stale browser removal
Playwright keeps track of the clients that use its browsers. When there are no more clients that require particular
version of the browser, that version is deleted from the system. That way you can safely use Playwright instances of
different versions and at the same time, you don't waste disk space for the browsers that are no longer in use.
To opt-out from the unused browser removal, you can set the `PLAYWRIGHT_SKIP_BROWSER_GC=1` environment variable.

4
docs/src/ci.md
View file

@ -312,7 +312,7 @@ tests:
By default, Playwright downloads browser binaries when the Playwright NPM package
is installed. The NPM packages have a `postinstall` hook that downloads the browser
binaries. This behavior can be [customized with environment variables][installation-managing-browser-binaries].
binaries. This behavior can be [customized with environment variables](./browsers.md#managing-browser-binaries).
Caching browsers on CI is **strictly optional**: The `postinstall` hooks should
execute and download the browser binaries on every run.
@ -333,7 +333,7 @@ This behavior can be fixed with one of the following approaches:
behavior in most CI providers.)
1. Set `PLAYWRIGHT_BROWSERS_PATH=0` as the environment variable before running
`npm install`. This will download the browser binaries in the `node_modules`
directory and cache them with the package code. See [managing browser binaries][installation-managing-browser-binaries].
directory and cache them with the package code. See [managing browser binaries](./browsers.md#managing-browser-binaries).
1. Use `npm ci` (instead of `npm install`) which forces a clean install: by
removing the existing `node_modules` directory. See [npm docs](https://docs.npmjs.com/cli/ci.html).
1. Cache the browser binaries, with the steps below.

316
docs/src/installation.md
View file

@ -1,316 +0,0 @@
---
id: installation
title: "Installation"
---
<!-- TOC -->
### Prerequisites for .NET
* langs: csharp
All examples require the `Microsoft.Playwright.CLI` to be installed. You only have to do this once:
```bash
dotnet tool install -g Microsoft.Playwright.CLI
```
## 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
```bash python
pip install playwright
playwright install
```
```bash csharp
# In your solution/project folder...
playwright install
```
These browsers will take a few hundred megabytes of disk space when installed:
```bash
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:
```bash python
# Linux/macOS
pip install playwright
PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers python -m playwright install
# Windows with cmd.exe
set PLAYWRIGHT_BROWSERS_PATH=%USERPROFILE%\pw-browsers
pip install playwright
playwright install
# Windows with PowerShell
$env:PLAYWRIGHT_BROWSERS_PATH="$env:USERPROFILE\pw-browsers"
pip install playwright
playwright install
```
```bash java
# Linux/macOS
PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers mvn test
# Windows with cmd.exe
set PLAYWRIGHT_BROWSERS_PATH=%USERPROFILE%\pw-browsers
mvn test
# Windows with PowerShell
$env:PLAYWRIGHT_BROWSERS_PATH="$env:USERPROFILE\pw-browsers"
mvn test
```
```bash csharp
# Linux/macOS
PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers
playwright install
# Windows with cmd.exe
set PLAYWRIGHT_BROWSERS_PATH=%USERPROFILE%\pw-browsers
playwright install
# Windows with PowerShell
$env:PLAYWRIGHT_BROWSERS_PATH="$env:USERPROFILE\pw-browsers"
playwright install
```
When running Playwright scripts, ask it to search for browsers in a shared location.
```bash python
# Linux/macOS
PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers python playwright_script.js
# Windows with cmd.exe
set PLAYWRIGHT_BROWSERS_PATH=%USERPROFILE%\pw-browsers
python playwright_script.py
# Windows with PowerShell
$env:PLAYWRIGHT_BROWSERS_PATH="$env:USERPROFILE\pw-browsers"
python playwright_script.py
```
```bash java
# Windows with cmd.exe
set PLAYWRIGHT_BROWSERS_PATH=%USERPROFILE%\pw-browsers
mvn test
# Windows with PowerShell
$env:PLAYWRIGHT_BROWSERS_PATH="$env:USERPROFILE\pw-browsers"
mvn test
```
```bash csharp
# Linux/macOS
PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers dotnet test
# Windows with cmd.exe
set PLAYWRIGHT_BROWSERS_PATH=%USERPROFILE%\pw-browsers
dotnet test
# Windows with PowerShell
$env:PLAYWRIGHT_BROWSERS_PATH="$env:USERPROFILE\pw-browsers"
dotnet 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`.
:::
## Install behind a firewall or a proxy
By default, Playwright downloads browsers from Microsoft CDN.
Sometimes companies maintain an internal proxy that blocks direct access to the public
resources. In this case, Playwright can be configured to download browsers via a proxy server.
```bash python
# Linux/macOS
pip install playwright
HTTPS_PROXY=https://192.0.2.1 playwright install
# Windows with cmd.exe
set HTTPS_PROXY=https://192.0.2.1
pip install playwright
playwright install
# Windows with PowerShell
$env:HTTPS_PROXY="https://192.0.2.1"
pip install playwright
playwright install
```
```bash java
# Linux/macOS
HTTPS_PROXY=https://192.0.2.1 mvn test
# Windows with cmd.exe
set HTTPS_PROXY=https://192.0.2.1
mvn test
# Windows with PowerShell
$env:HTTPS_PROXY="https://192.0.2.1"
mvn test
```
```bash csharp
# Linux/macOS
HTTPS_PROXY=https://192.0.2.1 playwright install
# Windows with cmd.exe
set HTTPS_PROXY=https://192.0.2.1
playwright install
# Windows with PowerShell
$env:HTTPS_PROXY="https://192.0.2.1"
playwright install
```
## Download from artifact repository
By default, Playwright downloads browsers from Microsoft CDN.
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.
```bash python
# Linux/macOS
pip install playwright
PLAYWRIGHT_DOWNLOAD_HOST=192.0.2.1 playwright install
# Windows with cmd.exe
set PLAYWRIGHT_DOWNLOAD_HOST=192.0.2.1
pip install playwright
playwright install
# Windows with PowerShell
$env:PLAYWRIGHT_DOWNLOAD_HOST="192.0.2.1"
pip install playwright
playwright install
```
```bash java
# Linux/macOS
PLAYWRIGHT_DOWNLOAD_HOST=192.0.2.1 mvn test
# Windows with cmd.exe
set PLAYWRIGHT_DOWNLOAD_HOST=192.0.2.1
mvn test
# Windows with PowerShell
$env:PLAYWRIGHT_DOWNLOAD_HOST="192.0.2.1"
mvn test
```
```bash csharp
# Linux/macOS
PLAYWRIGHT_DOWNLOAD_HOST=192.0.2.1 playwright install
# Windows with cmd.exe
set PLAYWRIGHT_DOWNLOAD_HOST=192.0.2.1
playwright install
# Windows with PowerShell
$env:PLAYWRIGHT_DOWNLOAD_HOST="192.0.2.1"
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`.
```bash python
# Linux/macOS
pip install playwright
PLAYWRIGHT_FIREFOX_DOWNLOAD_HOST=203.0.113.3 PLAYWRIGHT_DOWNLOAD_HOST=192.0.2.1 python -m playwright install
```
```bash java
# Linux/macOS
PLAYWRIGHT_FIREFOX_DOWNLOAD_HOST=203.0.113.3 PLAYWRIGHT_DOWNLOAD_HOST=192.0.2.1 mvn test
```
```bash csharp
# Linux/macOS
PLAYWRIGHT_FIREFOX_DOWNLOAD_HOST=203.0.113.3 PLAYWRIGHT_DOWNLOAD_HOST=192.0.2.1 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.
```bash python
# Linux/macOS
pip install playwright
PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 python -m playwright install
# Windows with cmd.exe
set PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1
pip install playwright
playwright install
# Windows with PowerShell
$env:PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1
pip install playwright
playwright install
```
```bash java
# Linux/macOS
PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 mvn test
# Windows with cmd.exe
set PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1
mvn test
# Windows with PowerShell
$env:PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1
mvn test
```
```bash csharp
# Linux/macOS
PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 playwright install
# Windows with cmd.exe
set PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1
playwright install
# Windows with PowerShell
$env:PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1
playwright install
```
## Download single browser binary
* langs: python
Playwright downloads Chromium, Firefox and WebKit browsers by default. To install a specific browser, pass it as an argument during installation.
```bash
pip install playwright
playwright install firefox
```
## Stale browser removal
Playwright keeps track of the clients that use its browsers. When there are no more clients that require particular
version of the browser, that version is deleted from the system. That way you can safely use Playwright instances of
different versions and at the same time, you don't waste disk space for the browsers that are no longer in use.
To opt-out from the unused browser removal, you can set the `PLAYWRIGHT_SKIP_BROWSER_GC=1` environment variable.

2
docs/src/intro-java.md
View file

@ -87,7 +87,7 @@ With the Example.java and pom.xml above, compile and execute your new program as
mvn compile exec:java -Dexec.mainClass="org.example.Example"
```
Running it downloads the Playwright package and installs browser binaries for Chromium, Firefox and WebKit. To modify this behavior see [installation parameters](./installation.md).
Running it downloads the Playwright package and installs browser binaries for Chromium, Firefox and WebKit. To modify this behavior see [installation parameters](./browsers.md#installing-browsers).
## First script

266
docs/src/intro-js.md
View file

@ -3,7 +3,7 @@ id: intro
title: "Getting Started"
---
Playwright can either be used as a part of the Playwright Test, or as a [Playwright Library](./library.md). If you intend to use Playwright for testing, read on.
Playwright can either be used as a part of the Playwright Test (this guide), or as a [Playwright Library](./library.md).
Playwright Test was created specifically to accommodate the needs of the end-to-end testing. It does everything you would expect from the regular test runner, and more. Playwright test allows to:
@ -26,15 +26,11 @@ Playwright has its own test runner for end-to-end tests, we call it Playwright T
```bash
npm i -D @playwright/test
```
Unlike Playwright Library, Playwright Test does not bundle browsers by default, so you need to install them explicitly:
```bash
# install supported browsers
npx playwright install
```
You can optionally install only selected browsers, see [installing browsers](./test-install.md) for more details. Or you can install no browsers at all and use existing [browser channels](./browsers.md).
You can optionally install only selected browsers, see [installing browsers](./browsers.md#installing-browsers) for more details. Or you can install no browsers at all and use existing [browser channels](./browsers.md).
## First test
@ -45,8 +41,8 @@ const { test, expect } = require('@playwright/test');
test('basic test', async ({ page }) => {
await page.goto('https://playwright.dev/');
const name = await page.innerText('.navbar__title');
expect(name).toBe('Playwright');
const title = page.locator('.navbar__title');
await expect(title).toHaveText('Playwright');
});
```
@ -55,8 +51,8 @@ import { test, expect } from '@playwright/test';
test('basic test', async ({ page }) => {
await page.goto('https://playwright.dev/');
const name = await page.innerText('.navbar__title');
expect(name).toBe('Playwright');
const title = page.locator('.navbar__title');
await expect(title).toHaveText('Playwright');
});
```
@ -86,149 +82,34 @@ npx playwright test --browser=all
Refer to [configuration](./test-configuration.md) section for configuring test runs in different modes with different browsers.
## Test fixtures
You noticed an argument `{ page }` that the test above has access to:
## Writing assertions
```js js-flavor=js
test('basic test', async ({ page }) => {
...
```
Playwright Test uses [expect](https://jestjs.io/docs/expect) library for test assertions. It provides a lot of matchers like `toEqual`, `toContain`, `toMatch`, `toMatchSnapshot` and many more. Playwright also extends this set with the following matchers:
```js js-flavor=ts
test('basic test', async ({ page }) => {
...
```
- `toBeChecked`
- `toBeDisabled`
- `toBeEditable`
- `toBeEmpty`
- `toBeEnabled`
- `toBeFocused`
- `toBeHidden`
- `toBeSelected`
- `toBeVisible`
- `toContainText`
- `toHaveAttr`
- `toHaveClass`
- `toHaveCount`
- `toHaveCSS`
- `toHaveData`
- `toHaveId`
- `toHaveProp`
- `toHaveText`
- `toHaveTitle`
- `toHaveURL`
- `toHaveValue`
- `toMatchSnapshot`
We call these arguments `fixtures`. Fixtures are objects that are created for each test run. Playwright Test comes loaded with those fixtures, and you can add your own fixtures as well. When running tests, Playwright Test looks at each test declaration, analyses the set of fixtures the test needs and prepares those fixtures specifically for the test.
Here is a list of the pre-defined fixtures that you are likely to use most of the time:
|Fixture |Type |Description |
|:----------|:----------------|:--------------------------------|
|page |[Page] |Isolated page for this test run. |
|context |[BrowserContext] |Isolated context for this test run. The `page` fixture belongs to this context as well. Learn how to [configure context](./test-configuration.md). |
|browser |[Browser] |Browsers are shared across tests to optimize resources. Learn how to [configure browser](./test-configuration.md). |
|browserName|[string] |The name of the browser currently running the test. Either `chromium`, `firefox` or `webkit`.|
## Test and assertion features
If you are familiar with test runners like Jest, Mocha and Ava, you will find the Playwright Test syntax familiar. These are the basic things you can do with the test:
### Focus a test
You can focus some tests. When there are focused tests, only they run.
```js js-flavor=js
test.only('focus this test', async ({ page }) => {
// Run only focused tests in the entire project.
});
```
```js js-flavor=ts
test.only('focus this test', async ({ page }) => {
// Run only focused tests in the entire project.
});
```
### Skip a test
Mark a test as skipped.
```js js-flavor=js
test.skip('skip this test', async ({ page }) => {
// This test is not run
});
```
```js js-flavor=ts
test.skip('skip this test', async ({ page }) => {
// This test is not run
});
```
You can also skip a test when [some condition is met](./test-annotations.md#conditionally-skip-a-test).
### Group tests
You can group tests to give them a logical name or to scope before/after hooks to the group.
```js js-flavor=js
const { test, expect } = require('@playwright/test');
test.describe('two tests', () => {
test('one', async ({ page }) => {
// ...
});
test('two', async ({ page }) => {
// ...
});
});
```
```js js-flavor=ts
import { test, expect } from '@playwright/test';
test.describe('two tests', () => {
test('one', async ({ page }) => {
// ...
});
test('two', async ({ page }) => {
// ...
});
});
```
### Use test hooks
You can use `test.beforeAll` and `test.afterAll` hooks to set up and tear down resources shared between tests.
And you can use `test.beforeEach` and `test.afterEach` hooks to set up and tear down resources for each test individually.
```js js-flavor=js
// example.spec.js
const { test, expect } = require('@playwright/test');
test.describe('feature foo', () => {
test.beforeEach(async ({ page }) => {
// Go to the starting url before each test.
await page.goto('https://my.start.url/');
});
test('my test', async ({ page }) => {
// Assertions use the expect API.
expect(page.url()).toBe('https://my.start.url/');
});
});
```
```js js-flavor=ts
// example.spec.ts
import { test, expect } from '@playwright/test';
test.describe('feature foo', () => {
test.beforeEach(async ({ page }) => {
// Go to the starting url before each test.
await page.goto('https://my.start.url/');
});
test('my test', async ({ page }) => {
// Assertions use the expect API.
expect(page.url()).toBe('https://my.start.url/');
});
});
```
### Write assertions
Playwright Test uses [expect](https://jestjs.io/docs/expect) library for test assertions. It provides a lot of matchers like `toEqual`, `toContain`, `toMatch`, `toMatchSnapshot` and many more.
Combine `expect` with various Playwright methods to create expectations for your test:
- [`method: Page.isVisible`]
- [`method: Page.waitForSelector`]
- [`method: Page.textContent`]
- [`method: Page.getAttribute`]
- [`method: Page.screenshot`]
- Find out more in the [assertions](./assertions.md) guide
```js js-flavor=js
@ -239,17 +120,17 @@ test('my test', async ({ page }) => {
await page.goto('https://playwright.dev/');
// Expect a title "to contain" a substring.
expect(await page.title()).toContain('Playwright');
await expect(page).toHaveTitle('Playwright');
// Expect an attribute "to be strictly equal" to the value.
expect(await page.getAttribute('text=Get Started', 'href')).toBe('/docs/intro');
await expect(page.locator('text=Get Started').toHaveAttr('href', '/docs/intro');
// Expect an element "to be visible".
expect(await page.isVisible('text=Learn more')).toBeTruthy();
await expect(page.locator('text=Learn more')).toBeVisible();
await page.click('text=Get Started');
// Expect some text to be visible on the page.
expect(await page.waitForSelector('text=System requirements')).toBeTruthy();
await expect(page.locator('text=System requirements')).toBeVisible();
// Compare screenshot with a stored reference.
expect(await page.screenshot()).toMatchSnapshot('get-started.png');
@ -264,17 +145,17 @@ test('my test', async ({ page }) => {
await page.goto('https://playwright.dev/');
// Expect a title "to contain" a substring.
expect(await page.title()).toContain('Playwright');
await expect(page).toHaveTitle('Playwright');
// Expect an attribute "to be strictly equal" to the value.
expect(await page.getAttribute('text=Get Started', 'href')).toBe('/docs/intro');
await expect(page.locator('text=Get Started').toHaveAttr('href', '/docs/intro');
// Expect an element "to be visible".
expect(await page.isVisible('text=Learn more')).toBeTruthy();
await expect(page.locator('text=Learn more')).toBeVisible();
await page.click('text=Get Started');
// Expect some text to be visible on the page.
expect(await page.waitForSelector('text=System requirements')).toBeTruthy();
await expect(page.locator('text=System requirements')).toBeVisible();
// Compare screenshot with a stored reference.
expect(await page.screenshot()).toMatchSnapshot('get-started.png');
@ -303,7 +184,72 @@ npx playwright test --update-snapshots
```
## Learn the command line
## Using test fixtures
You noticed an argument `{ page }` that the test above has access to:
```js js-flavor=js
test('basic test', async ({ page }) => {
...
```
```js js-flavor=ts
test('basic test', async ({ page }) => {
...
```
We call these arguments `fixtures`. Fixtures are objects that are created for each test run. Playwright Test comes loaded with those fixtures, and you can add your own fixtures as well. When running tests, Playwright Test looks at each test declaration, analyses the set of fixtures the test needs and prepares those fixtures specifically for the test.
Here is a list of the pre-defined fixtures that you are likely to use most of the time:
|Fixture |Type |Description |
|:----------|:----------------|:--------------------------------|
|page |[Page] |Isolated page for this test run. |
|context |[BrowserContext] |Isolated context for this test run. The `page` fixture belongs to this context as well. Learn how to [configure context](./test-configuration.md). |
|browser |[Browser] |Browsers are shared across tests to optimize resources. Learn how to [configure browser](./test-configuration.md). |
|browserName|[string] |The name of the browser currently running the test. Either `chromium`, `firefox` or `webkit`.|
## Using test hooks
You can use `test.beforeAll` and `test.afterAll` hooks to set up and tear down resources shared between tests.
And you can use `test.beforeEach` and `test.afterEach` hooks to set up and tear down resources for each test individually.
```js js-flavor=js
// example.spec.js
const { test, expect } = require('@playwright/test');
test.describe('feature foo', () => {
test.beforeEach(async ({ page }) => {
// Go to the starting url before each test.
await page.goto('https://my.start.url/');
});
test('my test', async ({ page }) => {
// Assertions use the expect API.
await expect(page).toHaveURL('https://my.start.url/');
});
});
```
```js js-flavor=ts
// example.spec.ts
import { test, expect } from '@playwright/test';
test.describe('feature foo', () => {
test.beforeEach(async ({ page }) => {
// Go to the starting url before each test.
await page.goto('https://my.start.url/');
});
test('my test', async ({ page }) => {
// Assertions use the expect API.
await expect(page).toHaveURL('https://my.start.url/');
});
});
```
## Learning the command line
Here are the most common options available in the [command line](./test-cli.md).
@ -366,7 +312,7 @@ Here are the most common options available in the [command line](./test-cli.md).
npx playwright test
```
## Create a configuration file
## Creating a configuration file
So far, we've looked at the zero-config operation of Playwright Test. For a real world application, it is likely that you would want to use a config.

2
docs/src/intro-python.md
View file

@ -31,7 +31,7 @@ conda install playwright
playwright install
```
These commands download the Playwright package and install browser binaries for Chromium, Firefox and WebKit. To modify this behavior see [installation parameters](./installation.md).
These commands download the Playwright package and install browser binaries for Chromium, Firefox and WebKit. To modify this behavior see [installation parameters](./browsers.md#installing-browsers).
## Usage

185
docs/src/library-js.md
View file

@ -3,7 +3,7 @@ id: library
title: "Playwright Library"
---
Playwright can either be used as a part of the [Playwright Test](./intro.md), or as a standalone library. If you are working on an application that utilizes Playwright capabilities or you are using Playwright with another test runner, read on.
Playwright can either be used as a part of the [Playwright Test](./intro.md), or as a Playwright Library (this guide). If you are working on an application that utilizes Playwright capabilities or you are using Playwright with another test runner, read on.
<!-- TOC -->
- [Release notes](./release-notes.md)
@ -120,186 +120,3 @@ Only Ubuntu 18.04 and Ubuntu 20.04 are officially supported.
See also in the [Command Line Interface](./cli.md#install-system-dependencies)
which has a command to install all necessary dependencies automatically for Ubuntu
LTS releases.
## 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
```bash js
npm i -D playwright
```
These browsers will take a few hundred megabytes of disk space when installed:
```bash
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:
```bash js
# Linux/macOS
PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers npm i -D playwright
# Windows with cmd.exe
set PLAYWRIGHT_BROWSERS_PATH=%USERPROFILE%\pw-browsers
npm i -D playwright
# Windows with PowerShell
$env:PLAYWRIGHT_BROWSERS_PATH="$env:USERPROFILE\pw-browsers"
npm i -D playwright
```
When running Playwright scripts, ask it to search for browsers in a shared location.
```bash js
# Linux/macOS
PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers node playwright-script.js
# Windows with cmd.exe
set PLAYWRIGHT_BROWSERS_PATH=%USERPROFILE%\pw-browsers
node playwright-script.js
# Windows with PowerShell
$env:PLAYWRIGHT_BROWSERS_PATH="$env:USERPROFILE\pw-browsers"
node playwright-script.js
```
Or you can opt into the hermetic install and place binaries in the local folder:
```bash js
# Linux/macOS
# Places binaries to node_modules/playwright
PLAYWRIGHT_BROWSERS_PATH=0 npm i -D playwright
# Windows with cmd.exe
# Places binaries to node_modules\playwright
set PLAYWRIGHT_BROWSERS_PATH=0
npm i -D playwright
# Windows with PowerShell
# Places binaries to node_modules\playwright
$env:PLAYWRIGHT_BROWSERS_PATH=0
npm i -D playwright
```
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`.
:::
### Install behind a firewall or a proxy
By default, Playwright downloads browsers from Microsoft's CDN.
Sometimes companies maintain an internal proxy that blocks direct access to the public
resources. In this case, Playwright can be configured to download browsers via a proxy server.
```bash js
# Linux/macOS
HTTPS_PROXY=https://192.0.2.1 npm i -D playwright
# Windows with cmd.exe
set HTTPS_PROXY=https://192.0.2.1
npm i -D playwright
# Windows with PowerShell
$env:HTTPS_PROXY="https://192.0.2.1"
npm i -D playwright
```
### Download from artifact repository
By default, Playwright downloads browsers from Microsoft's CDN.
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.
```bash js
# Linux/macOS
PLAYWRIGHT_DOWNLOAD_HOST=192.0.2.1 npm i -D playwright
# Windows with cmd.exe
set PLAYWRIGHT_DOWNLOAD_HOST=192.0.2.1
npm i -D playwright
# Windows with PowerShell
$env:PLAYWRIGHT_DOWNLOAD_HOST="192.0.2.1"
npm i -D playwright
```
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`.
```bash js
# Linux/macOS
PLAYWRIGHT_FIREFOX_DOWNLOAD_HOST=203.0.113.3 PLAYWRIGHT_DOWNLOAD_HOST=192.0.2.1 npm i -D playwright
```
### 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.
```bash js
# Linux/macOS
PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 npm i -D playwright
# Windows with cmd.exe
set PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1
npm i -D playwright
# Windows with PowerShell
$env:PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1
npm i -D playwright
```
### Download single browser binary
Playwright ships three packages that bundle only a single browser:
- [`playwright-chromium`](https://www.npmjs.com/package/playwright-chromium)
- [`playwright-webkit`](https://www.npmjs.com/package/playwright-webkit)
- [`playwright-firefox`](https://www.npmjs.com/package/playwright-firefox)
:::note
All configuration environment variables also apply to these packages.
:::
Using these packages is as easy as using a regular Playwright:
Install a specific package
```bash
npm i -D playwright-webkit
```
Require package
```js
// Notice a proper package name in require
const { webkit } = require('playwright-webkit');
(async () => {
const browser = await webkit.launch();
// ...
})();
```
### Stale browser removal
Playwright keeps track of the clients that use its browsers. When there are no more clients that require particular
version of the browser, that version is deleted from the system. That way you can safely use Playwright instances of
different versions and at the same time, you don't waste disk space for the browsers that are no longer in use.
To opt-out from the unused browser removal, you can set the `PLAYWRIGHT_SKIP_BROWSER_GC=1` environment variable.

293
docs/src/test-assertions-js.md Normal file
View file

@ -0,0 +1,293 @@
---
id: test-assertions
title: "Assertions"
---
Playwright Test uses [expect](https://jestjs.io/docs/expect) library for test assertions. This library provides
a lot of matchers like `toEqual`, `toContain`, `toMatch`, `toMatchSnapshot` and many more:
```js
expect(success).toBeTruthy();
```
Playwright also extends it with convenience async matchers that will wait until
the expected condition is met.
<!-- TOC -->
## Matching
Consider the following example:
```js
await expect(page.locator('.status')).toHaveText('Submitted');
```
Playwright Test will be re-testing the node with the selector `.status` until fetched Node has the `"Submitted"`
text. It will be re-fetching the node and checking it over and over, until the condition is met or until the timeout is
reached. You can either pass this timeout or configure it once via the [`property: Fixtures.actionTimeout`] value
in test config.
By default, the timeout for assertions is not set, so it'll wait forever, until the whole test times out.
## expect(locator).toBeChecked
- `options`
- `timeout`: <[number]> Time to retry assertion for, defaults to [`property: Fixtures.actionTimeout`].
Ensures [Locator] points to the checked input.
```js
const locator = await page.locator('.subscribe');
await expect(locator).toBeChecked();
```
## expect(locator).toBeDisabled
- `options`
- `timeout`: <[number]> Time to retry assertion for, defaults to [`property: Fixtures.actionTimeout`].
Ensures [Locator] points to a disabled element.
```js
const locator = await page.locator('button.submit');
await expect(locator).toBeDisabled();
```
## expect(locator).toBeEditable
- `options`
- `timeout`: <[number]> Time to retry assertion for, defaults to [`property: Fixtures.actionTimeout`].
Ensures [Locator] points to an editable element.
```js
const locator = await page.locator('input');
await expect(locator).toBeEditable();
```
## expect(locator).toBeEmpty
- `options`
- `timeout`: <[number]> Time to retry assertion for, defaults to [`property: Fixtures.actionTimeout`].
Ensures [Locator] points to an empty editable element or to a DOM node that has no text.
```js
const locator = await page.locator('div.warning');
await expect(locator).toBeEmpty();
```
## expect(locator).toBeEnabled
- `options`
- `timeout`: <[number]> Time to retry assertion for, defaults to [`property: Fixtures.actionTimeout`].
Ensures [Locator] points to an enabled element.
```js
const locator = await page.locator('button.submit');
await expect(locator).toBeEnabled();
```
## expect(locator).toBeFocused
- `options`
- `timeout`: <[number]> Time to retry assertion for, defaults to [`property: Fixtures.actionTimeout`].
Ensures [Locator] points to a focused DOM node.
```js
const locator = await page.locator('input');
await expect(locator).toBeFocused();
```
## expect(locator).toBeHidden
- `options`
- `timeout`: <[number]> Time to retry assertion for, defaults to [`property: Fixtures.actionTimeout`].
Ensures [Locator] points to a hidden DOM node, which is the opposite of [visible](./actionability.md#visible).
```js
const locator = await page.locator('.my-element');
await expect(locator).toBeHidden();
```
## expect(locator).toBeSelected
- `options`
- `timeout`: <[number]> Time to retry assertion for, defaults to [`property: Fixtures.actionTimeout`].
Ensures [Locator] points to a selected option.
```js
const locator = await page.locator('option[value=Three]');
await expect(locator).toBeSelected();
```
## expect(locator).toBeVisible
- `options`
- `timeout`: <[number]> Time to retry assertion for, defaults to [`property: Fixtures.actionTimeout`].
Ensures [Locator] points to a [visible](./actionability.md#visible) DOM node.
```js
const locator = await page.locator('.my-element');
await expect(locator).toBeVisible();
```
## expect(locator).toContainText(text, options?)
- `text`: <[string]> Text to look for inside the element
- `options`
- `timeout`: <[number]> Time to wait for, defaults to [`property: Fixtures.actionTimeout`].
- `useInnerText`: <[boolean]> Whether to use `element.innerText` instead of `element.textContent` when retrieving DOM node text.
Ensures [Locator] points to a selected option.
```js
const locator = await page.locator('.title');
await expect(locator).toContainText('substring');
```
## expect(locator).toHaveAttr(name, value)
- `name`: <[string]> Attribute name
- `value`: <[string]|[RegExp]> Attribute value
- `options`
- `timeout`: <[number]> Time to retry assertion for, defaults to [`property: Fixtures.actionTimeout`].
Ensures [Locator] points to an element with given attribute.
```js
const locator = await page.locator('input');
await expect(locator).toHaveAttr('type', 'text');
```
## expect(locator).toHaveClass(expected)
- `expected`: <[string] | [RegExp] | [Array]<[string]>>
- `options`
- `timeout`: <[number]> Time to retry assertion for, defaults to [`property: Fixtures.actionTimeout`].
Ensures [Locator] points to an element with given CSS class.
```js
const locator = await page.locator('#component');
await expect(locator).toHaveClass(/selected/);
```
Note that if array is passed as an expected value, entire lists can be asserted:
```js
const locator = await page.locator('list > #component');
await expect(locator).toHaveClass(['component', 'component selected', 'component']);
```
## expect(locator).toHaveCount(count)
- `count`: <[number]>
- `options`
- `timeout`: <[number]> Time to retry assertion for, defaults to [`property: Fixtures.actionTimeout`].
Ensures [Locator] resolves to an exact number of DOM nodes.
```js
const list = await page.locator('list > #component');
await expect(list).toHaveCount(3);
```
## expect(locator).toHaveCSS(name, value)
- `name`: <[string]> CSS property name
- `value`: <[string]|[RegExp]> CSS property value
- `options`
- `timeout`: <[number]> Time to retry assertion for, defaults to [`property: Fixtures.actionTimeout`].
Ensures [Locator] resolves to an element with the given computed CSS style
```js
const locator = await page.locator('button');
await expect(locator).toHaveCSS('display', 'flex');
```
## expect(locator).toHaveData(name, value)
- `name`: <[string]> Data attribute name
- `value`: <[string]|[RegExp]> Data value
- `options`
- `timeout`: <[number]> Time to retry assertion for, defaults to [`property: Fixtures.actionTimeout`].
Ensures [Locator] points to an element with given data binding.
```js
const locator = await page.locator('input');
await expect(locator).toHaveData('mydata', 'myvalue');
```
## expect(locator).toHaveId(id)
- `id`: <[string]> Element id
- `options`
- `timeout`: <[number]> Time to retry assertion for, defaults to [`property: Fixtures.actionTimeout`].
Ensures [Locator] points to an element with the given DOM Node ID.
```js
const locator = await page.locator('input');
await expect(locator).toHaveId('lastname');
```
## expect(locator).toHaveProp(name, value)
- `name`: <[string]> Property name
- `value`: <[any]> Property value
- `options`
- `timeout`: <[number]> Time to retry assertion for, defaults to [`property: Fixtures.actionTimeout`].
Ensures [Locator] points to an element with given JavaScript property. Note that this property can be
of a primitive type as well as a plain serializable JavaScript object.
```js
const locator = await page.locator('.component');
await expect(locator).toHaveProp('loaded', true);
```
## expect(locator).toHaveText(expected, options)
- `expected`: <[string] | [RegExp] | [Array]<[string]>>
- `options`
- `timeout`: <[number]> Time to retry assertion for, defaults to [`property: Fixtures.actionTimeout`].
- `useInnerText`: <[boolean]> Whether to use `element.innerText` instead of `element.textContent` when retrieving DOM node text.
Ensures [Locator] points to an element with the given text. You can use regular expressions for the value as well.
```js
const locator = await page.locator('.title');
await expect(locator).toHaveText(/Welcome, .*/);
```
Note that if array is passed as an expected value, entire lists can be asserted:
```js
const locator = await page.locator('list > #component');
await expect(locator).toHaveText(['Text 1', 'Text 2', 'Text 3']);
```
## expect(page).toHaveTitle(title)
- `title`: <[string] | [RegExp]>>
- `options`
- `timeout`: <[number]> Time to retry assertion for, defaults to [`property: Fixtures.actionTimeout`].
Ensures page has a given title.
```js
await expect(page).toHaveTitle(/.*checkout/);
```
## expect(page).toHaveURL(url)
- `url`: <[string] | [RegExp]>>
- `options`
- `timeout`: <[number]> Time to retry assertion for, defaults to [`property: Fixtures.actionTimeout`].
Ensures page is navigated to a given URL.
```js
await expect(page).toHaveURL(/.*checkout/);
```
## expect(locator).toHaveValue(value)
- `value`: <[string] | [RegExp]>>
- `options`
- `timeout`: <[number]> Time to retry assertion for, defaults to [`property: Fixtures.actionTimeout`].
Ensures [Locator] points to an element with the given input value. You can use regular expressions for the value as well.
```js
const locator = await page.locator('input[type=number]');
await expect(locator).toHaveValue(/[0-9]/);
```

142
docs/src/test-install-js.md
View file

@ -1,142 +0,0 @@
---
id: test-install
title: "Advanced: installing browsers"
---
<!-- TOC -->
## Installing browser binaries
Each version of Playwright Test needs specific versions of browser binaries to operate. Playwright Test includes [Command Line Interface](./cli.md) that can download these binaries. By default, Playwright Test 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
```bash
# Add dependency
npm i -D @playwright/test
# Download browser binaries
npx playwright install
```
These browsers will take a few hundred megabytes of disk space when installed:
```bash
du -hs ~/Library/Caches/ms-playwright/*
281M chromium-XXXXXX
187M firefox-XXXX
180M webkit-XXXX
```
## Installing a single browser binary
Playwright Test downloads Chromium, Firefox and WebKit browsers by default. To install a specific browser, pass it as an argument.
```bash
npx playwright install webkit
```
## Managing browser binaries
You can override default installation behavior using environment variables. When installing browsers, ask Playwright Test to download them into a specific location.
```bash
# Linux/macOS
PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers npx playwright install
# Windows with cmd.exe
set PLAYWRIGHT_BROWSERS_PATH=%USERPROFILE%\pw-browsers
npx playwright install
# Windows with PowerShell
$env:PLAYWRIGHT_BROWSERS_PATH="$env:USERPROFILE\pw-browsers"
npx playwright install
```
When running tests, ask it to search for browsers in a shared location.
```bash
# Linux/macOS
PLAYWRIGHT_BROWSERS_PATH=$HOME/pw-browsers npx playwright test
# Windows with cmd.exe
set PLAYWRIGHT_BROWSERS_PATH=%USERPROFILE%\pw-browsers
npx playwright test
# Windows with PowerShell
$env:PLAYWRIGHT_BROWSERS_PATH="$env:USERPROFILE\pw-browsers"
npx playwright test
```
Or you can opt into the hermetic install and place binaries in the local folder:
```bash
# Linux/macOS
# Places binaries to node_modules/@playwright/test
PLAYWRIGHT_BROWSERS_PATH=0 npx playwright install
# Windows with cmd.exe
# Places binaries to node_modules\@playwright\test
set PLAYWRIGHT_BROWSERS_PATH=0
npx playwright install
# Windows with PowerShell
# Places binaries to node_modules\@playwright\test
$env:PLAYWRIGHT_BROWSERS_PATH=0
npx playwright install
```
Playwright Test keeps track of packages that need those browsers and will garbage collect them as you update Playwright Test to the newer versions.
## Install behind a firewall or a proxy
By default, Playwright Test downloads browsers from Microsoft CDN.
Sometimes companies maintain an internal proxy that blocks direct access to the public
resources. In this case, Playwright can be configured to download browsers via a proxy server.
```bash
# Linux/macOS
HTTPS_PROXY=https://192.0.2.1 npx playwright install
# Windows with cmd.exe
set HTTPS_PROXY=https://192.0.2.1
npx playwright install
# Windows with PowerShell
$env:HTTPS_PROXY="https://192.0.2.1"
npx playwright install
```
## Download from artifact repository
By default, Playwright downloads browsers from Microsoft CDN.
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.
```bash
# Linux/macOS
PLAYWRIGHT_DOWNLOAD_HOST=192.0.2.1 npx playwright install
# Windows with cmd.exe
set PLAYWRIGHT_DOWNLOAD_HOST=192.0.2.1
npx playwright install
# Windows with PowerShell
$env:PLAYWRIGHT_DOWNLOAD_HOST="192.0.2.1"
npx playwright install
```
It is also possible to choose a per-browser download host using `PLAYWRIGHT_CHROMIUM_DOWNLOAD_HOST`, `PLAYWRIGHT_FIREFOX_DOWNLOAD_HOST` and `PLAYWRIGHT_WEBKIT_DOWNLOAD_HOST` env variables that
take precedence over `PLAYWRIGHT_DOWNLOAD_HOST`.
## Stale browser removal
Playwright Test keeps track of the clients that use its browsers. When there are no more clients that require particular
version of the browser, that version is deleted from the system. That way you can safely use Playwright Test instances of
different versions and at the same time, you don't waste disk space for the browsers that are no longer in use.
To opt-out from the unused browser removal, you can set the `PLAYWRIGHT_SKIP_BROWSER_GC=1` environment variable.

2
docs/src/test-reporter-api/class-reporter.md
View file

@ -3,7 +3,7 @@
Test runner notifies the reporter about various events during test execution. All methods of the reporter are optional.
You can create a custom reporter my implementing a class with some of the reporter methods. Make sure to export this class as default.
You can create a custom reporter by implementing a class with some of the reporter methods. Make sure to export this class as default.
```js js-flavor=js
// my-awesome-reporter.js

94
docs/src/test-reporters-js.md
View file

@ -311,3 +311,97 @@ const config: PlaywrightTestConfig = {
};
export default config;
```
## Custom reporters
You can create a custom reporter by implementing a class with some of the reporter methods. Learn more about the [Reporter] API.
```js js-flavor=js
// my-awesome-reporter.js
// @ts-check
/** @implements {import('@playwright/test/reporter').Reporter} */
class MyReporter {
onBegin(config, suite) {
console.log(`Starting the run with ${suite.allTests().length} tests`);
}
onTestBegin(test) {
console.log(`Starting test ${test.title}`);
}
onTestEnd(test, result) {
console.log(`Finished test ${test.title}: ${result.status}`);
}
onEnd(result) {
console.log(`Finished the run: ${result.status}`);
}
}
module.exports = MyReporter;
```
```js js-flavor=ts
// playwright.config.ts
import { Reporter } from '@playwright/test/reporter';
class MyReporter implements Reporter {
onBegin(config, suite) {
console.log(`Starting the run with ${suite.allTests().length} tests`);
}
onTestBegin(test) {
console.log(`Starting test ${test.title}`);
}
onTestEnd(test, result) {
console.log(`Finished test ${test.title}: ${result.status}`);
}
onEnd(result) {
console.log(`Finished the run: ${result.status}`);
}
}
export default MyReporter;
```
Now use this reporter with [`property: TestConfig.reporter`].
```js js-flavor=js
// playwright.config.js
// @ts-check
/** @type {import('@playwright/test').PlaywrightTestConfig} */
const config = {
reporter: './my-awesome-reporter.js',
};
module.exports = config;
```
```js js-flavor=ts
// playwright.config.ts
import { PlaywrightTestConfig } from '@playwright/test';
const config: PlaywrightTestConfig = {
reporter: './my-awesome-reporter.ts',
};
export default config;
```
## Third party showcase
- Allure reporter
```bash
# Install
npm i -D experimental-allure-playwright
# Run tests
npx playwright test --reporter=line,experimental-allure-playwright
# Generate report
allure generate ./allure-result --clean && allure open ./allure-report
```

27
docs/src/why-playwright.md
View file

@ -3,7 +3,7 @@ id: why-playwright
title: "Why Playwright?"
---
Playwright enables fast, reliable and capable automation across all modern browsers. This guide covers those key differentiators to help you decide on the right tool for your automated tests.
Playwright enables fast, reliable and capable testing and automation across all modern browsers. This guide covers those key differentiators to help you decide on the right tool for your automated tests.
<!-- TOC -->
- [Release notes](./release-notes.md)
@ -22,7 +22,9 @@ Playwright enables fast, reliable and capable automation across all modern brows
* **Timeout-free automation**. Playwright receives browser signals, like network requests, page navigations and page load events to eliminate the need for sleep timeouts that cause flakiness.
* **Lean parallelization with browser contexts**. Reuse a single browser instance for multiple parallelized, isolated execution environments with [browser contexts](./core-concepts.md).
* **Lean parallelization with Playwright Test Runner**. Zero configuration [parallel tests](./test-parallel.md).
* **Fast isolation with browser contexts**. Reuse a single browser instance for multiple isolated execution environments with [browser contexts](./core-concepts.md).
* **Resilient element selectors**. Playwright can rely on user-facing strings, like text content and accessibility labels to [select elements](./selectors.md). These strings are more resilient than selectors tightly-coupled to the DOM structure.
@ -35,27 +37,8 @@ Playwright enables fast, reliable and capable automation across all modern brows
* **Capabilities to cover all scenarios**. Support for [file downloads](./downloads.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**. Installing Playwright auto-downloads browser dependencies for your team to be onboarded quickly.
```bash js
npm i playwright
```
```bash python
pip install playwright
playwright install
```
* **TypeScript support**. Playwright ships with built-in types for auto-completion and other benefits.
* **Debugging tools**. Playwright works with the [editor debugger and browser developer tools](./debug.md) to pause execution and inspect the web page.
* **Language bindings**. Playwright is available for [Node.js](https://github.com/microsoft/playwright) [Python](https://github.com/microsoft/playwright-python), [.NET](https://github.com/microsoft/playwright-dotnet) and
[Java](https://github.com/microsoft/playwright-java). Learn more about [supported languages](./languages.md).
* **Deploy tests to CI**. First-party [Docker image](./docker.md) and [GitHub Actions](./ci.md#github-actions) support to deploy tests to [your preferred CI/CD provider](./ci.md).
## Limitations
* **Legacy Edge and IE11 support**. Playwright does not support legacy Microsoft Edge or IE11 ([deprecation notice](https://techcommunity.microsoft.com/t5/microsoft-365-blog/microsoft-365-apps-say-farewell-to-internet-explorer-11-and/ba-p/1591666)). The new Microsoft Edge (on Chromium) is supported.
* **Test on real mobile devices**: Playwright uses desktop browsers to emulate mobile devices. There is experimental Android support available see [here](https://playwright.dev/docs/mobile). If you are interested in iOS, please [upvote this issue](https://github.com/microsoft/playwright/issues/1122).
* **Test on real mobile devices**: Playwright uses desktop browsers to emulate mobile devices. There is experimental [Android] support available. If you are interested in iOS, please [upvote this issue](https://github.com/microsoft/playwright/issues/1122).

2
src/test/matchers/matchers.ts
View file

@ -212,7 +212,7 @@ export function toHaveProp(
this: ReturnType<Expect['getState']>,
locator: Locator,
name: string,
expected: number,
expected: any,
options?: { timeout?: number },
) {
return toEqual.call(this, 'toHaveProp', locator, 'Locator', async timeout => {

2
types/testReporter.d.ts vendored
View file

@ -265,7 +265,7 @@ export interface FullResult {
/**
* Test runner notifies the reporter about various events during test execution. All methods of the reporter are optional.
*
* You can create a custom reporter my implementing a class with some of the reporter methods. Make sure to export this
* You can create a custom reporter by implementing a class with some of the reporter methods. Make sure to export this
* class as default.
*
* ```js js-flavor=js

1
types/types.d.ts vendored
View file

@ -9156,7 +9156,6 @@ export {};
/**
* Playwright has **experimental** support for Android automation. This includes Chrome for Android and Android WebView.
* You can access android namespace via:
*
* *Requirements*
* - Android device or AVD Emulator.