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