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/wd/hub \
    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.