Skip to content

Development Guide

Jump to bottom
Martin Chovanec edited this page May 18, 2018 · 2 revisions

Development Environment

[draft]

Sacredboard can be developed on any machine supporting Python 3.5+ and Node.js, but the preferred OS is Linux (or experimental: Windows Subsystem for Linux - WSL).

Ubuntu (recommended) dependencies

sudo apt install python3 libpython3-dev python3-venv build-essential git nodejs npm

Make sure your distribution of Node.js comes with the LTS 8.x version (or newer). If not, please install it separately.

Running from source

Clone:

git clone https://github.com/chovanecm/sacredboard.git

Optionally, create and activate a Python virtual environment for Sacredboard in order not to collide with your production version:

python3 -m venv sacredenv
source ./sacredenv/bin/activate

Switch to the sacredboard source folder and install in development mode:

python setup.py develop

Now you can run sacredboard as usual (or in debug mode):

sacredboard -m nameOfSacredDatabase --debug

Tests

Sacredboard combines Python and JavaScript code. While the first runs on the back-end, the latter is executed in the user’s web browser. Tests are important for reducing probability of introducing bugs when changing the code, to clarify expected behaviour of the components and to check code style standards for better readability.

Additional Python dependencies are required to run the test suite, which can be easily installed by make:

make pydependencies

Having installed all the dependencies, simply run

make test

to execute the test suite. Alternatively, the aspects of the application can be also tested separately, as described below.

Python Tests

For Python, Sacredboard tests are written on top of the pytest framework. To perform regression testing during the development, the fastest way is to do so by executing:

make pytest

Test files are located in the sacredboard/tests directory

JavaScript Tests

A compromise solution has been found in the QUnit framework that can run both in the web browser and Node.js. Developers that do not want / cannot install Node.js may run the tests in their web browser by navigating to http://localhost:5000/_tests when Sacredboard is running. The other and preferred option is to download Sacredboard’s JavaScript dependencies using the Node.js package manager (npm) and run the tests:

npm install
# Run JavaScript tests
npm test
# Run code style check
npm run lint

or simply:

make qunit
make eslint

JavaScript tests are located in the sacredboard/static/scripts/tests dictionary as modules. To let both the npm and web browser know which tests to run, the corresponding test modules must be loaded both in the tests/index.html and tests/node_tests.js files.

Continous Integration

[outdated]

To ensure that changes made to Sacredboard do not break the unit tests in the develop branch, a task for an continuous integration (CI) server is created every time an update is pushed to the GitHub repository. The build passes only if the following conditions are met:

  • Python unit tests pass both Python version 3.4 and 3.5
  • JavaScript unit tests pass
  • Python code style meets the PEP 8 convention
  • Python code documentation is present and meets the PEP 257 convention
  • Python code cyclomatic complexity of functions does not exceed 10
  • JavaScript code follows defined set of rules
  • JavaScript JSDoc code documentation follows defined set of rules

The Travis CI cloud service being used is provided free of charge to open source projects. But developers working on Sacredboard can run the tests even on their local machine. The following additional dependencies must be manually installed to do so:

Python packages:

  • tox

Other software:

  • nodejs >= 4.6
  • npm

Running tox (without parameters) in the project directory launches all the above mentioned tests and informs the user about failures. There are command line options provided to to run only a particular subset of the tests:

  • tox -e py35 – Runs python setup.py test with Python 3.5 interpreter. Replacing with py34 does the same for an older version.
  • tox -e flake8 – Checks Python code style, including the cyclomatic complexity of the code.
  • tox -e pydocstyle – Checks Python documentation style.
  • tox -e qunit – Runs npm install && npm test to run JavaScript tests (Node.js necessary).
  • tox -e eslint – Runs npm install && npm run lint to check JavaScript code and documentation style.
Clone this wiki locally