From 4a37483294e98e705da7b52188879e47ced3f300 Mon Sep 17 00:00:00 2001
From: Tim Schaub <tim.schaub@gmail.com>
Date: Wed, 25 Sep 2019 09:26:03 +0200
Subject: [PATCH] Rendering test instructions

---
 rendering/readme.md | 34 ++++++++++++++++++++++++++++++++++
 rendering/test.js   |  2 +-
 2 files changed, 35 insertions(+), 1 deletion(-)
 create mode 100644 rendering/readme.md

diff --git a/rendering/readme.md b/rendering/readme.md
new file mode 100644
index 0000000000..d0837b0f85
--- /dev/null
+++ b/rendering/readme.md
@@ -0,0 +1,34 @@
+# Rendering Tests
+
+The rendering tests use [Puppeteer](https://github.com/GoogleChrome/puppeteer) to take a screenshot of a map and compare it to an expected screenshot.  Each directory in the `cases` directory includes a single test case with the following files:
+
+ * `main.js` - the script that sets up the map and calls the magic `render()` function
+ * `expected.png` - the expected screenshot (this can be generated with the `--fix` flag)
+ * `actual.png` - the screenshot generated when running the tests (ignored by git)
+ * `pass` - a generated marker file that represents the last time the test passed (ignored by git)
+
+## Running the tests
+
+To run all the rendering tests:
+
+```bash
+node rendering/test.js
+```
+
+To run a single rendering test case:
+
+```bash
+node rendering/test.js --match your-test-case-name
+```
+
+## Creating a new test
+
+To create a new test case, add a directory under `cases` and add a `main.js` to it (copied from one of the other cases).  Then to generate the `expected.png` screenshot, run the test script with the `--fix` flag:
+
+```bash
+node rendering/test.js --match your-test-case-name --fix
+```
+
+Note that your `main.js` needs to call the magic `render()` function after setting up the map.  This triggers a snapshot.  The `render()` function can be called with an options object that includes a `tolerance` property.  The tolerance is related to the ratio of mismatched pixels to the total number of pixels in the actual screenshot.
+
+After creating a new test case, commit your `main.js` and `expected.png` files.
diff --git a/rendering/test.js b/rendering/test.js
index 2a4d7003a8..d12b40082d 100755
--- a/rendering/test.js
+++ b/rendering/test.js
@@ -184,7 +184,7 @@ async function copyActualToExpected(entry) {
 async function renderEach(page, entries, options) {
   let fail = false;
   for (const entry of entries) {
-    const {tolerance = 0.001, message = ''} = await renderPage(page, entry, options);
+    const {tolerance = 0.005, message = ''} = await renderPage(page, entry, options);
 
     if (options.fix) {
       await copyActualToExpected(entry);