Files
@ 8655320fec11
Branch filter:
Location: gimmecert/docs/development.rst
8655320fec11
4.0 KiB
text/prs.fallenstein.rst
GC-14: Cleaned-up testing and development configuration and documentation:
- Enforce 100% coverage in tests (fail the tests otherwise).
- Updated development documentation to list:
- How to run tests with coverage.
- How to generate coverage in html format.
- How to build documentation.
- What tests are included when running test via tox.
- Default to running just the unit tests when not passing in any
arguments to pytest.
- Removed use of pytest-flake8.
- Do not run coverage tests by default outside of tox.
- Ensure documentation is built inside of tox environment, and that it
does not pollute the source directory.
- Have all Python interpreters specified in same section in tox
configuration file.
- Enforce 100% coverage in tests (fail the tests otherwise).
- Updated development documentation to list:
- How to run tests with coverage.
- How to generate coverage in html format.
- How to build documentation.
- What tests are included when running test via tox.
- Default to running just the unit tests when not passing in any
arguments to pytest.
- Removed use of pytest-flake8.
- Do not run coverage tests by default outside of tox.
- Ensure documentation is built inside of tox environment, and that it
does not pollute the source directory.
- Have all Python interpreters specified in same section in tox
configuration file.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 | .. Copyright (C) 2018 Branko Majic
This file is part of Gimmecert documentation.
This work is licensed under the Creative Commons Attribution-ShareAlike 3.0
Unported License. To view a copy of this license, visit
http://creativecommons.org/licenses/by-sa/3.0/ or send a letter to Creative
Commons, 444 Castro Street, Suite 900, Mountain View, California, 94041, USA.
Development
===========
This section provides information on development process for the
project, including instructions on how to set-up a development
environment or run the tests locally.
Preparing development environment
---------------------------------
There is a number of different ways a development environment can be
set-up. The process outlined here is centered around
`virtualenvwrapper
<https://virtualenvwrapper.readthedocs.io/>`_. Instructions have been
tailored for a GNU/Linux system.
Before proceeding, ensure you have the following system-wide packages
installed:
- `Python, version 3.4+ <https://www.python.org/>`_.
- `virtualenvwrapper <https://virtualenvwrapper.readthedocs.io/>`_.
With those in place, do the following:
1. Clone the git repository::
git clone https://code.majic.rs/gimmecert/
2. Change directory::
cd gimmecert/
3. Create Python virtual environment:
.. warning::
Make sure to specify Python 3 as interpreter.
::
mkvirtualenv -a . -p /usr/bin/python3 gimmecert
4. Install development requirements::
pip install -e .[devel]
5. At this point, any time you want to run tests etc, you can easily
switch to correct environment (this will also put you in project
root directory) with::
workon gimmecert
Testing
-------
Project includes both unit tests (within ``tests/`` directory) , and
functional tests (within ``functional_tests/`` directory).
Tests can be run in a number of different ways, depending on what you
want to test and how.
To run the unit tests via setup script, run the following command from
repository root::
python setup.py test
To run the unit tests directly, run the following command from
repository root::
pytest
Tests can be also run with coverage checks. By default coverage is
configured to report to standard output. Report will only list files
which lack coverage. For each file a percentage will be shown, as well
as line numbers that were not covered by tests. To include coverage
checks, run tests with::
pytest --cov
.. warning::
Gimmecert project has 100% coverage requirement. Anything below
will trigger failures when coverage checks are run.
Should you desire to generate coverage report in HTML format, run
(coverage report will be put into directory ``coverage/``)::
pytest --cov --cov-report=html:coverage/
Functional tests must be run explicitly (since they tend to take more
time), with::
pytest functional_tests/
In addition to proper linting, implemented code should be pruned of
unused imports and variables. Linting should be conformant to PEP8,
with the exception of line length, which is allowed to be up to 160
characters. Linting and code sanity checks are not executed
automatically, but can easily be run with::
flake8
Documentation should be buildable at all times. Documentation build
can be triggered with a simple::
cd docs/
make html
Tests can also be run using `tox <https://tox.readthedocs.io/>`_:
.. note::
When running tests via ``tox``, functional tests and coverage
checks are included as well.
::
# Run full suite of tests on all supported Python versions.
tox
# List available tox environments.
tox -l
# Run tests against specific Python version.
tox -e py35
# Run documentation and linting tests only.
tox -e doc,lint
Building documentation
----------------------
Documentation is written in `reStructuredText
<https://en.wikipedia.org/wiki/ReStructuredText>`_ and built via
`Sphinx <http://www.sphinx-doc.org/>`_.
To build documentation, run::
cd docs/
make html
Resulting documentation will be stored in HTML format in directory
``docs/_build/html/``.
|