test-image: add documentation in CONTRIBUTING

Author: antoinerg

CONTRIBUTING.md

@@ -78,6 +78,33 @@ To check test coverage:
 npm run coverage
 ```
 
+### Running image tests
+
+#### Build Docker image
+To produce images reproducibly,
+we need to make sure Orca is running in exactly the same environment.
+To achieve this, we package Orca in a Docker image which can be built with:
+```
+export DOCKER_ORCA_IMAGE=orca_dev
+docker build -t "$DOCKER_ORCA_IMAGE" -f deployment/Dockerfile .
+```
+
+#### Build images and compare
+
+To run the image tests, run the following:
+```
+./test/image/render_mocks_cli build/test_images "$DOCKER_ORCA_IMAGE" && \
+./test/image/compare_images test/image/baselines build/test_images build/
+```
+
+#### Generate new baselines
+Simply build images as above but save then at `test/image/baselines` instead:
+```
+./test/image/render_mocks_cli test/image/baselines "$DOCKER_ORCA_IMAGE"
+```
+** Note that one can change the version of plotly.js used to build images
+by editing `test/image/render_mocks_cli`. **
+
 ## Packaging
 
 We use [`electron-builder`](https://github.com/electron-userland/electron-builder) to pack up

test/image/render_mocks_cli

@@ -1,8 +1,9 @@
 #!/usr/bin/env bash
 set -e
-
 programname=$0
 
+PLOTLYJS_URL="https://cdn.plot.ly/plotly-1.47.2.min.js"
+
 function usage {
     echo "usage: $programname output_folder [docker:image]"
     echo "  it renders all the JSON files found in ./test/image/mocks into the output_folder."
@@ -26,7 +27,7 @@ do
   ORCA_OPTS=(--topojson /plotly-geo-assets.js --mathjax /mathjax/MathJax.js)
 
   # pin Plotly.js' version
-  ORCA_OPTS+=(--plotlyJS "https://cdn.plot.ly/plotly-1.47.2.min.js")
+  ORCA_OPTS+=(--plotlyJS "$PLOTLYJS_URL")
 
   # Set Orca options
   ORCA_OPTS+=(--verbose --format "$format" --output-dir "$1")