Testing

The MISCore package is and can be tested in several ways. First we explain how you can test the documentation, coding style and the functioning of MISCore locally. Then we highlight how these tests are performed in GitLab.

Documentation

The documentation can be built using Sphinx. The (HTML) documentation can be built in two steps. First, you should open the doc directory in the PyCharm terminal. For that, open the Terminal tab at the bottom of the PyCharm screen and call:

cd doc

Alternatively, you can find the folder in the Project Structure on the left, right-click on it and click “Open with” > “Terminal”. Second, call make.bat with html as argument by typing the following:

.\make.bat html

The created documentation will be in _build\html. Open it by going to the doc/_build/html folder and opening the index.html file in your browser (right-click on index.html and click “Open with” > “Browser”).

Note

Make sure to install all necessary Sphinx extensions. See the second bullet of Contributing.

Style guide

All code should adhere to the styling conventions as in PEP8. Imports should be grouped and sorted as described in the Google Python Style Guide. Docstrings should follow the conventions as in PEP257. You can check if the code adheres to these conventions by calling flake8 in the terminal:

flake8

Test suite

To ensure MISCore functions as expected, a test suite has been developed. This test suite has been implemented in the Python unittest unit testing framework and is located in the tests directory.

The unit tests (located in tests/unit) test the individual components of MISCore, whereas the integration tests (located in tests/integration) test the built-in processes and entire models.

The test suite can be run by using the following command:

python -m unittest discover -s tests -v

Alternatively, you can run the individual tests by finding them in the tests folder and clicking the green “run” arrow on the left of the code. See also: see https://www.jetbrains.com/help/pycharm/testing.html.

Continuous Integration in GitLab

For every push to the repository and every Git tag created a GitLab CI/CD pipeline is ran. The following stages and jobs are defined in the .gitlab-ci.yml file.

  • test

    In this first stage, several jobs are ran to check if nothing has been broken.

    • test_functionality

      This job tests the functionality of the MISCore package. It first creates a package and installs it. Then the test suite is ran, as well as the scripts in the examples and doc directories.

    • test_documentation

      This job attempts to build the documentation with Sphinx (in the nit-picky mode). The built documentation is uploaded as a job artifact.

    • test_style

      This job tests the code and docstring style using flake8 (with the flake8-import-order extension) and pydocstyle. The settings are defined in setup.cfg.

  • deploy

    This stage is only created when the pipeline is triggered for the main branch.

    • pages

      This job builds and uploads the documentation using GitLab Pages. Note that this only works if the job is named “pages”.

  • build

    In this stage, the MISCore package is built. All jobs should be manually triggered and have artifacts.

    • build_source

      This job creates a source distribution (i.e. miscore-x.x.x.tar.gz).

    • build_linux_xx

      This job creates a Linux binary wheel (i.e. miscore-x.x.x-cpxx-cpxx-linux_x86_64.whl). A job is defined for each supported Python version.

    • build_windows_xx

      This job creates 64 bit Windows binary wheels (i.e. miscore-x.x.x-cpxx-cpxx-win_amd64.whl). A job is defined for each supported Python version.

  • release

    This stage is only created when the pipeline is triggered by a Git tag (i.e. a release).

    • release

      This job can only be triggered manually. When doing so, all the created files in the build stage are uploaded to the GitLab PyPI repository.