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