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