From aad6301aca621cbbea855945932c3ab991e3b71d Mon Sep 17 00:00:00 2001
From: Arjun Attam <arjunattam@gmail.com>
Date: Fri, 26 Jun 2020 17:49:18 -0700
Subject: [PATCH] docs(ci): update intro, caching section, add gitlab (#2735)

---
 docs/ci.md | 37 +++++++++++++++++++++++++++++++++----
 1 file changed, 33 insertions(+), 4 deletions(-)

diff --git a/docs/ci.md b/docs/ci.md
index 62f3ead9ad..1339b7bb48 100644
--- a/docs/ci.md
+++ b/docs/ci.md
@@ -1,8 +1,10 @@
 # Continuous Integration
 
-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.
+Playwright tests can be executed in CI environments. We have created sample
+configurations for common CI providers.
 
 <!-- GEN:toc -->
+- [Introduction](#introduction)
 - [CI configurations](#ci-configurations)
   * [GitHub Actions](#github-actions)
   * [Docker](#docker)
@@ -11,6 +13,7 @@ Playwright tests can be executed to run on your CI environments. To simplify thi
   * [CircleCI](#circleci)
   * [AppVeyor](#appveyor)
   * [Bitbucket Pipelines](#bitbucket-pipelines)
+  * [GitLab CI](#gitlab-ci)
 - [Caching browsers](#caching-browsers)
     - [Exception: `node_modules` are cached](#exception-nodemodules-are-cached)
     - [Directories to cache](#directories-to-cache)
@@ -18,7 +21,15 @@ Playwright tests can be executed to run on your CI environments. To simplify thi
 - [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.
+## Introduction
+
+3 steps to get your tests running on CI:
+
+1. **Ensure CI agent can run browsers**: Use [our Docker image](docker/README.md)
+   in Linux agents. Windows and macOS agents do not require any additional dependencies.
+1. **Install Playwright**: In most projects, this would be done with `npm ci`
+   (or `npm install`). Playwright would install the relevant browsers automatically.
+1. **Run your tests**: Use `npm test` or equivalent to execute your tests.
 
 ## CI configurations
 
@@ -174,6 +185,22 @@ const { chromium } = require('playwright');
 const browser = await chromium.launch({ args: ['--no-sandbox'] });
 ```
 
+### GitLab CI
+
+To run Playwright tests on GitLab, use our public Docker image ([see Dockerfile](docker/README.md)).
+
+```yml
+stages:
+  - test
+
+tests:
+  stage: test
+  image: aslushnikov/playwright:bionic
+  script:
+    - npm install # This should install playwright
+    - npm run test
+```
+
 ## Caching browsers
 
 By default, Playwright downloads browser binaries when the Playwright NPM package
@@ -188,8 +215,8 @@ execute and download the browser binaries on every run.
 Most CI providers cache the [npm-cache](https://docs.npmjs.com/cli-commands/cache.html)
 directory (located at `$HOME/.npm`). If your CI pipelines caches the `node_modules`
 directory and you run `npm install` (instead of `npm ci`), the default configuration 
-**will not work**. This is because the `npm install` step will find the NPM
-package on disk, and not execute the `postinstall` step.
+**will not work**. This is because the `npm install` step will find the Playwright NPM
+package on disk and not execute the `postinstall` step.
 
 > Travis CI automatically caches `node_modules` if your repo does not have a
   `package-lock.json` file.
@@ -200,6 +227,8 @@ This behavior can be fixed with one of the following approaches:
 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 [installation docs](installation.md).
+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.
 
 #### Directories to cache