Notice

This document is for a development version of Ceph.

Testing - unit tests

The Ceph GitHub repository has two types of tests: unit tests (also calledmakecheck tests) and integration tests. Strictly speaking, themakecheck tests are not “unit tests”, but rather tests that can be runeasily on a single build machine after compiling Ceph from source, whereasintegration tests require package installation and multi-machine clusters torun.

What does “make check” mean?

After compiling Ceph, the code can be run through a battery of tests. Forhistorical reasons, this is often referred to asmakecheck even thoughthe actual command used to run the tests is nowctest. To be included inthis group of tests, a test must:

  • bind ports that do not conflict with other tests

  • not require root access

  • not require more than one machine to run

  • complete within a few minutes

For the sake of simplicity, this class of tests is referred to as “makecheck tests” or “unit tests”. This is meant to distinguish these tests fromthe more complex “integration tests” that are run via theteuthologyframework.

While it is possible to runctest directly, it can be tricky to correctlyset up your environment for it. Fortunately, there is a script that makes iteasy to run the unit tests on your code. This script can be run from thetop-level directory of the Ceph source tree by invoking:

./run-make-check.sh

You will need a minimum of 8GB of RAM and 32GB of free drive space for thiscommand to complete successfully on x86_64 architectures; other architecturesmay have different requirements. Depending on your hardware, it can take fromtwenty minutes to three hours to complete.

How unit tests are declared

Unit tests are declared in theCMakeLists.txt file, which is found in the./src directory. Theadd_ceph_test andadd_ceph_unittest CMakefunctions are used to declare unit tests.add_ceph_test andadd_ceph_unittest are themselves defined in./cmake/modules/AddCephTest.cmake.

Some unit tests are scripts and other unit tests are binaries that arecompiled during the build process.

  • add_ceph_test function - used to declare unit test scripts

  • add_ceph_unittest function - used for unit test binaries

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 toolcalledcram via a shell script called./src/test/run-cli-tests.cram tests that are not suitable formakecheck can also be run byteuthology using thecram task.

Tox-based testing of Python modules

Some of the Python modules in Ceph usetoxto run their unit tests.

Most of these Python modules can be found in the directory./src/pybind/.

Currently (December 2020) the following modules usetox:

  • 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

    • ./src/ceph-volume/ceph_volume/tests/functional/batch/tox.ini

    • ./src/ceph-volume/ceph_volume/tests/functional/simple/tox.ini

    • ./src/ceph-volume/ceph_volume/tests/functional/lvm/tox.ini

Configuring Tox environments and tasks

Most tox configurations support multiple environments and tasks.

The list of environments and tasks that are supported is in thetox.inifile, underenvlist. For example, here are the first three lines of./src/cephadm/tox.ini:

[tox]envlist=py3,mypyskipsdist=true

In this example, thePython3 andmypy environments are specified.

The list of environments can be retrieved with the following command:

tox--list

Or:

tox-l

Running Tox

To runtox, just executetox in the directory containingtox.ini. If you do not specify any environments (for example,-e$env1,$env2), thentox will run all environments. Jenkins will runtox by executing./src/script/run_tox.sh.

Here are some examples from Ceph Dashboard that show how to specify differentenvironments and run options:

## Run Python 2+3 tests+lint commands:$ tox -e py27,py3,lint,check## Run Python 3 tests+lint commands:$ tox -e py3,lint,check## To run it as Jenkins would:$ ../../../script/run_tox.sh --tox-env py3,lint,check

Manager core unit tests

Currently onlydoctests insidemgr_util.py are run.

To add more files to be tested inside the core of the manager, open thetox.ini file and add the files to be tested at the end of the line thatincludesmgr_util.py.

Unit test caveats

  1. Unlike the various Ceph daemons andceph-fuse, the unit tests arelinked against the default memory allocator (glibc) unless they areexplicitly linked against something else. This enables tools such asvalgrind to be used in the tests.

  2. Google Test unit testing library hides the client output from the shell.In order to debug the client after setting the desired debug level(e.gcephconfigsetclientdebug_rbd20), the debug log file canbe found atbuild/out/client.admin.<pid>.log.This can also be handy when examining teuthology failed unit testjobs, the job’s debug level can be set at the relevant yaml file.

Brought to you by the Ceph Foundation

The Ceph Documentation is a community resource funded and hosted by the non-profitCeph Foundation. If you would like to support this and our other efforts, please considerjoining now.