docs/developer/testing-nfvbench.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. SPDX-License-Identifier: CC-BY-4.0
   3
   4 ================
   5 Testing NFVbench
   6 ================
   7
   8 tox
   9 ===
  10
  11 NFVbench project uses `tox`_ to orchestrate the testing of the code base:
  12
  13 * run unit tests
  14 * check code style
  15 * run linter
  16 * check links in the docs
  17
  18 In addition to testing, tox is also used to generate the documentation in HTML
  19 format.
  20
  21 What tox should do is specified in a ``tox.ini`` file located at the project root.
  22
  23 tox is used in continuous integration (jenkins-ci today, gitlab-ci in the near
  24 future): all the actions performed by tox must succeed before a patchset can be
  25 merged.  As a developer, it is also useful to run tox locally to detect and fix
  26 the issues before pushing the code for review.
  27
  28 .. _tox: https://tox.wiki/en/latest/
  29
  30
  31
  32 Using tox on a developer's machine
  33 ==================================
  34
  35 Requirement: |python-version|
  36 -----------------------------
  37
  38 .. |python-version| replace:: Python 3.6
  39
  40 The current version of Python used by NFVbench is |python-version|.  In
  41 particular, this means that |python-version| is used:
  42
  43 * by tox in CI
  44 * in nfvbench Docker image
  45 * in nfvbench traffic generator VM image
  46
  47 |python-version| is needed to be able to run tox locally.  If it is not
  48 available through the package manager, it can be installed using `pyenv`_.  In
  49 that case, it will also be necessary to install the `pyenv-virtualenv`_ plugin.
  50 Refer to the documentation of those projects for installation instructions.
  51
  52 .. _pyenv: https://github.com/pyenv/pyenv
  53 .. _pyenv-virtualenv: https://github.com/pyenv/pyenv-virtualenv
  54
  55
  56 tox installation
  57 ----------------
  58
  59 Install tox with::
  60
  61     $ pip install tox tox-pip-version
  62
  63
  64 Running tox
  65 -----------
  66
  67 In nfvbench root directory, simply run tox with::
  68
  69     $ tox
  70
  71 If all goes well, tox shows a green summary such as::
  72
  73     py36: commands succeeded
  74     pep8: commands succeeded
  75     lint: commands succeeded
  76     docs: commands succeeded
  77     docs-linkcheck: commands succeeded
  78     congratulations :)
  79
  80 It is possible to run only a subset of tox *environments* with the ``-e``
  81 command line option.  For instance, to check the code style only, do::
  82
  83     $ tox -e pep8
  84
  85 Each tox *environment* uses a dedicated python virtual environment.  The
  86 ``-r`` command line option can be used to force the recreation of the virtual
  87 environment(s).  For instance::
  88
  89     $ tox -r