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