What does "make check" mean?
----------------------------
-After compiling Ceph, the code can be run through a battery of tests
-For historical reasons, this is
-often referred to as ``make check`` even though the actual command used to run
-the tests is now ``ctest``. For inclusion in this group of tests, a test
-must:
-
+After compiling Ceph, the code can be run through a battery of tests. For
+historical reasons, this is often referred to as ``make check`` even though
+the actual command used to run the tests is now ``ctest``. To be included in
+this group of tests, a test must:
* bind ports that do not conflict with other tests
* not require root access
framework`_.
While it is possible to run ``ctest`` directly, it can be tricky to correctly
-set up your environment. Fortunately, a script is provided to make it easier
-run the unit tests on your code. It can be run from the top-level directory of
-the Ceph source tree by invoking:
+set up your environment for it. Fortunately, there is a script that makes it
+easy to run the unit tests on your code. This script can be run from the
+top-level directory of the Ceph source tree by invoking:
.. prompt:: bash $
./run-make-check.sh
You will need a minimum of 8GB of RAM and 32GB of free drive space for this
-command to complete successfully on x86_64; other architectures may have
-different requirements. Depending on your hardware, it can take from twenty
-minutes to three hours to complete, but it's worth the wait.
+command to complete successfully on x86_64 architectures; other architectures
+may have different requirements. Depending on your hardware, it can take from
+twenty minutes to three hours to complete.
How unit tests are declared
---------------------------
-Unit tests are declared in the ``CMakeLists.txt`` file, which is found
-in the ``./src`` directory. The ``add_ceph_test`` and
-``add_ceph_unittest`` CMake functions are used to declare unit tests.
-``add_ceph_test`` and ``add_ceph_unittest`` are themselves defined in
+Unit tests are declared in the ``CMakeLists.txt`` file, which is found in the
+``./src`` directory. The ``add_ceph_test`` and ``add_ceph_unittest`` CMake
+functions are used to declare unit tests. ``add_ceph_test`` and
+``add_ceph_unittest`` are themselves defined in
``./cmake/modules/AddCephTest.cmake``.
Some unit tests are scripts and other unit tests are binaries that are
Unit testing of CLI tools
-------------------------
-
Some of the CLI tools are tested using special files ending with the extension
``.t`` and stored under ``./src/test/cli``. These tests are run using a tool
-called `cram`_ via a shell script ``./src/test/run-cli-tests``. `cram`_ tests
-that are not suitable for ``make check`` may also be run by teuthology using
-the `cram task`_.
+called `cram`_ via a shell script called ``./src/test/run-cli-tests``.
+`cram`_ tests that are not suitable for ``make check`` can also be run by
+teuthology using the `cram task`_.
.. _`cram`: https://bitheap.org/cram/
.. _`cram task`: https://github.com/ceph/ceph/blob/master/qa/tasks/cram.py
-Tox based testing of python modules
+Tox-based testing of Python modules
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Some of the Python modules in Ceph use `tox <https://tox.readthedocs.io/en/latest/>`_
+to run their unit tests.
+
+Most of these Python modules can be found in the directory ``./src/pybind/``.
+
+Currently (December 2020) the following modules use **tox**:
+
+* Cephadm (``./src/cephadm/tox.ini``)
+* Ceph Manager Python API (``./src/pybind/mgr``)
+
+ * ``./src/pybind/mgr/tox.ini``
+
+ * ``./src/pybind/mgr/dashboard/tox.ini``
+
+ * ``./src/pybind/tox.ini``
+
+* Dashboard (``./src/pybind/mgr/dashboard``)
+* Python common (``./src/python-common/tox.ini``)
+* CephFS (``./src/tools/cephfs/tox.ini``)
+* ceph-volume
+
+ * ``./src/ceph-volume/tox.ini``
+
+ * ``./src/ceph-volume/plugin/zfs/tox.ini``
-Most python modules can be found under ``./src/pybind/``.
+ * ``./src/ceph-volume/ceph_volume/tests/functional/batch/tox.ini``
-Many modules use **tox** to run their unit tests.
-**tox** itself is a generic virtualenv management and test command line tool.
+ * ``./src/ceph-volume/ceph_volume/tests/functional/simple/tox.ini``
-To find out quickly if **tox** can be run you can either just try to run ``tox``
-or check for the existence of a ``tox.ini`` file.
+ * ``./src/ceph-volume/ceph_volume/tests/functional/lvm/tox.ini``
-Currently the following modules use **tox**:
+Configuring Tox environments and tasks
+""""""""""""""""""""""""""""""""""""""
+Most tox configurations support multiple environments and tasks.
-- Cephadm (``./src/pybind/mgr/cephadm``)
-- Insights (``./src/pybind/mgr/insights``)
-- Manager core (``./src/pybind/mgr``)
-- Dashboard (``./src/pybind/mgr/dashboard``)
-- Python common (``./src/python-common/tox.ini``)
+The list of environments and tasks that are supported is in the ``tox.ini``
+file, under ``envlist``. For example, here are the first three lines of
+``./src/cephadm/tox.ini``::
+
+ [tox]
+ envlist = py3, mypy
+ skipsdist=true
+
+In this example, the ``Python 3`` and ``mypy`` environments are specified.
+
+The list of environments can be retrieved with the following command:
+
+ .. prompt:: bash $
+
+ tox --list
+
+Or:
+
+ .. prompt:: bash $
+ tox -l
-Most **tox** configurations support multiple environments and tasks. You can see
-which are supported by examining the ``envlist`` assignment within ``tox.ini``
-To run **tox**, just execute ``tox`` in the directory where ``tox.ini`` is found.
-If no environments are specified with e.g. ``-e $env1,$env2``, all environments
-will be run. Jenkins will run ``tox`` by executing ``run_tox.sh`` which is under
-``./src/script``.
+Running Tox
+"""""""""""
+To run **tox**, just execute ``tox`` in the directory containing
+``tox.ini``. If you do not specify any environments (for example, ``-e
+$env1,$env2``), then ``tox`` will run all environments. Jenkins will run
+``tox`` by executing ``./src/script/run_tox.sh``.
-Here some examples from the Ceph Dashboard on how to specify
+Here are some examples from Ceph Dashboard that show how to specify different
environments and run options::
## Run Python 2+3 tests+lint commands:
## Run Python 3 tests+lint commands:
$ tox -e py3,lint,check
- ## To run it like Jenkins would do
+ ## To run it as Jenkins would:
$ ../../../script/run_tox.sh --tox-env py27,py3,lint,check
$ ../../../script/run_tox.sh --tox-env py3,lint,check
Currently only doctests_ inside ``mgr_util.py`` are run.
-To add test additional files inside the core of the manager, add
-them at the end of the line that includes ``mgr_util.py`` within ``tox.ini``.
+To add more files to be tested inside the core of the manager, open the
+``tox.ini`` file and add the files to be tested at the end of the line that
+includes ``mgr_util.py``.
.. _doctests: https://docs.python.org/3/library/doctest.html
Unit test caveats
-----------------
-1. Unlike the various Ceph daemons and ``ceph-fuse``, unit tests
- are linked against the default memory allocator (glibc) unless explicitly
- linked against something else. This enables tools like **valgrind** to be used
- in the tests.
+#. Unlike the various Ceph daemons and ``ceph-fuse``, the unit tests are
+ linked against the default memory allocator (glibc) unless they are
+ explicitly linked against something else. This enables tools such as
+ **valgrind** to be used in the tests.
.. _make check:
.. _teuthology framework: https://github.com/ceph/teuthology
projects / ceph.git / commitdiff