1.. SPDX-License-Identifier: GPL-2.0
2
3===========================
4Test Style and Nomenclature
5===========================
6
7To make finding, writing, and using KUnit tests as simple as possible, it is
8strongly encouraged that they are named and written according to the guidelines
9below. 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 run
11automatically 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. For
17   example, non-deterministically producing false positives or negatives, or
18   taking a long time to run.
19
20Subsystems, Suites, and Tests
21=============================
22
23To make tests easy to find, they are grouped into suites and subsystems. A test
24suite is a group of tests which test a related area of the kernel. A subsystem
25is a set of test suites which test different parts of a kernel subsystem
26or a driver.
27
28Subsystems
29----------
30
31Every test suite must belong to a subsystem. A subsystem is a collection of one
32or more KUnit test suites which test the same driver or part of the kernel. A
33test subsystem should match a single kernel module. If the code being tested
34cannot be compiled as a module, in many cases the subsystem should correspond to
35a directory in the source tree or an entry in the ``MAINTAINERS`` file. If
36unsure, follow the conventions set by tests in similar areas.
37
38Test subsystems should be named after the code being tested, either after the
39module (wherever possible), or after the directory or files being tested. Test
40subsystems should be named to avoid ambiguity where necessary.
41
42If a test subsystem name has multiple components, they should be separated by
43underscores. *Do not* include "test" or "kunit" directly in the subsystem name
44unless we are actually testing other tests or the kunit framework itself. For
45example, 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
57Avoid 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
76Suites
77------
78
79KUnit tests are grouped into test suites, which cover a specific area of
80functionality being tested. Test suites can have shared initialization and
81shutdown code which is run for all tests in the suite. Not all subsystems need
82to be split into multiple test suites (for example, simple drivers).
83
84Test suites are named after the subsystem they are part of. If a subsystem
85contains several suites, the specific area under test should be appended to the
86subsystem name, separated by an underscore.
87
88In the event that there are multiple types of test using KUnit within a
89subsystem (for example, both unit tests and integration tests), they should be
90put into separate suites, with the type of test as the last element in the suite
91name. 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 as
95the ``.name`` member of the ``kunit_suite`` struct, and forms the base for the
96module 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
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 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
121Test Cases
122----------
123
124Individual tests consist of a single function which tests a constrained
125codepath, property, or function. In the test output, an individual test's
126results 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 the
129function 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 with
131the 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
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 a
145  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 the
150test name, separated by a colon (i.e. ``suite:test``).
151
152Test Kconfig Entries
153====================
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 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
168If we are not able to meet above conditions (for example, the test is unable to
169be built as a module), Kconfig entries for tests should be tristate.
170
171For 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
188Test File and Module Names
189==========================
190
191KUnit tests can often be compiled as a module. These modules should be named
192after the test suite, followed by ``_test``. If this is likely to conflict with
193non-KUnit tests, the suffix ``_kunit`` can also be used.
194
195The easiest way of achieving this is to name the file containing the test suite
196``<suite>_test.c`` (or, as above, ``<suite>_kunit.c``). This file should be
197placed next to the code under test.
198
199If the suite name contains some or all of the name of the test's parent
200directory, it may make sense to modify the source filename to reduce redundancy.
201For example, a ``foo_firmware`` suite could be in the ``foo/firmware_test.c``
202file.
203