1 .. SPDX-License-Identifier: GPL-2.0
2
3 ===============
4 Getting Started
5 ===============
6
7 This page contains an overview of the kunit_to
8 teaching how to run existing tests and then ho
9 and covers common problems users face when usi
10
11 Installing Dependencies
12 =======================
13 KUnit has the same dependencies as the Linux k
14 build the kernel, you can run KUnit.
15
16 Running tests with kunit_tool
17 =============================
18 kunit_tool is a Python script, which configure
19 tests, and formats the test results. From the
20 can run kunit_tool:
21
22 .. code-block:: bash
23
24 ./tools/testing/kunit/kunit.py run
25
26 .. note ::
27 You may see the following error:
28 "The source tree is not clean, please
29
30 This happens because internally kunit.
31 (default option) as the build director
32 through the argument ``--build_dir``.
33 out-of-tree build, the source tree mus
34
35 There is also the same caveat mentione
36 the kernel" section of the :doc:`admin
37 that is, its use, it must be used for
38 The good news is that it can indeed be
39 ``make ARCH=um mrproper``, just be awa
40 current configuration and all generate
41
42 If everything worked correctly, you should see
43
44 .. code-block::
45
46 Configuring KUnit Kernel ...
47 Building KUnit Kernel ...
48 Starting KUnit Kernel ...
49
50 The tests will pass or fail.
51
52 .. note ::
53 Because it is building a lot of sources for
54 the ``Building KUnit Kernel`` step may take
55
56 For detailed information on this wrapper, see:
57 Documentation/dev-tools/kunit/run_wrapper.rst.
58
59 Selecting which tests to run
60 ----------------------------
61
62 By default, kunit_tool runs all tests reachabl
63 that is, using default values for most of the
64 you can select which tests to run by:
65
66 - `Customizing Kconfig`_ used to compile the k
67 - `Filtering tests by name`_ to select specifi
68
69 Customizing Kconfig
70 ~~~~~~~~~~~~~~~~~~~
71 A good starting point for the ``.kunitconfig``
72 If you didn't run ``kunit.py run`` yet, you ca
73
74 .. code-block:: bash
75
76 cd $PATH_TO_LINUX_REPO
77 tools/testing/kunit/kunit.py config
78 cat .kunit/.kunitconfig
79
80 .. note ::
81 ``.kunitconfig`` lives in the ``--build_dir
82 ``.kunit`` by default.
83
84 Before running the tests, kunit_tool ensures t
85 set in ``.kunitconfig`` are set in the kernel
86 you if you have not included dependencies for
87
88 There are many ways to customize the configura
89
90 a. Edit ``.kunit/.kunitconfig``. The file shou
91 options required to run the desired tests,
92 You may want to remove CONFIG_KUNIT_ALL_TES
93 it will enable a number of additional tests
94 If you need to run on an architecture other
95
96 b. Enable additional kconfig options on top of
97 For example, to include the kernel's linked
98
99 ./tools/testing/kunit/kunit.py run \
100 --kconfig_add CONFIG_LIST_KUNI
101
102 c. Provide the path of one or more .kunitconfi
103 For example, to run only ``FAT_FS`` and ``E
104
105 ./tools/testing/kunit/kunit.py run \
106 --kunitconfig ./fs/fat/.kunitc
107 --kunitconfig ./fs/ext4/.kunit
108
109 d. If you change the ``.kunitconfig``, kunit.p
110 ``.config`` file. But you can edit the ``.c
111 tools like ``make menuconfig O=.kunit``. As
112 ``.kunitconfig``, kunit.py won't overwrite
113
114
115 .. note ::
116
117 To save a .kunitconfig after finding a
118
119 make savedefconfig O=.kunit
120 cp .kunit/defconfig .kunit/.ku
121
122 Filtering tests by name
123 ~~~~~~~~~~~~~~~~~~~~~~~
124 If you want to be more specific than Kconfig c
125 to select which tests to execute at boot-time
126 (read instructions regarding the pattern in th
127 If there is a ``"."`` (period) in the filter,
128 separator between the name of the test suite a
129 otherwise, it will be interpreted as the name
130 For example, let's assume we are using the def
131
132 a. inform the name of a test suite, like ``"ku
133 to run every test case it contains::
134
135 ./tools/testing/kunit/kunit.py run "ku
136
137 b. inform the name of a test case prefixed by
138 like ``"example.example_simple_test"``, to
139
140 ./tools/testing/kunit/kunit.py run "ex
141
142 c. use wildcard characters (``*?[``) to run an
143 like ``"*.*64*"`` to run test cases contain
144 any test suite::
145
146 ./tools/testing/kunit/kunit.py run "*.
147
148 Running Tests without the KUnit Wrapper
149 =======================================
150 If you do not want to use the KUnit Wrapper (f
151 under test to integrate with other systems, or
152 unsupported architecture or configuration), KU
153 any kernel, and the results are read out and p
154
155 .. note ::
156 ``CONFIG_KUNIT`` should not be enabled in a
157 Enabling KUnit disables Kernel Address-Spac
158 (KASLR), and tests may affect the state of
159 suitable for production.
160
161 Configuring the Kernel
162 ----------------------
163 To enable KUnit itself, you need to enable the
164 option (under Kernel Hacking/Kernel Testing an
165 ``menuconfig``). From there, you can enable an
166 usually have config options ending in ``_KUNIT
167
168 KUnit and KUnit tests can be compiled as modul
169 will run when the module is loaded.
170
171 Running Tests (without KUnit Wrapper)
172 -------------------------------------
173 Build and run your kernel. In the kernel log,
174 out in the TAP format. This will only happen b
175 are built-in. Otherwise the module will need t
176
177 .. note ::
178 Some lines and/or data may get interspersed
179
180 Writing Your First Test
181 =======================
182 In your kernel repository, let's add some code
183
184 1. Create a file ``drivers/misc/example.h``, w
185
186 .. code-block:: c
187
188 int misc_example_add(int left, int rig
189
190 2. Create a file ``drivers/misc/example.c``, w
191
192 .. code-block:: c
193
194 #include <linux/errno.h>
195
196 #include "example.h"
197
198 int misc_example_add(int left, int rig
199 {
200 return left + right;
201 }
202
203 3. Add the following lines to ``drivers/misc/K
204
205 .. code-block:: kconfig
206
207 config MISC_EXAMPLE
208 bool "My example"
209
210 4. Add the following lines to ``drivers/misc/M
211
212 .. code-block:: make
213
214 obj-$(CONFIG_MISC_EXAMPLE) += example.
215
216 Now we are ready to write the test cases.
217
218 1. Add the below test case in ``drivers/misc/e
219
220 .. code-block:: c
221
222 #include <kunit/test.h>
223 #include "example.h"
224
225 /* Define the test cases. */
226
227 static void misc_example_add_test_basi
228 {
229 KUNIT_EXPECT_EQ(test, 1, misc_
230 KUNIT_EXPECT_EQ(test, 2, misc_
231 KUNIT_EXPECT_EQ(test, 0, misc_
232 KUNIT_EXPECT_EQ(test, INT_MAX,
233 KUNIT_EXPECT_EQ(test, -1, misc
234 }
235
236 static void misc_example_test_failure(
237 {
238 KUNIT_FAIL(test, "This test ne
239 }
240
241 static struct kunit_case misc_example_
242 KUNIT_CASE(misc_example_add_te
243 KUNIT_CASE(misc_example_test_f
244 {}
245 };
246
247 static struct kunit_suite misc_example
248 .name = "misc-example",
249 .test_cases = misc_example_tes
250 };
251 kunit_test_suite(misc_example_test_sui
252
253 MODULE_LICENSE("GPL");
254
255 2. Add the following lines to ``drivers/misc/K
256
257 .. code-block:: kconfig
258
259 config MISC_EXAMPLE_TEST
260 tristate "Test for my example"
261 depends on MISC_EXAMPLE && KUN
262 default KUNIT_ALL_TESTS
263
264 Note: If your test does not support being buil
265 discouraged), replace tristate by bool, and de
266
267 3. Add the following lines to ``drivers/misc/M
268
269 .. code-block:: make
270
271 obj-$(CONFIG_MISC_EXAMPLE_TEST) += exa
272
273 4. Add the following lines to ``.kunit/.kunitc
274
275 .. code-block:: none
276
277 CONFIG_MISC_EXAMPLE=y
278 CONFIG_MISC_EXAMPLE_TEST=y
279
280 5. Run the test:
281
282 .. code-block:: bash
283
284 ./tools/testing/kunit/kunit.py run
285
286 You should see the following failure:
287
288 .. code-block:: none
289
290 ...
291 [16:08:57] [PASSED] misc-example:misc_
292 [16:08:57] [FAILED] misc-example:misc_
293 [16:08:57] EXPECTATION FAILED at drive
294 [16:08:57] This test never passes
295 ...
296
297 Congrats! You just wrote your first KUnit test
298
299 Next Steps
300 ==========
301
302 If you're interested in using some of the more
303 take a look at Documentation/dev-tools/kunit/r
304
305 If you'd like to run tests without using kunit
306 Documentation/dev-tools/kunit/run_manual.rst
307
308 For more information on writing KUnit tests (i
309 for testing different things), see Documentati
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.