From: Anthony D'Atri Date: Mon, 16 Nov 2020 00:20:21 +0000 (-0800) Subject: doc/dev/developer_guide: verb disagreement on "Testing: Unit Tests" page X-Git-Tag: v16.1.0~482^2~1 X-Git-Url: http://git-server-git.apps.pok.os.sepia.ceph.com/?a=commitdiff_plain;h=73435185a364df1dbcb25ba820a40f27c7863d9c;p=ceph.git doc/dev/developer_guide: verb disagreement on "Testing: Unit Tests" page Signed-off-by: Anthony D'Atri Fixes: https://tracker.ceph.com/issues/46367 --- diff --git a/doc/dev/developer_guide/tests-unit-tests.rst b/doc/dev/developer_guide/tests-unit-tests.rst index 06a9d063dac3..ddbee16dfc37 100644 --- a/doc/dev/developer_guide/tests-unit-tests.rst +++ b/doc/dev/developer_guide/tests-unit-tests.rst @@ -1,21 +1,22 @@ Testing - unit tests ==================== -Ceph 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 packages -and multi-machine clusters to run. +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 +run. .. _make-check: What does "make check" mean? ---------------------------- -After compiling Ceph, the code can be run through a battery of tests covering -various aspects of Ceph. For historical reasons, this battery of tests is +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 battery of tests, a test +the tests is now ``ctest``. For inclusion in this group of tests, a test must: * bind ports that do not conflict with other tests @@ -30,14 +31,13 @@ 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. 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 doing:: +the Ceph source tree by invoking:: $ ./run-make-check.sh - -You will need a minimum of 8GB of RAM and 32GB of free disk space for this -command to complete successfully on x86_64 (other architectures may have -different constraints). Depending on your hardware, it can take from 20 +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 twendy minutes to three hours to complete, but it's worth the wait. How unit tests are declared @@ -71,10 +71,10 @@ Most python modules can be found under ``./src/pybind/``. Many modules use **tox** to run their unit tests. **tox** itself is a generic virtualenv management and test command line tool. -To find out quickly if tox can be run you can either just try to run ``tox`` -or find out if a ``tox.ini`` exists. +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. -Currently the following modules use tox: +Currently the following modules use **tox**: - Cephadm (``./src/pybind/mgr/cephadm``) - Insights (``./src/pybind/mgr/insights``) @@ -83,15 +83,14 @@ Currently the following modules use tox: - Python common (``./src/python-common/tox.ini``) -Most tox configuration support multiple environments and tasks. You can see -which environments and tasks are supported by looking into the ``tox.ini`` -file to see what ``envlist`` is assigned. -To run **tox**, just execute ``tox`` in the directory where ``tox.ini`` lies. -Without any specified environments ``-e $env1,$env2``, all environments will -be run. Jenkins will run ``tox`` by executing ``run_tox.sh`` which lies under +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``. -Here some examples from ceph dashboard on how to specify different +Here some examples from the Ceph Dashboard on how to specify environments and run options:: ## Run Python 2+3 tests+lint commands: @@ -109,17 +108,17 @@ Manager core unit tests Currently only doctests_ inside ``mgr_util.py`` are run. -To add more files that should be tested inside the core of the manager add -them at the end of the line that includes ``mgr_util.py`` inside ``tox.ini``. +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``. .. _doctests: https://docs.python.org/3/library/doctest.html Unit test caveats ----------------- -1. Unlike the various Ceph daemons and ``ceph-fuse``, the unit tests +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 + linked against something else. This enables tools like **valgrind** to be used in the tests. .. _make check: