update image container readme

Author: etpinard

test/image/README.md

@@ -40,25 +40,86 @@ as listed on [hub.docker.com](https://hub.docker.com/r/plotly/testbed/tags/) and
 
 ### Step 2: Run the image tests
 
-Inside your `plotly.js` directory, run
+The image testing docker container allows plotly.js developers to (A) run image
+comparison tests, (B) run image export tests and (C) generate baseline
+images.
+
+**IMPORTANT:** the image tests scripts do **not** bundle the source files before
+running the image tests. We recommend running `npm run watch` or `npm start` in
+a separate tab to ensure that the most up-to-date code is used.
+
+##### A: Run image comparison tests
+
+Image comparison tests take in plotly.js mock json files (found in
+[`test/image/mocks`][mocks]), generate test png images (saved in
+`build/test_images/` - which is git-ignored) and compare them pixel-by-pixel to
+their corresponding baseline images (found in
+[`test/image/baselines`][baselines]) using
+[`GraphicsMagick`](https://github.com/aheckmann/gm).
+
+To run the image comparison tests, in your `plotly.js` directory:
 
 ```bash
 npm run test-image
 ```
 
-if some tests fail, compare their outputs using `npm run start-image_viewer`.
+which runs all image comparison tests in batch. If some tests fail, compare their outputs
+using `npm run start-image_viewer`.
 
-**IMPORTANT:** `npm run test-image` does **not** bundle the source files before running the image tests. We recommend runnnig `npm run watch` or `npm run start-test_dashboard` in a separate tab to ensure that the most up-to-date code is tested. 
+As an alternative to running all image comparison tests at once, you can provide
+a glob as argument to target one or multiple test mocks found in
+[`test/image/mocks`][mocks].
+For example,
 
-### Step 2b: Make a new or update an existing baseline image
+```bash
+# Run one test (e.g. the 'contour_nolines' test):
+$ npm run test-image -- contour_nolines
 
-Inside your `plotly.js` directory, run
+# Run all gl3d image test in batch:
+$ npm run test-image -- gl3d_*
+```
+
+Developers on weak hardware might encounter batch timeout issue. These are most
+common when generated WebGL-based graphs. In this case, running the image
+comparison tests in queue (i.e. with no concurrency) is recommended:
 
 ```bash
-npm run baseline -- mock.json
+# Run all gl3d image test in queue:
+$ npm run test-image -- gl3d_* --queue
+```
+
+##### B: Run image export tests
+
+Image export tests check that image export works for formats other than png.
+
+To run the image export tests, in your `plotly.js` directory:
+
+```bash
+npm run test-export
+
+# or
+npm run test-export -- <glob>
+```
+
+##### C: Generate or update existing baseline image
+
+To generate a new baseline image, add a new mock file in
+[`test/image/mocks`][mocks]. Note that mock file needs to be a valid JSON and
+have both a "data" and a `"layout"` field. Then, in your plotly.js directory,
+run:
+
+```bash
+npm run baseline -- <name-of-mock>
+```
+
+which generates a baseline png image in [`test/image/baselines`][baselines].
+
+To update existing baseline image(s), run
+
+```bash
+npm run basline -- <glob-of-mocks-to-update>
 ```
 
-where `mock.json` is the name of a `{"data": [], "layout": {}}` json file found in [`test/image/mocks/`](https://github.com/plotly/plotly.js/tree/master/test/image/mocks). The `"data"` and `"layout"` field are passed to `Plotly.plot` to produce an image saved in [`test/image/baslines`](https://github.com/plotly/plotly.js/tree/master/test/image/baselines).
 
 ### Step 3: Stop your testing container
 
@@ -74,7 +135,7 @@ Mac and Windows user should also kill their docker-machine (named `default`) onc
 docker-machine kill default
 ```
 
-### Docker tricks 
+### Docker tricks
 
 ##### SSH into docker container
 
@@ -145,3 +206,6 @@ docker-machine kill default
 ```
 
 For more comprehensive information about docker, please refer to the [docker docs](http://docs.docker.com/).
+
+[mocks]: https://github.com/plotly/plotly.js/tree/master/test/image/mocks
+[baselines]: https://github.com/plotly/plotly.js/tree/master/test/image/baselines