63 lines
4.6 KiB
ReStructuredText
63 lines
4.6 KiB
ReStructuredText
Quality Assurance
|
|
=================
|
|
|
|
This section shows you how to test the software locally on your machine and ensure that your contributions follow our common coding standards.
|
|
Note that with every contribution pushed to the Gitlab server the routines that are described here are automatically executed for you.
|
|
The results are then visible in `the repository's CI/CD section <https://gitlab.sailingteam.hg.tu-darmstadt.de/informatik/pyrate/-/pipelines>`__ and in the specific merge request view.
|
|
`The Software section of the Wiki <https://gitlab.sailingteam.hg.tu-darmstadt.de/team/wiki/-/wikis/Software/Home%20%F0%9F%92%BB>`__ also holds further information on our `styleguide <https://gitlab.sailingteam.hg.tu-darmstadt.de/team/wiki/-/wikis/Software/Quality-Assurance/Styleguide>`__, `documentation <https://gitlab.sailingteam.hg.tu-darmstadt.de/team/wiki/-/wikis/Software/Quality-Assurance/Documentation>`__ and `testing <https://gitlab.sailingteam.hg.tu-darmstadt.de/team/wiki/-/wikis/Software/Quality-Assurance/Testing>`__.
|
|
|
|
Coding Style
|
|
------------
|
|
|
|
A common style when collaborating on a big project is crucial to keep everything maintainable and easy to understand in the long run.
|
|
To make sure you are following the rules we employ a number of programs that help us to analyse the source automatically.
|
|
Since Python is an interpreted language, we do not have a compiler that ensures that everything we write will make sense at runtime.
|
|
Linting and enforcing coding conventions thereby can have a very important role in keeping our software reliable.
|
|
To get reports on the code you have written you can use the following commands in the packages root directory.
|
|
|
|
|
|
.. code-block:: bash
|
|
|
|
flake8
|
|
mypy pyrate tests scripts
|
|
pylint -j 0 pyrate tests scripts
|
|
|
|
|
|
Testing
|
|
-------
|
|
|
|
Tests can be run by simply executing :code:`pytest` within the repositories root directory.
|
|
This will also result in coverage statistics being printed, which are a good indicator whether your tests are covering all the lines of your code.
|
|
Again, since Python is not compiled, this can be very useful.
|
|
Nevertheless, make sure that your tests ideally go beyond mere execution of code and assert its correctness.
|
|
Besides statement coverage, we also collect branch coverage (see `here <https://coverage.readthedocs.io/en/stable/branch.html>`__).
|
|
We require that all contributions achieve 100% statement coverage and 90% branch coverage.
|
|
|
|
Two parts of the library are special when it comes to testing:
|
|
Both the tests around :code:`pyrate.common.charts.SpatialiteDatabase` and around :code:`pyrate.common.charts.S57ChartHandler` are only exercised if the required dependencies are met and if not running on a CI server.
|
|
If the dependencies cannot be found, the tests will be marked as skipped.
|
|
This allows for easier development as less dependencies are actually required for running the tests, but the CI server will still check these modules for you.
|
|
|
|
|
|
Hypothesis Testing and Speed
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Many tests use the `Hypothesis property based testing framework <https://hypothesis.readthedocs.io/en/latest/>`__.
|
|
Everyone is encouraged to do so too, and there are already some handy example generators in ``tests/strategies/``.
|
|
The settings (along with some more general setup) are declared in ``tests/__init__.py``.
|
|
|
|
However, a few tests take a lot of time to process, like for example the tests that use the very slow cartesian route example generation.
|
|
Therefore, it might be required to reduce the number of tests, as is done in ``tests/plan/geometry/primitives/test_polygons.py`` using the ``@settings()`` decorator.
|
|
Timings for (all) individual tests can be obtained by running pytest with ``--durations=0`` (see `the pytest docs <https://docs.pytest.org/en/stable/usage.html#profiling-test-execution-duration>`__).
|
|
You may want to temporarily add this argument to the ``addopts`` option in the section ``[tool.pytest.ini_options]`` in ``pyproject.toml``.
|
|
|
|
|
|
Downstream CI Pipeline Triggers
|
|
-------------------------------
|
|
|
|
Other projects like *ros-nodes* depend on *Pyrate*: They are *downstream* projects, as changes in *Pyrate* flow down the "stream of dependencies" to them.
|
|
To ensure that changes here in the upstream *Pyrate* project do not break such downstream projects (or just to remind us to fix stuff over there too),
|
|
the pipeline of this repository triggers the ones of downstream projects.
|
|
This is configured in a special ``Deploy``-stage job called ``Trigger Downstream Pipelines`` at the bottom of the ``.gitlab-ci.yml`` file (in this upstream project!).
|
|
The capabilities are documented in `the official GitLab docs on "Multi-project pipelines" <https://docs.gitlab.com/ee/ci/multi_project_pipelines.html>`__.
|