Documentation/dev-tools/kunit/style.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ===========================
   4 Test Style and Nomenclature
   5 ===========================
   6
   7 To make finding, writing, and using KUnit tests as simple as possible, it is
   8 strongly encouraged that they are named and written according to the guidelines
   9 below. While it is possible to write KUnit tests which do not follow these rules,
  10 they may break some tooling, may conflict with other tests, and may not be run
  11 automatically by testing systems.
  12
  13 It is recommended that you only deviate from these guidelines when:
  14
  15 1. Porting tests to KUnit which are already known with an existing name.
  16 2. Writing tests which would cause serious problems if automatically run. For
  17    example, non-deterministically producing false positives or negatives, or
  18    taking a long time to run.
  19
  20 Subsystems, Suites, and Tests
  21 =============================
  22
  23 To make tests easy to find, they are grouped into suites and subsystems. A test
  24 suite is a group of tests which test a related area of the kernel. A subsystem
  25 is a set of test suites which test different parts of a kernel subsystem
  26 or a driver.
  27
  28 Subsystems
  29 ----------
  30
  31 Every test suite must belong to a subsystem. A subsystem is a collection of one
  32 or more KUnit test suites which test the same driver or part of the kernel. A
  33 test subsystem should match a single kernel module. If the code being tested
  34 cannot be compiled as a module, in many cases the subsystem should correspond to
  35 a directory in the source tree or an entry in the ``MAINTAINERS`` file. If
  36 unsure, follow the conventions set by tests in similar areas.
  37
  38 Test subsystems should be named after the code being tested, either after the
  39 module (wherever possible), or after the directory or files being tested. Test
  40 subsystems should be named to avoid ambiguity where necessary.
  41
  42 If a test subsystem name has multiple components, they should be separated by
  43 underscores. *Do not* include "test" or "kunit" directly in the subsystem name
  44 unless we are actually testing other tests or the kunit framework itself. For
  45 example, subsystems could be called:
  46
  47 ``ext4``
  48   Matches the module and filesystem name.
  49 ``apparmor``
  50   Matches the module name and LSM name.
  51 ``kasan``
  52   Common name for the tool, prominent part of the path ``mm/kasan``
  53 ``snd_hda_codec_hdmi``
  54   Has several components (``snd``, ``hda``, ``codec``, ``hdmi``) separated by
  55   underscores. Matches the module name.
  56
  57 Avoid names as shown in examples below:
  58
  59 ``linear-ranges``
  60   Names should use underscores, not dashes, to separate words. Prefer
  61   ``linear_ranges``.
  62 ``qos-kunit-test``
  63   This name should use underscores, and not have "kunit-test" as a
  64   suffix. ``qos`` is also ambiguous as a subsystem name, because several parts
  65   of the kernel have a ``qos`` subsystem. ``power_qos`` would be a better name.
  66 ``pc_parallel_port``
  67   The corresponding module name is ``parport_pc``, so this subsystem should also
  68   be named ``parport_pc``.
  69
  70 .. note::
  71         The KUnit API and tools do not explicitly know about subsystems. They are
  72         a way of categorizing test suites and naming modules which provides a
  73         simple, consistent way for humans to find and run tests. This may change
  74         in the future.
  75
  76 Suites
  77 ------
  78
  79 KUnit tests are grouped into test suites, which cover a specific area of
  80 functionality being tested. Test suites can have shared initialization and
  81 shutdown code which is run for all tests in the suite. Not all subsystems need
  82 to be split into multiple test suites (for example, simple drivers).
  83
  84 Test suites are named after the subsystem they are part of. If a subsystem
  85 contains several suites, the specific area under test should be appended to the
  86 subsystem name, separated by an underscore.
  87
  88 In the event that there are multiple types of test using KUnit within a
  89 subsystem (for example, both unit tests and integration tests), they should be
  90 put into separate suites, with the type of test as the last element in the suite
  91 name. Unless these tests are actually present, avoid using ``_test``, ``_unittest``
  92 or similar in the suite name.
  93
  94 The full test suite name (including the subsystem name) should be specified as
  95 the ``.name`` member of the ``kunit_suite`` struct, and forms the base for the
  96 module name. For example, test suites could include:
  97
  98 ``ext4_inode``
  99   Part of the ``ext4`` subsystem, testing the ``inode`` area.
 100 ``kunit_try_catch``
 101   Part of the ``kunit`` implementation itself, testing the ``try_catch`` area.
 102 ``apparmor_property_entry``
 103   Part of the ``apparmor`` subsystem, testing the ``property_entry`` area.
 104 ``kasan``
 105   The ``kasan`` subsystem has only one suite, so the suite name is the same as
 106   the subsystem name.
 107
 108 Avoid names, for example:
 109
 110 ``ext4_ext4_inode``
 111   There is no reason to state the subsystem twice.
 112 ``property_entry``
 113   The suite name is ambiguous without the subsystem name.
 114 ``kasan_integration_test``
 115   Because there is only one suite in the ``kasan`` subsystem, the suite should
 116   just be called as ``kasan``. Do not redundantly add
 117   ``integration_test``. It should be a separate test suite. For example, if the
 118   unit tests are added, then that suite could be named as ``kasan_unittest`` or
 119   similar.
 120
 121 Test Cases
 122 ----------
 123
 124 Individual tests consist of a single function which tests a constrained
 125 codepath, property, or function. In the test output, an individual test's
 126 results will show up as subtests of the suite's results.
 127
 128 Tests should be named after what they are testing. This is often the name of the
 129 function being tested, with a description of the input or codepath being tested.
 130 As tests are C functions, they should be named and written in accordance with
 131 the kernel coding style.
 132
 133 .. note::
 134         As tests are themselves functions, their names cannot conflict with
 135         other C identifiers in the kernel. This may require some creative
 136         naming. It is a good idea to make your test functions `static` to avoid
 137         polluting the global namespace.
 138
 139 Example test names include:
 140
 141 ``unpack_u32_with_null_name``
 142   Tests the ``unpack_u32`` function when a NULL name is passed in.
 143 ``test_list_splice``
 144   Tests the ``list_splice`` macro. It has the prefix ``test_`` to avoid a
 145   name conflict with the macro itself.
 146
 147
 148 Should it be necessary to refer to a test outside the context of its test suite,
 149 the *fully-qualified* name of a test should be the suite name followed by the
 150 test name, separated by a colon (i.e. ``suite:test``).
 151
 152 Test Kconfig Entries
 153 ====================
 154
 155 Every test suite should be tied to a Kconfig entry.
 156
 157 This Kconfig entry must:
 158
 159 * be named ``CONFIG_<name>_KUNIT_TEST``: where <name> is the name of the test
 160   suite.
 161 * be listed either alongside the config entries for the driver/subsystem being
 162   tested, or be under [Kernel Hacking]->[Kernel Testing and Coverage]
 163 * depend on ``CONFIG_KUNIT``.
 164 * be visible only if ``CONFIG_KUNIT_ALL_TESTS`` is not enabled.
 165 * have a default value of ``CONFIG_KUNIT_ALL_TESTS``.
 166 * have a brief description of KUnit in the help text.
 167
 168 If we are not able to meet above conditions (for example, the test is unable to
 169 be built as a module), Kconfig entries for tests should be tristate.
 170
 171 For example, a Kconfig entry might look like:
 172
 173 .. code-block:: none
 174
 175         config FOO_KUNIT_TEST
 176                 tristate "KUnit test for foo" if !KUNIT_ALL_TESTS
 177                 depends on KUNIT
 178                 default KUNIT_ALL_TESTS
 179                 help
 180                   This builds unit tests for foo.
 181
 182                   For more information on KUnit and unit tests in general,
 183                   please refer to the KUnit documentation in Documentation/dev-tools/kunit/.
 184
 185                   If unsure, say N.
 186
 187
 188 Test File and Module Names
 189 ==========================
 190
 191 KUnit tests are often compiled as a separate module. To avoid conflicting
 192 with regular modules, KUnit modules should be named after the test suite,
 193 followed by ``_kunit`` (e.g. if "foobar" is the core module, then
 194 "foobar_kunit" is the KUnit test module).
 195
 196 Test source files, whether compiled as a separate module or an
 197 ``#include`` in another source file, are best kept in a ``tests/``
 198 subdirectory to not conflict with other source files (e.g. for
 199 tab-completion).
 200
 201 Note that the ``_test`` suffix has also been used in some existing
 202 tests. The ``_kunit`` suffix is preferred, as it makes the distinction
 203 between KUnit and non-KUnit tests clearer.
 204
 205 So for the common case, name the file containing the test suite
 206 ``tests/<suite>_kunit.c``. The ``tests`` directory should be placed at
 207 the same level as the code under test. For example, tests for
 208 ``lib/string.c`` live in ``lib/tests/string_kunit.c``.
 209
 210 If the suite name contains some or all of the name of the test's parent
 211 directory, it may make sense to modify the source filename to reduce
 212 redundancy. For example, a ``foo_firmware`` suite could be in the
 213 ``foo/tests/firmware_kunit.c`` file.