1 .. SPDX-License-Identifier: GPL-2.0
2
3 ===========================
4 Test Style and Nomenclature
5 ===========================
6
7 To make finding, writing, and using KUnit test
8 strongly encouraged that they are named and wr
9 below. While it is possible to write KUnit tes
10 they may break some tooling, may conflict with
11 automatically by testing systems.
12
13 It is recommended that you only deviate from t
14
15 1. Porting tests to KUnit which are already kn
16 2. Writing tests which would cause serious pro
17 example, non-deterministically producing fa
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 i
24 suite is a group of tests which test a related
25 is a set of test suites which test different p
26 or a driver.
27
28 Subsystems
29 ----------
30
31 Every test suite must belong to a subsystem. A
32 or more KUnit test suites which test the same
33 test subsystem should match a single kernel mo
34 cannot be compiled as a module, in many cases
35 a directory in the source tree or an entry in
36 unsure, follow the conventions set by tests in
37
38 Test subsystems should be named after the code
39 module (wherever possible), or after the direc
40 subsystems should be named to avoid ambiguity
41
42 If a test subsystem name has multiple componen
43 underscores. *Do not* include "test" or "kunit
44 unless we are actually testing other tests or
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
53 ``snd_hda_codec_hdmi``
54 Has several components (``snd``, ``hda``, ``
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
61 ``linear_ranges``.
62 ``qos-kunit-test``
63 This name should use underscores, and not ha
64 suffix. ``qos`` is also ambiguous as a subsy
65 of the kernel have a ``qos`` subsystem. ``po
66 ``pc_parallel_port``
67 The corresponding module name is ``parport_p
68 be named ``parport_pc``.
69
70 .. note::
71 The KUnit API and tools do not explici
72 a way of categorizing test suites and
73 simple, consistent way for humans to f
74 in the future.
75
76 Suites
77 ------
78
79 KUnit tests are grouped into test suites, whic
80 functionality being tested. Test suites can ha
81 shutdown code which is run for all tests in th
82 to be split into multiple test suites (for exa
83
84 Test suites are named after the subsystem they
85 contains several suites, the specific area und
86 subsystem name, separated by an underscore.
87
88 In the event that there are multiple types of
89 subsystem (for example, both unit tests and in
90 put into separate suites, with the type of tes
91 name. Unless these tests are actually present,
92 or similar in the suite name.
93
94 The full test suite name (including the subsys
95 the ``.name`` member of the ``kunit_suite`` st
96 module name. For example, test suites could in
97
98 ``ext4_inode``
99 Part of the ``ext4`` subsystem, testing the
100 ``kunit_try_catch``
101 Part of the ``kunit`` implementation itself,
102 ``apparmor_property_entry``
103 Part of the ``apparmor`` subsystem, testing
104 ``kasan``
105 The ``kasan`` subsystem has only one suite,
106 the subsystem name.
107
108 Avoid names, for example:
109
110 ``ext4_ext4_inode``
111 There is no reason to state the subsystem tw
112 ``property_entry``
113 The suite name is ambiguous without the subs
114 ``kasan_integration_test``
115 Because there is only one suite in the ``kas
116 just be called as ``kasan``. Do not redundan
117 ``integration_test``. It should be a separat
118 unit tests are added, then that suite could
119 similar.
120
121 Test Cases
122 ----------
123
124 Individual tests consist of a single function
125 codepath, property, or function. In the test o
126 results will show up as subtests of the suite'
127
128 Tests should be named after what they are test
129 function being tested, with a description of t
130 As tests are C functions, they should be named
131 the kernel coding style.
132
133 .. note::
134 As tests are themselves functions, the
135 other C identifiers in the kernel. Thi
136 naming. It is a good idea to make your
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 NUL
143 ``test_list_splice``
144 Tests the ``list_splice`` macro. It has the
145 name conflict with the macro itself.
146
147
148 Should it be necessary to refer to a test outs
149 the *fully-qualified* name of a test should be
150 test name, separated by a colon (i.e. ``suite:
151
152 Test Kconfig Entries
153 ====================
154
155 Every test suite should be tied to a Kconfig e
156
157 This Kconfig entry must:
158
159 * be named ``CONFIG_<name>_KUNIT_TEST``: where
160 suite.
161 * be listed either alongside the config entrie
162 tested, or be under [Kernel Hacking]->[Kerne
163 * depend on ``CONFIG_KUNIT``.
164 * be visible only if ``CONFIG_KUNIT_ALL_TESTS`
165 * have a default value of ``CONFIG_KUNIT_ALL_T
166 * have a brief description of KUnit in the hel
167
168 If we are not able to meet above conditions (f
169 be built as a module), Kconfig entries for tes
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"
177 depends on KUNIT
178 default KUNIT_ALL_TESTS
179 help
180 This builds unit tests for f
181
182 For more information on KUni
183 please refer to the KUnit do
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 m
192 with regular modules, KUnit modules should be
193 followed by ``_kunit`` (e.g. if "foobar" is th
194 "foobar_kunit" is the KUnit test module).
195
196 Test source files, whether compiled as a separ
197 ``#include`` in another source file, are best
198 subdirectory to not conflict with other source
199 tab-completion).
200
201 Note that the ``_test`` suffix has also been u
202 tests. The ``_kunit`` suffix is preferred, as
203 between KUnit and non-KUnit tests clearer.
204
205 So for the common case, name the file containi
206 ``tests/<suite>_kunit.c``. The ``tests`` direc
207 the same level as the code under test. For exa
208 ``lib/string.c`` live in ``lib/tests/string_ku
209
210 If the suite name contains some or all of the
211 directory, it may make sense to modify the sou
212 redundancy. For example, a ``foo_firmware`` su
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.