214 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3===========================4Test Style and Nomenclature5===========================6 7To make finding, writing, and using KUnit tests as simple as possible, it is8strongly encouraged that they are named and written according to the guidelines9below. While it is possible to write KUnit tests which do not follow these rules,10they may break some tooling, may conflict with other tests, and may not be run11automatically by testing systems.12 13It is recommended that you only deviate from these guidelines when:14 151. Porting tests to KUnit which are already known with an existing name.162. Writing tests which would cause serious problems if automatically run. For17 example, non-deterministically producing false positives or negatives, or18 taking a long time to run.19 20Subsystems, Suites, and Tests21=============================22 23To make tests easy to find, they are grouped into suites and subsystems. A test24suite is a group of tests which test a related area of the kernel. A subsystem25is a set of test suites which test different parts of a kernel subsystem26or a driver.27 28Subsystems29----------30 31Every test suite must belong to a subsystem. A subsystem is a collection of one32or more KUnit test suites which test the same driver or part of the kernel. A33test subsystem should match a single kernel module. If the code being tested34cannot be compiled as a module, in many cases the subsystem should correspond to35a directory in the source tree or an entry in the ``MAINTAINERS`` file. If36unsure, follow the conventions set by tests in similar areas.37 38Test subsystems should be named after the code being tested, either after the39module (wherever possible), or after the directory or files being tested. Test40subsystems should be named to avoid ambiguity where necessary.41 42If a test subsystem name has multiple components, they should be separated by43underscores. *Do not* include "test" or "kunit" directly in the subsystem name44unless we are actually testing other tests or the kunit framework itself. For45example, 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 by55 underscores. Matches the module name.56 57Avoid names as shown in examples below:58 59``linear-ranges``60 Names should use underscores, not dashes, to separate words. Prefer61 ``linear_ranges``.62``qos-kunit-test``63 This name should use underscores, and not have "kunit-test" as a64 suffix. ``qos`` is also ambiguous as a subsystem name, because several parts65 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 also68 be named ``parport_pc``.69 70.. note::71 The KUnit API and tools do not explicitly know about subsystems. They are72 a way of categorizing test suites and naming modules which provides a73 simple, consistent way for humans to find and run tests. This may change74 in the future.75 76Suites77------78 79KUnit tests are grouped into test suites, which cover a specific area of80functionality being tested. Test suites can have shared initialization and81shutdown code which is run for all tests in the suite. Not all subsystems need82to be split into multiple test suites (for example, simple drivers).83 84Test suites are named after the subsystem they are part of. If a subsystem85contains several suites, the specific area under test should be appended to the86subsystem name, separated by an underscore.87 88In the event that there are multiple types of test using KUnit within a89subsystem (for example, both unit tests and integration tests), they should be90put into separate suites, with the type of test as the last element in the suite91name. Unless these tests are actually present, avoid using ``_test``, ``_unittest``92or similar in the suite name.93 94The full test suite name (including the subsystem name) should be specified as95the ``.name`` member of the ``kunit_suite`` struct, and forms the base for the96module 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 as106 the subsystem name.107 108Avoid 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 should116 just be called as ``kasan``. Do not redundantly add117 ``integration_test``. It should be a separate test suite. For example, if the118 unit tests are added, then that suite could be named as ``kasan_unittest`` or119 similar.120 121Test Cases122----------123 124Individual tests consist of a single function which tests a constrained125codepath, property, or function. In the test output, an individual test's126results will show up as subtests of the suite's results.127 128Tests should be named after what they are testing. This is often the name of the129function being tested, with a description of the input or codepath being tested.130As tests are C functions, they should be named and written in accordance with131the kernel coding style.132 133.. note::134 As tests are themselves functions, their names cannot conflict with135 other C identifiers in the kernel. This may require some creative136 naming. It is a good idea to make your test functions `static` to avoid137 polluting the global namespace.138 139Example 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 a145 name conflict with the macro itself.146 147 148Should it be necessary to refer to a test outside the context of its test suite,149the *fully-qualified* name of a test should be the suite name followed by the150test name, separated by a colon (i.e. ``suite:test``).151 152Test Kconfig Entries153====================154 155Every test suite should be tied to a Kconfig entry.156 157This Kconfig entry must:158 159* be named ``CONFIG_<name>_KUNIT_TEST``: where <name> is the name of the test160 suite.161* be listed either alongside the config entries for the driver/subsystem being162 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 168If we are not able to meet above conditions (for example, the test is unable to169be built as a module), Kconfig entries for tests should be tristate.170 171For example, a Kconfig entry might look like:172 173.. code-block:: none174 175 config FOO_KUNIT_TEST176 tristate "KUnit test for foo" if !KUNIT_ALL_TESTS177 depends on KUNIT178 default KUNIT_ALL_TESTS179 help180 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 188Test File and Module Names189==========================190 191KUnit tests are often compiled as a separate module. To avoid conflicting192with regular modules, KUnit modules should be named after the test suite,193followed by ``_kunit`` (e.g. if "foobar" is the core module, then194"foobar_kunit" is the KUnit test module).195 196Test source files, whether compiled as a separate module or an197``#include`` in another source file, are best kept in a ``tests/``198subdirectory to not conflict with other source files (e.g. for199tab-completion).200 201Note that the ``_test`` suffix has also been used in some existing202tests. The ``_kunit`` suffix is preferred, as it makes the distinction203between KUnit and non-KUnit tests clearer.204 205So for the common case, name the file containing the test suite206``tests/<suite>_kunit.c``. The ``tests`` directory should be placed at207the same level as the code under test. For example, tests for208``lib/string.c`` live in ``lib/tests/string_kunit.c``.209 210If the suite name contains some or all of the name of the test's parent211directory, it may make sense to modify the source filename to reduce212redundancy. For example, a ``foo_firmware`` suite could be in the213``foo/tests/firmware_kunit.c`` file.214