This document is for a development version of Ceph.
Testing - unit tests
The Ceph GitHub repository has two types of tests: unit tests (also called
make check tests) and integration tests. Strictly speaking, the
make check tests are not “unit tests”, but rather tests that can be run
easily on a single build machine after compiling Ceph from source, whereas
integration tests require package installation and multi-machine clusters to
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. To be included in
this 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 “make check tests” or “unit tests”. This is meant to distinguish these tests from the more complex “integration tests” that are run via the teuthology framework.
While it is possible to run
ctest directly, it can be tricky to correctly
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:
You will need a minimum of 8GB of RAM and 32GB of free drive space for this 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
functions are used to declare unit tests.
add_ceph_unittest are themselves defined in
Some unit tests are scripts and other unit tests are binaries that are compiled during the build process.
add_ceph_testfunction - used to declare unit test scripts
add_ceph_unittestfunction - 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 tool
called cram via a shell script called
cram tests that are not suitable for
make check can also be run by
teuthology using the cram task.
Tox-based testing of Python modules
Some of the Python modules in Ceph use tox to run their unit tests.
Most of these Python modules can be found in the directory
Currently (December 2020) the following modules use tox:
Ceph Manager Python API (
Python common (
Configuring Tox environments and tasks
Most tox configurations support multiple environments and tasks.
The list of environments and tasks that are supported is in the
envlist. For example, here are the first three lines of
[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:
To run tox, just execute
tox in the directory containing
tox.ini. If you do not specify any environments (for example,
tox will run all environments. Jenkins will run
tox by executing
Here are some examples from Ceph Dashboard that show how to specify different environments 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 only doctests inside
mgr_util.py are run.
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
Unit test caveats
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.
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.g
ceph config set client debug_rbd 20), the debug log file can be found at
build/out/client.admin.<pid>.log. This can also be handy when examining teuthology failed unit test jobs, the job’s debug level can be set at the relevant yaml file.