:memo: Add Headless CI Tutorial

diff --git a/docs/README.md b/docs/README.md
index 9d2b36e..19ec513 100644 (file)
--- a/docs/README.md
+++ b/docs/README.md
@@ -26,6 +26,7 @@ an issue:
 * [DevTools Extension](tutorial/devtools-extension.md)
 * [Using Pepper Flash Plugin](tutorial/using-pepper-flash-plugin.md)
 * [Using Widevine CDM Plugin](tutorial/using-widevine-cdm-plugin.md)
+* [Testing on Headless CI Systems (Travis, Jenkins)](tutorial/testing-on-headless-ci.md)
 
 ## Tutorials
 

diff --git a/docs/tutorial/testing-on-headless-ci.md b/docs/tutorial/testing-on-headless-ci.md
new file mode 100644 (file)
index 0000000..6b0dacf
--- /dev/null
+++ b/docs/tutorial/testing-on-headless-ci.md
@@ -0,0 +1,38 @@
+# Testing Electron with headless CI Systems (Travis CI, Jenkins)
+
+Being based on Chromium, Electron requires a display driver to function. If Chromium can't find a display driver, Electron will simply fail to launch - and therefore not executing any of your tests, regardless of how you are running them. Testing Electron-based apps on Travis, Circle, Jenkins or similar systems requires therefore a little bit of configuration. In essence, we need to use a virtual display driver.
+
+## Configuring the Virtual Display Server
+First, install [Xvfb](https://en.wikipedia.org/wiki/Xvfb). It's a virtual framebuffer, implementing the X11 display server protocol - it performs all graphical operations in memory without showing any screen output, which is exactly what we need.
+
+Then, create a virtual xvfb screen and export an environment variable called DISPLAY that points to it. Chromium in Electron will automatically look for `$DISPLAY`, so no further configuration of your app is required. This step can be automated with Paul Betts's [xfvb-maybe](https://github.com/paulcbetts/xvfb-maybe): Prepend your test commands with `xfvb-maybe` and the little tool will automatically configure xfvb, if required by the current system. On Windows or Mac OS X, it will simply do nothing. 
+
+```
+## On Windows or OS X, this just invokes electron-mocha
+## On Linux, if we are in a headless environment, this will be equivalent
+## to xvfb-run electron-mocha ./test/*.js
+xvfb-maybe electron-mocha ./test/*.js
+```
+
+### Travis CI
+On Travis, your `.travis.yml` should look roughly like this:
+
+```
+addons:
+  apt:
+    packages:
+      - xvfb
+
+install:
+  - export DISPLAY=':99.0'
+  - Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &
+```
+
+### Jenkins
+For Jenkins, a [Xfvb plugin is available](https://wiki.jenkins-ci.org/display/JENKINS/Xvfb+Plugin).
+
+### Circle CI
+Circle CI is awesome and has xvfb and `$DISPLAY` [already setup, so no further configuration is required](https://circleci.com/docs/environment#browsers).
+
+### AppVeyor
+AppVeyor runs on Windows, supporting Selenium, Chromium, Electron and similar tools out of the box - no configuration is required.