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: all the actions performed by tox must
  24 succeed before a patchset can be merged.  As a developer, it is also useful to
  25 run tox locally to detect and fix the issues before pushing the code for review.
  26
  27 .. _tox: https://tox.wiki/en/latest/
  28
  29
  30
  31 Using tox on a developer's machine
  32 ==================================
  33
  34 Requirement: |python-version|
  35 -----------------------------
  36
  37 .. |python-version| replace:: Python 3.8
  38
  39 The current version of Python used by NFVbench is |python-version|.  In
  40 particular, this means that |python-version| is used:
  41
  42 * by tox in CI
  43 * in nfvbench Docker image
  44 * in nfvbench traffic generator VM image
  45
  46 |python-version| is needed to be able to run tox locally.  If it is not
  47 available through the package manager, it can be installed using `pyenv`_.  In
  48 that case, it will also be necessary to install the `pyenv-virtualenv`_ plugin.
  49 Refer to the documentation of those projects for installation instructions.
  50
  51 .. _pyenv: https://github.com/pyenv/pyenv
  52 .. _pyenv-virtualenv: https://github.com/pyenv/pyenv-virtualenv
  53
  54
  55 tox installation
  56 ----------------
  57
  58 Install tox with::
  59
  60     $ pip install tox==3.21.4
  61
  62 .. note:: tox 3.21.4 is the version that comes with Ubuntu 22.04 and that can be
  63           found on gerrit.opnfv.org build servers.
  64
  65
  66 Running tox
  67 -----------
  68
  69 In nfvbench root directory, simply run tox with::
  70
  71     $ tox
  72
  73 If all goes well, tox shows a green summary such as::
  74
  75     py38: commands succeeded
  76     pep8: commands succeeded
  77     lint: commands succeeded
  78     docs: commands succeeded
  79     docs-linkcheck: commands succeeded
  80     congratulations :)
  81
  82 It is possible to run only a subset of tox *environments* with the ``-e``
  83 command line option.  For instance, to check the code style only, do::
  84
  85     $ tox -e pep8
  86
  87 Each tox *environment* uses a dedicated python virtual environment.  The
  88 ``-r`` command line option can be used to force the recreation of the virtual
  89 environment(s).  For instance::
  90
  91     $ tox -r