Skip to content

GitLab

Commit c2cb322e authored by BorjaEst's avatar BorjaEst
Browse files

Improve documentation

parent f556d03d
Hide whitespace changes
Inline Side-by-side
README.md
View file @ c2cb322e
......@@ -108,31 +108,14 @@ $ udocker run --user=application o3skim --help
...
```
# Testing <a name = "testing"></a>
There are 2 types of tests in this package.
On top, [tox](https://tox.readthedocs.io/en/latest/) automation is used to simplify the testing process.
Testing is based on [sqa-baseline](https://indigo-dc.github.io/sqa-baseline/) criteria. On top, [tox](https://tox.readthedocs.io/en/latest/) automation is used to simplify the testing process.
To run white and black box tests use:
To run unit and functional tests with coverage use:
```sh
$ tox
```
## BlackBox tests - [Unittest framework](https://docs.python.org/3/library/unittest.html)
Located inside package modules (./o3skim). This helps to test easily functions at low level. It helps the developer to ensure the function is creating has the expected behavior.
To run only white tests use:
```sh
$ tox o3skim
```
## BlackBox tests - [Pytest framework](https://docs.pytest.org/en/stable/)
Located inside tests package folder (./tests). Black box testing is used to test the system from a general overview of the application. Pytest framework is selected in order to provide a simple syntax to test all possible combinations from the user point of view.
To run only black box tests use:
```sh
$ tox tests
```
# Documentation <a name = "doc"></a>
All o3as project module documents can be found at [o3as.readthedocs.io](https://o3as.readthedocs.io/en/latest/).
......
docs/dev_guide/tests.rst
View file @ c2cb322e
Tests
==================================
Testing is based on sqa-baseline_ criteria, tox_ automation is used to
simplify the testing process.
Tests should run using tox_, an automation is used to simplify the
testing process.
.. _sqa-baseline: https://indigo-dc.github.io/sqa-baseline/
.. _tox: https://tox.readthedocs.io/en/latest/
To install it with pip use:
.. code-block:: bash
$ pip install tox
Tests are divided into two types:
- Black-Box tests: Based on pytest_ framework, test the functionality
of the application without peering into its internal structures or
workings.
- White tests: Based on unittest_ framework, test the internal
structures of the application.
.. _pytest: https://docs.pytest.org/en/stable/
.. _unittest: https://tox.readthedocs.io/en/latest/
To run White and Black-Box tests use:
To run unit and functional tests together with reports use:
.. code-block:: bash
$ tox
...
clean: commands succeeded
stylecheck: commands succeeded
bandit: commands succeeded
docs: commands succeeded
py36: commands succeeded
report: commands succeeded
...
This command generates a complete test report together with a
coverage and pep8 report.
The last coverage report output is produced at **htmlcov** which
can be displayed in html format accessing to **index.html**.
The last Pep8 report produced by flake8 at the output file
**flake8.log**.
Black-Box tests:
----------------
However, you can also run different test configurations using
different tox environments:
The framework used is pytest_ to provide a simple syntax to
test all possible combinations from the user point of view.
Pytest detects directly all tests following the test_discovery_
naming conventions. Therefore all Black-Box tests should be
located on the **tests** folder at the package root and start
with **test**. For example *test_sources.py*.
Code Style [QC.Sty]
-----------------------
Test pep8 maintenance style conventions based on pylint format.
To run stylecheck use:
.. _test_discovery: https://docs.pytest.org/en/reorganize-docs/new-docs/user/naming_conventions.html
.. code-block:: bash
More than 500 test combinations are generated using which otherwise
might not be feasible using other python test frameworks. To run
only Black-Box tests simply call tox followed by the folder with the
test location:
$ tox -e stylecheck
...
stylecheck: commands succeeded
...
Unit Testing [QC.Uni]
-----------------------
All unit tests are placed inside the package (./o3skim/test). This
helps to test easily functions at low level and ensure the functions
have the expected behavior.
To run unit tests use:
.. code-block:: bash
$ tox tests
$ tox -e unittesting
...
py36: commands succeeded
unittesting: commands succeeded
...
White tests:
------------
This environment also provide a coverage term report for the tests.
The design of Unit Tests is based on the python unittest_ framework,
a simple and extended test framework which ships by default together
with python.
The framework used is unittest_, a simple and extended test framework
which ships by default together with python.
.. _unittest: https://tox.readthedocs.io/en/latest/
The usage is very simple and straight forward for simple test, but
The usage is very simple and straight forward for simple tests, but
the difficulty to parametrize and combine multiple test fixtures
makes it not suitable for Black-Box testing without a very complex
customization.
To simplify code usage and testing, the white tests should be located
inside the package folder. To run only White tests simply call tox
followed by the package name:
Functional Testing [QC.Fun]
---------------------------
Located inside tests package folder (./tests). Functional testing is
used to test the system from a general overview of the application.
To run functional tests use:
.. code-block:: bash
$ tox o3skim
$ tox -e functional
...
py36: commands succeeded
functional: commands succeeded
...
This environment also provide a coverage term report for the tests.
The framework used is pytest_ to provide a simple syntax to test all
possible combinations from the user point of view.
Coverage and Pep8 reports:
--------------------------
Pytest detects directly all tests following the test_discovery_
naming conventions. Therefore all functional tests should be
located on the **tests** folder at the package root and start
with **test**. For example *test_sources.py*.
One of the benefits of tox test automation is the capability to
generate code reports during testing.
.. _pytest: https://docs.pytest.org/en/stable/
.. _test_discovery: https://docs.pytest.org/en/reorganize-docs/new-docs/user/naming_conventions.html
The last coverage report output is produced at **htmlcov** which
can be displayed in html format accessing to **index.html**.
More than 500 test combinations are generated using which otherwise
might not be feasible using other python test frameworks.
The last Pep8 report produced by flake8 at the output file
**flake8.log**.
Security [QC.Sec]
-----------------------
Security checks are performed by bandit_, a tool designed to find
common security issues in Python code.
To run security checks use:
.. code-block:: bash
$ tox -e functional
...
functional: commands succeeded
...
.. _bandit: https://pypi.org/project/bandit/
Documentation [QC.Doc]
-----------------------
Documentation is build using sphinx_, a tool designed to create
documentation based on code.
To run documentation build checks use:
.. code-block:: bash
$ tox -e docs
...
docs: commands succeeded
...
.. _sphinx: https://www.sphinx-doc.org/en/master/
The HTML pages are build inside in docs/_build.
docs/index.rst
View file @ c2cb322e
......@@ -14,6 +14,7 @@ Getting started
* How to :doc:`getting_started/build` your o3skim container.
* How to :doc:`getting_started/deployment` your o3skim container.
* How to use the o3skim :doc:`getting_started/cli`
* Create your :doc:`getting_started/source-file` to point what to skim.
.. toctree::
:maxdepth: 2
......@@ -24,27 +25,14 @@ Getting started
getting_started/build
getting_started/deployment
getting_started/cli
User guide
=========================================
* Create your :doc:`user_guide/source-file` to point what to skim.
* Learn how to skim by reading the :doc:`user_guide/o3skim`
.. toctree::
:maxdepth: 2
:hidden:
:caption: User guide:
user_guide/source-file
user_guide/o3skim
getting_started/source-file
Developer guide
=========================================
* How to do a :doc:`dev_guide/local-install`
* How to use o3skim package :doc:`dev_guide/o3skim`
* How to run and create new :doc:`dev_guide/tests`
.. toctree::
......@@ -54,28 +42,16 @@ Developer guide
dev_guide/local-install
dev_guide/tests
dev_guide/o3skim
See also
Authors
=========================================
Indices and tables
---------------------
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
Authors
---------------------
- `@V.Kozlov <https://git.scc.kit.edu/eo9869>`_ - TBD
- `@T.Kerzenmacher <https://git.scc.kit.edu/px5501>`_ - TBD
- `@B.Esteban <https://git.scc.kit.edu/zr5094>`_ - TBD
Acknowledgements
---------------------
- `@T.Kerzenmacher <https://git.scc.kit.edu/px5501>`_ - Data scientist at KIT-IMK_
- `@V.Kozlov <https://git.scc.kit.edu/eo9869>`_ - Code developer at KIT-SCC_
- `@B.Esteban <https://git.scc.kit.edu/zr5094>`_ - Code developer at KIT-SCC_
.. _KIT-IMK: https://www.imk.kit.edu/english/index.php
.. _KIT-SCC: https://www.scc.kit.edu/en/index.php
tox.ini
View file @ c2cb322e
[tox]
minversion = 1.6
skipsdist = True
envlist = clean,stylecheck,py36,report
envlist =
clean,
stylecheck,
bandit,
docs,
py36,
report
[testenv]
commands = pytest --basetemp="{envtmpdir}" \
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment