Testing Guide

Before submitting a pull request, please make sure to read and follow this guide.

Before submitting code

• All tests should pass. Ideally, tests are run locally before a PR is submitted. See below for a guide on how to run tests on your own machine.

• Your code should not decrease test coverage (%).

Testing coverage

Test coverage (%) is a measure of the percentage of lines in the source code that are invoked during a test run.

• To view local coverage open mapstory/cover/index.html

• Current coverage:

• Coverage details: Click here

Types of tests

• Unit tests: Only tests a single unit of code. Smallest unit of test.
• Integration tests: Tests the interaction between components.
• End to end tests: Tests the system from a user's perspective.

Running tests

To run all python tests:

Start a shell inside the django container: docker-compose exec django /bin/bash

Then run this command to run all tests:

# To run all tests simply run the test script.
./test.sh

This will run all tests inside python files that follow these rules:

• File name starts with test
• Test functions start with test_

Running End to end tests

End-to-end tests simulate the user's actions on a browser. They provide a way to test complex interactions between website components as a real user would.

If you don't have protractor installed, follow the guide bellow

To run all e2e tests:

1. Start the server

cd to the vagrant provision directory (mapstory/mapstory/scripts/provision) and start the server with vagrant up:

2. Start the webdriver

On a new local shell:

• cd into mapstory/tests and
• run the script ./startWebDriver.sh.

3. Run tests with protractor

On a new local shell:

• cd into mapstory/tests and
• run the script ./runE2ETests.sh

Install End-to-end dependencies

For running end-to-end tests:

1: Install Protractor

The following needs to be installed on your system for running e2e tests:

• protractor

To install

1.1 Go to http://www.protractortest.org/#/ and follow the install instructions.

1.2 Get the webdriver by running : webdriver-manager update

Optional config

1.3 To set the browser used modify this line inside: tests/js/conf.js

browserName: 'chrome' or browserName: 'firefox'

Autofind tests

Any file following these rules will be found and run automatically as a test by the testRunner, and considered for the coverage report:

• File name starts with test
• Test functions start with test_

Tests directory structure

Unit test structure

All unit tests should use django's auto-generated test.py filebe inside their parent's app directory.

All other tests structure

Intregration and any additional tests they should follow the structure below:

mapstory/tests/
    integration/
    unit/
    js/

Any common objects, scripts and config files belong inside mapstory/tests

The subfolders inside should be organized like this:

• integration : For integration tests

• unit : For unit tests that do now belong inside an app's test file.

• js : For protractor's End-to-end test files.

Error Screenshots

When a test fails a screenshot is taken.

The filename is the timestamp and is saved to mapstory/mapstory/tests/errors

This folder is ignored by git and will not push error images to the repository.