Developer guide

Automatic testing

AiiDA-KKR comes with a set of unit and regression tests for its functionality. The tests are run through pytest and they are defined in tests/ and the sub directories therein. Instead of running the JuKKR codes during the tests, we use AiiDA’s caching features via enable_archive_cache of the aiida-test-cache package. The different tests are organized in the tests directory in the following structure:

  1. tests/: files for common calcfunctions and workfunctions (i.e. not running any calculation of the plugin), tests for the entrypoints, common tools (e.g., plot_kkr)

  2. tests/conftest.py and tests/dbsetup.py: configuration of the test environment (setting up DB with codes etc.)

  3. tests/calculations/: tests for calculations of the plugin (VoronoiCalculation, KkrCalculation, KkrimpCalculation, KkrnanoCalculation)

  4. tests/cmdline/: tests for command line interface

  5. tests/parsers/: tests for calculation parsers

  6. tests/tools/: tests for tools that are part of AiiDA-KKR

  7. tests/workflows/: tests for the different workflows (using cached files for the calculations)

  8. tests/data_dir/: export files of tests that ran which are imported when tests are run to be able to use caching of the calculation instead of rerunning them

The following will run the unit tests:

# install aiida-kkr with testing extra
pip install -e .[testing]
# go to path where tests are defined
cd tests
# create fake executables
mkdir -p jukkr; cd jukkr && export PATH="$PWD:$PATH"; touch kkr.x; touch voronoi.exe; touch kkrflex.exe; chmod +x kkr.x voronoi.exe kkrflex.exe
# run tests (-h shows help)
./run_all.sh -h

The coverage of the tests is controlled via environment variables (see -h option of run_all.sh), e.g.:

RUN_VORONOI=1 RUN_KKRHOST=1 ./run_all.sh

In order to recreate test export files you need real executables instead of the fakes we create above:

cd tests
# this will download the code and compile voronoi, kkrhost and kkrimp
./jukkr_installation.sh -f
# make sure the executables are found in the PATH
cd jukkr && export PATH="$PWD:$PATH" && cd ..

If your changes require updates to reference data (checked via the pytest-regressions package) you should add the --force-regen option to the pytest run:

pytest --force-regen workflows/test_bs_wc.py

If any changes require recreating achive files used to cache calculations (created by enable_archive_cache from the aiida_test_cache package) rerun the corresponding pytest with the --archive-cache-overwrite option:

pytest calculations/test_vorocalc.py -svx --archive-cache-overwrite

Automatic linter and coding style checks

Enable enable automatic checks of code sanity and coding style:

pip install -e .[pre-commit]
pre-commit install

After this, the yapf formatter, the pylint linter and code analyzer will run at every commit.

To run the pre-commit hooks without making a commit use:

pre-commit run --all-files

If you ever need to skip these pre-commit hooks, just use:

git commit -n

Continuous integration

aiida-kkr comes with a .github folder that contains continuous integration tests on every commit using GitHub Actions. It will:

  1. run all tests for the django ORM

  2. build the documentation

  3. check coding style and version number (not required to pass by default)

  4. run CI tests

Building the documentation

  1. Install the docs extra:

    pip install -e .[docs]

  2. Edit the individual documentation pages:

    docs/source/index.rst
docs/source/developer_guide/index.rst
docs/source/user_guide/index.rst
...

  3. Use Sphinx to generate the html documentation:

    cd docs
make html

Check the result by opening build/html/index.html in your browser.

PyPI release

With every tag that is pushed a continuous deployment github action runs that uploads the code to pypi. Note that this will only be done if the tests (see Continuous integration) pass.

The latest release is therefore able to be installed via:

pip install aiida-kkr

Note

When updating the plugin package to a new version, remember to update the version number both in pyproject.toml and aiida_kkr/__init__.py.