From 6530c18acd9f8fff54cdd5515471351b091f57c1 Mon Sep 17 00:00:00 2001
From: Arjun Attam <arjunattam@gmail.com>
Date: Sat, 13 Jun 2020 13:11:24 -0700
Subject: [PATCH] docs: improvements to ci provider configs (#2565)

---
 docs/ci.md            | 46 ++++++++++++++++++++++++++++++++++++++++++-
 docs/docker/README.md |  4 ++++
 2 files changed, 49 insertions(+), 1 deletion(-)

diff --git a/docs/ci.md b/docs/ci.md
index 3dbfecdf88df7..62f3ead9adba7 100644
--- a/docs/ci.md
+++ b/docs/ci.md
@@ -10,10 +10,12 @@ Playwright tests can be executed to run on your CI environments. To simplify thi
   * [Travis CI](#travis-ci)
   * [CircleCI](#circleci)
   * [AppVeyor](#appveyor)
+  * [Bitbucket Pipelines](#bitbucket-pipelines)
 - [Caching browsers](#caching-browsers)
     - [Exception: `node_modules` are cached](#exception-nodemodules-are-cached)
     - [Directories to cache](#directories-to-cache)
 - [Debugging browser launches](#debugging-browser-launches)
+- [Running headful](#running-headful)
 <!-- 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.
@@ -66,7 +68,18 @@ Suggested configuration
 
 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.
+For Linux agents, you can use [our Docker container](docker/README.md) with Azure Pipelines support for [running containerized jobs](https://docs.microsoft.com/en-us/azure/devops/pipelines/process/container-phases?view=azure-devops). Alternatively, you can refer to the [Dockerfile](docker/README.md) to see additional dependencies that need to be installed on a Ubuntu agent.
+
+```yml
+pool:
+  vmImage: 'ubuntu-18.04'
+
+container: aslushnikov/playwright:bionic
+
+steps:
+- script: npm install
+- script: npm run test
+```
 
 ### Travis CI
 
@@ -146,6 +159,21 @@ We run our tests on CircleCI, with our [pre-built Docker image](docker/README.md
 
 We run our tests on Windows agents in AppVeyor. Use our [AppVeyor configuration](/.appveyor.yml) to create your own.
 
+### Bitbucket Pipelines
+
+Bitbucket Pipelines can use public [Docker images as build environments](https://confluence.atlassian.com/bitbucket/use-docker-images-as-build-environments-792298897.html). To run Playwright tests on Bitbucket, use our public Docker image ([see Dockerfile](docker/README.md)).
+
+```yml
+image: aslushnikov/playwright:bionic
+```
+
+While the Docker image supports sandboxing for Chromium, it does not work in the Bitbucket Pipelines environment. To launch Chromium on Bitbucket Pipelines, use the `--no-sandbox` launch argument.
+
+```js
+const { chromium } = require('playwright');
+const browser = await chromium.launch({ args: ['--no-sandbox'] });
+```
+
 ## Caching browsers
 
 By default, Playwright downloads browser binaries when the Playwright NPM package
@@ -193,3 +221,19 @@ Playwright supports the `DEBUG` environment variable to output debug logs during
 ```
 DEBUG=pw:browser* npm run test
 ```
+
+## Running headful
+
+By default, Playwright launches browsers in headless mode. This can be changed by passing a flag when the browser is launched.
+
+```js
+// Works across chromium, firefox and webkit
+const { chromium } = require('playwright');
+const browser = await chromium.launch({ headless: false });
+```
+
+On Linux agents, headful execution requires [Xvfb](https://en.wikipedia.org/wiki/Xvfb) to be installed. Our [Docker image](docker/README.md) and GitHub Action have Xvfb pre-installed. To run browsers in headful mode with Xvfb, add `xvfb-run` before the Node.js command.
+
+```
+xvfb-run node index.js
+```
diff --git a/docs/docker/README.md b/docs/docker/README.md
index 0024c651f2d49..ad82730571812 100644
--- a/docs/docker/README.md
+++ b/docs/docker/README.md
@@ -20,3 +20,7 @@ $ sudo docker container run -it --rm --ipc=host --security-opt seccomp=chrome.js
 > to run Chrome without sandbox.  
 > Using `--ipc=host` is also recommended when using Chrome. Without it Chrome can run out of memory and crash.  
 > [See the docker documentation for this option here.](https://docs.docker.com/engine/reference/run/#ipc-settings---ipc)
+
+## Playwright on Alpine
+
+Browser builds for Firefox and WebKit are built for the [glibc](https://en.wikipedia.org/wiki/GNU_C_Library) library. Alpine Linux and other distributions that are based on the [musl](https://en.wikipedia.org/wiki/Musl) standard library are not supported.