Document test suite

docs/dev/03_run_tests.rst

+Running tests and reports
+=========================
+
+Running default test suite
+--------------------------
+
+The test suite can be run using the `tox` tool::
+
+  poetry run tox
+
+
+Enabling Selenium browser tests
+-------------------------------
+
+The test suite contains tests that use Selenium to do browser based tests.
+They need to be enabled when running the test suite, which can be done by
+setting certain environment variables:
+
++------------------------+------------------------------------------------------+------------------------------+
+| Variable               | Meaning                                              | Example                      |
++========================+======================================================+==============================+
+| TEST_SELENIUM_BROWSERS | List of webdrivers to test against, comma-separated. | chrome,firefox               |
+| TEST_SELENIUM_HUB      | Address of Selenium hub if using remote grid         | http://127.0.0.1:4444/wd/hub |
+| TEST_HOST              | Hostname reachable from Selenium for live server     | 172.17.0.1                   |
+| TEST_SCREENSHOT_PATH   | Path to directory to create screenshots in           | ./screenshots                |
++------------------------+------------------------------------------------------+------------------------------+
+
+Selenium tests are enabled if `TEST_SELENIUM_BROWSERS` is non-empty.
+
+To set variables, use env to wrap the tox ommand::
+
+  poetry run env TEST_SELENIUM_BROWSERS=chrome,firefox tox
+
+
+Using a Selenium hub on local Docker host
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+One way to setup Selenium is to use the official images on the local
+machine.
+
+First, get Selenium Hub and one or more browser nodes up and running::
+
+  docker run -d -p 4444:4444 --name selenium-hub selenium/hub
+  docker run -d --link selenium-hub:hub selenium/node-chrome
+  docker run -d --link selenium-hub:hub selenium/node-firefox
+
+After that, you can run the test suite, setting the needed variables to use
+Docker Hub::
+
+  poetry run env \
+    TEST_SELENIUM_BROWSERS=chrome,firefox \
+    TEST_SELENIUM_HUB=http://127.0.0.1:4444 \
+    TEST_HOST=172.17.0.1 \
+  tox
+
+The `TEST_HOST` variable is set to the Docker host's IP address, where the
+Selenium nodes can access DJango's live server.  Django automatically
+configures the live server to be reachable if a Selenium hub is used.
+
+
+Taking screenshots
+~~~~~~~~~~~~~~~~~~
+
+The browser test suites automatically take screenshots at certain steps if
+enabled in the test run.  This can be used to visually verify that views
+look like they should or for documentation purposes.
+
+To enable screenshots, add the `TEST_SCREENSHOT_PATH` environment variable
+when running the tests.
+
+If runnin multiple browsers, screenshots are placed in separate directories
+per browser.