docs(ci): update docs for caching and troubleshooting (#2176)
This commit is contained in:
Arjun Attam
GitHub
Родитель
c5b0baacd1
Коммит
2510edc394
137
docs/ci.md
137
docs/ci.md
|
|
@ -3,17 +3,24 @@
|
|||
Playwright tests can be executed to run on your CI environments. To simplify this, we have created sample configurations for common CI providers that can be used to bootstrap your setup.
|
||||
|
||||
<!-- GEN:toc -->
|
||||
- [GitHub Actions](#github-actions)
|
||||
- [Docker](#docker)
|
||||
- [Azure Pipelines](#azure-pipelines)
|
||||
- [Travis CI](#travis-ci)
|
||||
- [CircleCI](#circleci)
|
||||
- [AppVeyor](#appveyor)
|
||||
- [CI configurations](#ci-configurations)
|
||||
* [GitHub Actions](#github-actions)
|
||||
* [Docker](#docker)
|
||||
- [Tips](#tips)
|
||||
* [Azure Pipelines](#azure-pipelines)
|
||||
* [Travis CI](#travis-ci)
|
||||
- [Tips](#tips-1)
|
||||
* [CircleCI](#circleci)
|
||||
* [AppVeyor](#appveyor)
|
||||
- [Debugging browser launches](#debugging-browser-launches)
|
||||
- [Caching browsers](#caching-browsers)
|
||||
<!-- GEN:stop -->
|
||||
|
||||
Broadly, configuration on CI involves **ensuring system dependencies** are in place, **installing Playwright and browsers** (typically with `npm install`), and **running tests** (typically with `npm test`). Windows and macOS build agents do not require any additional system dependencies. Linux build agents can require additional dependencies, depending on the Linux distribution.
|
||||
|
||||
## GitHub Actions
|
||||
## CI configurations
|
||||
|
||||
### GitHub Actions
|
||||
|
||||
The [Playwright GitHub Action](https://github.com/microsoft/playwright-github-action) can be used to run Playwright tests on GitHub Actions.
|
||||
|
||||
|
|
@ -26,24 +33,126 @@ steps:
|
|||
|
||||
We run [our tests](/.github/workflows/tests.yml) on GitHub Actions, across a matrix of 3 platforms (Windows, Linux, macOS) and 3 browsers (Chromium, Firefox, WebKit).
|
||||
|
||||
## Docker
|
||||
### Docker
|
||||
|
||||
We have a [pre-built Docker image](docker/README.md) which can either be used directly, or as a reference to update your existing Docker definitions.
|
||||
|
||||
## Azure Pipelines
|
||||
#### Tips
|
||||
1. By default, Docker runs a container with a `/dev/shm` shared memory space 64MB.
|
||||
This is [typically too small](https://github.com/c0b/chrome-in-docker/issues/1) for Chromium
|
||||
and will cause Chromium to crash when rendering large pages. To fix, run the container with
|
||||
`docker run --shm-size=1gb` to increase the size of `/dev/shm`. Since Chromium 65, this is no
|
||||
longer necessary. Instead, launch the browser with the `--disable-dev-shm-usage` flag:
|
||||
|
||||
```js
|
||||
const browser = await playwright.chromium.launch({
|
||||
args: ['--disable-dev-shm-usage']
|
||||
});
|
||||
```
|
||||
|
||||
This will write shared memory files into `/tmp` instead of `/dev/shm`. See
|
||||
[crbug.com/736452](https://bugs.chromium.org/p/chromium/issues/detail?id=736452) for more details.
|
||||
1. Using `--ipc=host` is also recommended when using Chromium—without it Chromium can run out of memory
|
||||
and crash. Learn more about this option in [Docker docs](https://docs.docker.com/engine/reference/run/#ipc-settings---ipc).
|
||||
1. Seeing other weird errors when launching Chromium? Try running your container
|
||||
with `docker run --cap-add=SYS_ADMIN` when developing locally. Since the Dockerfile
|
||||
adds a `pwuser` user as a non-privileged user, it may not have all the necessary privileges.
|
||||
1. [dumb-init](https://github.com/Yelp/dumb-init) is worth checking out if you're
|
||||
experiencing a lot of zombies Chromium processes sticking around. There's special
|
||||
treatment for processes with PID=1, which makes it hard to terminate Chromium
|
||||
properly in some cases (e.g. in Docker).
|
||||
|
||||
### Azure Pipelines
|
||||
|
||||
For Windows or macOS agents, no additional configuration required, just install Playwright and run your tests.
|
||||
|
||||
For Linux agents, refer to [our Docker setup](docker/README.md) to see additional dependencies that need to be installed.
|
||||
|
||||
## Travis CI
|
||||
### Travis CI
|
||||
|
||||
We run our tests on Travis CI over a Linux agent (Ubuntu 18.04). Use our [Travis configuration](/.travis.yml) to see list of additional dependencies to be installed.
|
||||
|
||||
## CircleCI
|
||||
#### Tips
|
||||
- [User namespace cloning](http://man7.org/linux/man-pages/man7/user_namespaces.7.html) should be enabled to support proper sandboxing
|
||||
- [xvfb](https://en.wikipedia.org/wiki/Xvfb) should be launched in order to run Chromium in non-headless mode (e.g. to test Chrome Extensions)
|
||||
|
||||
We run our tests on CircleCI, with our [pre-built Docker image](docker/README.md). Use our [CircleCI configuration](/.circleci/config.yml) to create your own.
|
||||
To sum up, your `.travis.yml` might look like this:
|
||||
|
||||
## AppVeyor
|
||||
```yml
|
||||
language: node_js
|
||||
dist: bionic
|
||||
addons:
|
||||
apt:
|
||||
packages:
|
||||
# These are required to run webkit
|
||||
- libwoff1
|
||||
- libopus0
|
||||
- libwebp6
|
||||
- libwebpdemux2
|
||||
- libenchant1c2a
|
||||
- libgudev-1.0-0
|
||||
- libsecret-1-0
|
||||
- libhyphen0
|
||||
- libgdk-pixbuf2.0-0
|
||||
- libegl1
|
||||
- libgles2
|
||||
- libevent-2.1-6
|
||||
- libnotify4
|
||||
- libxslt1.1
|
||||
- libvpx5
|
||||
# This is required to run chromium
|
||||
- libgbm1
|
||||
|
||||
We run our tests on Windows agents in AppVeyor. Use our [AppVeyor configuration](/.appveyor.yml) to create your own.
|
||||
# allow headful tests
|
||||
before_install:
|
||||
# Enable user namespace cloning
|
||||
- "sysctl kernel.unprivileged_userns_clone=1"
|
||||
# Launch XVFB
|
||||
- "export DISPLAY=:99.0"
|
||||
- "sh -e /etc/init.d/xvfb start"
|
||||
```
|
||||
|
||||
### CircleCI
|
||||
|
||||
We run our tests on CircleCI, with our [pre-built Docker image](docker/README.md). Use our [CircleCI configuration](/.circleci/config.yml) to create your own. Running Playwright smoothly on CircleCI requires the following steps:
|
||||
|
||||
1. Use the pre-built [Docker image](docker/README.md) in your config like so:
|
||||
|
||||
```yaml
|
||||
docker:
|
||||
- image: aslushnikov/playwright:bionic
|
||||
environment:
|
||||
NODE_ENV: development # Needed if playwright is in `devDependencies`
|
||||
```
|
||||
|
||||
1. If you’re using Playwright through Jest, then you may encounter an error spawning child processes:
|
||||
|
||||
```
|
||||
[00:00.0] jest args: --e2e --spec --max-workers=36
|
||||
Error: spawn ENOMEM
|
||||
at ChildProcess.spawn (internal/child_process.js:394:11)
|
||||
```
|
||||
|
||||
This is likely caused by Jest autodetecting the number of processes on the entire machine (`36`) rather than the number allowed to your container (`2`). To fix this, set `jest --maxWorkers=2` in your test command.
|
||||
|
||||
### AppVeyor
|
||||
|
||||
We run our tests on Windows agents in AppVeyor. Use our [AppVeyor configuration](/.appveyor.yml) to create your own.
|
||||
|
||||
## Debugging browser launches
|
||||
|
||||
Playwright supports the `DEBUG` environment variable to output debug logs during execution. Setting it to `pw:browser*` is helpful while debugging `Error: Failed to launch browser` errors.
|
||||
|
||||
```
|
||||
DEBUG=pw:browser* npm run test
|
||||
```
|
||||
|
||||
## Caching browsers
|
||||
|
||||
By default, Playwright installs browser binaries in the following directories. This behavior can be [customized with environment variables](installation.md).
|
||||
|
||||
- `%USERPROFILE%\AppData\Local\ms-playwright` on Windows
|
||||
- `~/Library/Caches/ms-playwright` on MacOS
|
||||
- `~/.cache/ms-playwright` on Linux
|
||||
|
||||
These locations are not covered by typical CI configurations, which cache the project `node_modules` or the [npm-cache directory](https://docs.npmjs.com/cli-commands/cache.html). To cache the browser binaries between CI runs, cache this location in your CI configuration, against a hash of the Playwright version.
|
||||
|
|
|
|||
|
|
@ -8,14 +8,15 @@ Along with a test runner Playwright can be used to automate user interactions to
|
|||
validate and test web applications. The Playwright API enables this through
|
||||
the following primitives.
|
||||
|
||||
#### Contents
|
||||
- [Browser](#browser)
|
||||
- [Browser contexts](#browser-contexts)
|
||||
- [Pages and frames](#pages-and-frames)
|
||||
- [Selectors](#selectors)
|
||||
- [Auto-waiting](#auto-waiting)
|
||||
- [Node.js and browser execution contexts](#nodejs-and-browser-execution-contexts)
|
||||
- [Object & element handles](#object--element-handles)
|
||||
<!-- GEN:toc-top-level -->
|
||||
- [Browser](#browser)
|
||||
- [Browser contexts](#browser-contexts)
|
||||
- [Pages and frames](#pages-and-frames)
|
||||
- [Selectors](#selectors)
|
||||
- [Auto-waiting](#auto-waiting)
|
||||
- [Node.js and browser execution contexts](#nodejs-and-browser-execution-contexts)
|
||||
- [Object & element handles](#object--element-handles)
|
||||
<!-- GEN:stop -->
|
||||
|
||||
<br/>
|
||||
|
||||
|
|
|
|||
|
|
@ -9,13 +9,14 @@ Playwright allows overriding various parameters of the device where the browser
|
|||
|
||||
Most of these parameters are configured during the browser context construction, but some of them such as viewport size can be changed for individual pages.
|
||||
|
||||
#### Contents
|
||||
<!-- GEN:toc-top-level -->
|
||||
- [User agent](#user-agent)
|
||||
- [Viewport, color scheme](#viewport-color-scheme)
|
||||
- [Devices](#devices)
|
||||
- [Locale & Timezone](#locale--timezone)
|
||||
- [Locale & timezone](#locale--timezone)
|
||||
- [Permissions](#permissions)
|
||||
- [Geolocation](#geolocation)
|
||||
<!-- GEN:stop -->
|
||||
|
||||
<br/>
|
||||
|
||||
|
|
|
|||
|
|
@ -1,8 +1,8 @@
|
|||
# Extensibility
|
||||
|
||||
#### Contents
|
||||
|
||||
<!-- GEN:toc-top-level -->
|
||||
- [Custom selector engines](#custom-selector-engines)
|
||||
<!-- GEN:stop -->
|
||||
|
||||
## Custom selector engines
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
# Input
|
||||
|
||||
#### Contents
|
||||
<!-- GEN:toc-top-level -->
|
||||
- [Text input](#text-input)
|
||||
- [Checkboxes](#checkboxes)
|
||||
- [Select options](#select-options)
|
||||
|
|
@ -9,6 +9,7 @@
|
|||
- [Keys and shortcuts](#keys-and-shortcuts)
|
||||
- [Upload files](#upload-files)
|
||||
- [Focus element](#focus-element)
|
||||
<!-- GEN:stop -->
|
||||
|
||||
<br/>
|
||||
|
||||
|
|
|
|||
|
|
@ -2,6 +2,13 @@
|
|||
|
||||
Playwright logically splits the process of showing a new document in the page into **navigation** and **loading**.
|
||||
|
||||
<!-- GEN:toc-top-level -->
|
||||
- [Navigation](#navigation)
|
||||
- [Loading](#loading)
|
||||
- [Common scenarios](#common-scenarios)
|
||||
- [Loading a popup](#loading-a-popup)
|
||||
<!-- GEN:stop -->
|
||||
|
||||
## Navigation
|
||||
|
||||
Page navigation can be either initiated by the Playwright call:
|
||||
|
|
|
|||
|
|
@ -4,13 +4,14 @@ Playwright provides APIs to **monitor** and **modify** network traffic, both HTT
|
|||
Any requests that page does, including [XHRs](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest) and
|
||||
[fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) requests, can be tracked, modified and handled.
|
||||
|
||||
#### Contents
|
||||
- [HTTP Authentication](#http-authentication)
|
||||
- [Handle file downloads](#handle-file-downloads)
|
||||
- [Network events](#network-events)
|
||||
- [Handle requests](#handle-requests)
|
||||
- [Modify requests](#modify-requests)
|
||||
- [Abort requests](#abort-requests)
|
||||
<!-- GEN:toc-top-level -->
|
||||
- [HTTP Authentication](#http-authentication)
|
||||
- [Handle file downloads](#handle-file-downloads)
|
||||
- [Network events](#network-events)
|
||||
- [Handle requests](#handle-requests)
|
||||
- [Modify requests](#modify-requests)
|
||||
- [Abort requests](#abort-requests)
|
||||
<!-- GEN:stop -->
|
||||
|
||||
<br/>
|
||||
|
||||
|
|
|
|||
|
|
@ -4,6 +4,12 @@ Playwright supports multiple selector engines used to query elements in the web
|
|||
|
||||
Selector can be used to obtain `ElementHandle` (see [page.$()](api.md#pageselector) for example) or shortcut element operations to avoid intermediate handle (see [page.click()](api.md#pageclickselector-options) for example).
|
||||
|
||||
<!-- GEN:toc-top-level -->
|
||||
- [Selector syntax](#selector-syntax)
|
||||
- [Examples](#examples)
|
||||
- [Built-in selector engines](#built-in-selector-engines)
|
||||
<!-- GEN:stop -->
|
||||
|
||||
## Selector syntax
|
||||
|
||||
Selector is a string that consists of one or more clauses separated by `>>` token, e.g. `clause1 >> clause2 >> clause3`. When multiple clauses are present, next one is queried relative to the previous one's result.
|
||||
|
|
|
|||
|
|
@ -11,11 +11,6 @@
|
|||
* [Firefox headless doesn't launch on Linux/WSL](#firefox-headless-doesnt-launch-on-linuxwsl)
|
||||
- [WebKit](#webkit)
|
||||
* [WebKit headless doesn't launch on Linux/WSL](#webkit-headless-doesnt-launch-on-linuxwsl)
|
||||
- [Running Playwright on CI](#running-playwright-on-ci)
|
||||
* [Running Playwright on Travis CI](#running-playwright-on-travis-ci)
|
||||
* [Running Playwright on CircleCI](#running-playwright-on-circleci)
|
||||
* [Running Playwright in Docker](#running-playwright-in-docker)
|
||||
- [Tips](#tips)
|
||||
- [Code transpilation issues](#code-transpilation-issues)
|
||||
- [Node requirements](#node-requirements)
|
||||
* [ReferenceError: URL is not defined](#referenceerror-url-is-not-defined)
|
||||
|
|
@ -203,106 +198,6 @@ machine to check which dependencies are missing. For dependencies on Ubuntu, ple
|
|||
Make sure all the necessary dependencies are installed. You can run `ldd chrome | grep not` on a Linux
|
||||
machine to check which dependencies are missing. For dependencies on Ubuntu, please refer to [Dockerfile](https://github.com/microsoft/playwright/blob/master/docs/docker/Dockerfile.bionic) which is used to run our tests.
|
||||
|
||||
## Running Playwright on CI
|
||||
|
||||
### Running Playwright on Travis CI
|
||||
|
||||
> 👋 We run our tests for Playwright on Travis CI - see our [`.travis.yml`](https://github.com/microsoft/playwright/blob/master/.travis.yml) for reference.
|
||||
|
||||
Tips-n-tricks:
|
||||
- The `libnss3` package must be installed in order to run Chromium on Ubuntu Trusty
|
||||
- [user namespace cloning](http://man7.org/linux/man-pages/man7/user_namespaces.7.html) should be enabled to support
|
||||
proper sandboxing
|
||||
- [xvfb](https://en.wikipedia.org/wiki/Xvfb) should be launched in order to run Chromium in non-headless mode (e.g. to test Chrome Extensions)
|
||||
|
||||
To sum up, your `.travis.yml` might look like this:
|
||||
|
||||
```yml
|
||||
language: node_js
|
||||
dist: trusty
|
||||
addons:
|
||||
apt:
|
||||
packages:
|
||||
# This is required to run new chrome on old trusty
|
||||
- libnss3
|
||||
notifications:
|
||||
email: false
|
||||
cache:
|
||||
directories:
|
||||
- node_modules
|
||||
# allow headful tests
|
||||
before_install:
|
||||
# Enable user namespace cloning
|
||||
- "sysctl kernel.unprivileged_userns_clone=1"
|
||||
# Launch XVFB
|
||||
- "export DISPLAY=:99.0"
|
||||
- "sh -e /etc/init.d/xvfb start"
|
||||
```
|
||||
|
||||
### Running Playwright on CircleCI
|
||||
|
||||
> 👋 We run our tests for Playwright on CircleCI - see our [`.circleci/config.yml`](https://github.com/microsoft/playwright/blob/master/.circleci/config.yml) for reference.
|
||||
|
||||
Running Playwright smoothly on CircleCI requires the following steps:
|
||||
|
||||
1. Start with a [NodeJS
|
||||
image](https://circleci.com/docs/2.0/circleci-images/#nodejs) in your config
|
||||
like so:
|
||||
```yaml
|
||||
docker:
|
||||
- image: circleci/node:12 # Use your desired version
|
||||
environment:
|
||||
NODE_ENV: development # Only needed if playwright is in `devDependencies`
|
||||
```
|
||||
1. Dependencies like `libXtst6` probably need to be installed via `apt-get`,
|
||||
so use the
|
||||
[threetreeslight/puppeteer](https://circleci.com/orbs/registry/orb/threetreeslight/puppeteer)
|
||||
orb
|
||||
([instructions](https://circleci.com/orbs/registry/orb/threetreeslight/puppeteer#quick-start)),
|
||||
or paste parts of its
|
||||
[source](https://circleci.com/orbs/registry/orb/threetreeslight/puppeteer#orb-source)
|
||||
into your own config.
|
||||
1. Lastly, if you’re using Playwright through Jest, then you may encounter an
|
||||
error spawning child processes:
|
||||
```
|
||||
[00:00.0] jest args: --e2e --spec --max-workers=36
|
||||
Error: spawn ENOMEM
|
||||
at ChildProcess.spawn (internal/child_process.js:394:11)
|
||||
```
|
||||
This is likely caused by Jest autodetecting the number of processes on the
|
||||
entire machine (`36`) rather than the number allowed to your container
|
||||
(`2`). To fix this, set `jest --maxWorkers=2` in your test command.
|
||||
|
||||
### Running Playwright in Docker
|
||||
|
||||
> 👋 We run our tests for Playwright in a Docker container - see our [Docker setup](docker/README.md) for reference.
|
||||
|
||||
#### Tips
|
||||
|
||||
By default, Docker runs a container with a `/dev/shm` shared memory space 64MB.
|
||||
This is [typically too small](https://github.com/c0b/chrome-in-docker/issues/1) for Chrome
|
||||
and will cause Chrome to crash when rendering large pages. To fix, run the container with
|
||||
`docker run --shm-size=1gb` to increase the size of `/dev/shm`. Since Chrome 65, this is no
|
||||
longer necessary. Instead, launch the browser with the `--disable-dev-shm-usage` flag:
|
||||
|
||||
```js
|
||||
const browser = await playwright.chromium.launch({
|
||||
args: ['--disable-dev-shm-usage']
|
||||
});
|
||||
```
|
||||
|
||||
This will write shared memory files into `/tmp` instead of `/dev/shm`. See [crbug.com/736452](https://bugs.chromium.org/p/chromium/issues/detail?id=736452) for more details.
|
||||
|
||||
Seeing other weird errors when launching Chrome? Try running your container
|
||||
with `docker run --cap-add=SYS_ADMIN` when developing locally. Since the Dockerfile
|
||||
adds a `pwuser` user as a non-privileged user, it may not have all the necessary privileges.
|
||||
|
||||
[dumb-init](https://github.com/Yelp/dumb-init) is worth checking out if you're
|
||||
experiencing a lot of zombies Chrome processes sticking around. There's special
|
||||
treatment for processes with PID=1, which makes it hard to terminate Chrome
|
||||
properly in some cases (e.g. in Docker).
|
||||
|
||||
|
||||
## Code transpilation issues
|
||||
|
||||
If you are using a JavaScript transpiler like babel or TypeScript, calling `evaluate()` with an async function might not work. This is because while `playwright` uses `Function.prototype.toString()` to serialize functions while transpilers could be changing the output code in such a way it's incompatible with `playwright`.
|
||||
|
|
|
|||
|
|
@ -1,10 +1,11 @@
|
|||
# Scraping and verification
|
||||
|
||||
#### Contents
|
||||
<!-- GEN:toc-top-level -->
|
||||
- [Evaluating JavaScript](#evaluating-javascript)
|
||||
- [Capturing screenshot](#capturing-screenshot)
|
||||
- [Page events](#page-events)
|
||||
- [Handling exceptions](#handling-exceptions)
|
||||
<!-- GEN:stop -->
|
||||
|
||||
<br/>
|
||||
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче