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 !! 7 Installing dependencies
8 teaching how to run existing tests and then ho <<
9 and covers common problems users face when usi <<
10 <<
11 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 build
14 build the kernel, you can run KUnit. !! 10 the kernel, you can run KUnit.
>> 11
>> 12 Running tests with the KUnit Wrapper
>> 13 ====================================
>> 14 Included with KUnit is a simple Python wrapper which runs tests under User Mode
>> 15 Linux, and formats the test results.
15 16
16 Running tests with kunit_tool !! 17 The wrapper can be run with:
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 18
22 .. code-block:: bash 19 .. code-block:: bash
23 20
24 ./tools/testing/kunit/kunit.py run 21 ./tools/testing/kunit/kunit.py run
25 22
26 .. note :: !! 23 For more information on this wrapper (also called kunit_tool) check out the
27 You may see the following error: !! 24 Documentation/dev-tools/kunit/kunit-tool.rst page.
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 25
62 By default, kunit_tool runs all tests reachabl !! 26 Creating a .kunitconfig
63 that is, using default values for most of the !! 27 -----------------------
64 you can select which tests to run by: !! 28 If you want to run a specific set of tests (rather than those listed in the
>> 29 KUnit defconfig), you can provide Kconfig options in the ``.kunitconfig`` file.
>> 30 This file essentially contains the regular Kernel config, with the specific
>> 31 test targets as well. The ``.kunitconfig`` should also contain any other config
>> 32 options required by the tests.
65 33
66 - `Customizing Kconfig`_ used to compile the k !! 34 A good starting point for a ``.kunitconfig`` is the KUnit defconfig:
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 35
74 .. code-block:: bash 36 .. code-block:: bash
75 37
76 cd $PATH_TO_LINUX_REPO 38 cd $PATH_TO_LINUX_REPO
77 tools/testing/kunit/kunit.py config !! 39 cp tools/testing/kunit/configs/default.config .kunitconfig
78 cat .kunit/.kunitconfig <<
79 40
80 .. note :: !! 41 You can then add any other Kconfig options you wish, e.g.:
81 ``.kunitconfig`` lives in the ``--build_dir <<
82 ``.kunit`` by default. <<
83 42
84 Before running the tests, kunit_tool ensures t !! 43 .. code-block:: none
85 set in ``.kunitconfig`` are set in the kernel <<
86 you if you have not included dependencies for <<
87 44
88 There are many ways to customize the configura !! 45 CONFIG_LIST_KUNIT_TEST=y
89 46
90 a. Edit ``.kunit/.kunitconfig``. The file shou !! 47 :doc:`kunit_tool <kunit-tool>` will ensure that all config options set in
91 options required to run the desired tests, !! 48 ``.kunitconfig`` are set in the kernel ``.config`` before running the tests.
92 You may want to remove CONFIG_KUNIT_ALL_TES !! 49 It'll warn you if you haven't included the dependencies of the options you're
93 it will enable a number of additional tests !! 50 using.
94 If you need to run on an architecture other <<
95 51
96 b. Enable additional kconfig options on top of !! 52 .. note::
97 For example, to include the kernel's linked !! 53 Note that removing something from the ``.kunitconfig`` will not trigger a
>> 54 rebuild of the ``.config`` file: the configuration is only updated if the
>> 55 ``.kunitconfig`` is not a subset of ``.config``. This means that you can use
>> 56 other tools (such as make menuconfig) to adjust other config options.
98 57
99 ./tools/testing/kunit/kunit.py run \ <<
100 --kconfig_add CONFIG_LIST_KUNI <<
101 58
102 c. Provide the path of one or more .kunitconfi !! 59 Running the tests (KUnit Wrapper)
103 For example, to run only ``FAT_FS`` and ``E !! 60 ---------------------------------
104 61
105 ./tools/testing/kunit/kunit.py run \ !! 62 To make sure that everything is set up correctly, simply invoke the Python
106 --kunitconfig ./fs/fat/.kunitc !! 63 wrapper from your kernel repo:
107 --kunitconfig ./fs/ext4/.kunit <<
108 64
109 d. If you change the ``.kunitconfig``, kunit.p !! 65 .. code-block:: bash
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 66
>> 67 ./tools/testing/kunit/kunit.py run
114 68
115 .. note :: !! 69 .. note::
>> 70 You may want to run ``make mrproper`` first.
116 71
117 To save a .kunitconfig after finding a !! 72 If everything worked correctly, you should see the following:
118 73
119 make savedefconfig O=.kunit !! 74 .. code-block:: bash
120 cp .kunit/defconfig .kunit/.ku <<
121 75
122 Filtering tests by name !! 76 Generating .config ...
123 ~~~~~~~~~~~~~~~~~~~~~~~ !! 77 Building KUnit Kernel ...
124 If you want to be more specific than Kconfig c !! 78 Starting KUnit Kernel ...
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 79
132 a. inform the name of a test suite, like ``"ku !! 80 followed by a list of tests that are run. All of them should be passing.
133 to run every test case it contains:: <<
134 81
135 ./tools/testing/kunit/kunit.py run "ku !! 82 .. note::
>> 83 Because it is building a lot of sources for the first time, the
>> 84 ``Building KUnit kernel`` step may take a while.
136 85
137 b. inform the name of a test case prefixed by !! 86 Running tests without the KUnit Wrapper
138 like ``"example.example_simple_test"``, to !! 87 =======================================
139 88
140 ./tools/testing/kunit/kunit.py run "ex !! 89 If you'd rather not use the KUnit Wrapper (if, for example, you need to
>> 90 integrate with other systems, or use an architecture other than UML), KUnit can
>> 91 be included in any kernel, and the results read out and parsed manually.
141 92
142 c. use wildcard characters (``*?[``) to run an !! 93 .. note::
143 like ``"*.*64*"`` to run test cases contain !! 94 KUnit is not designed for use in a production system, and it's possible that
144 any test suite:: !! 95 tests may reduce the stability or security of the system.
145 96
146 ./tools/testing/kunit/kunit.py run "*. <<
147 97
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 98
161 Configuring the Kernel !! 99 Configuring the kernel
162 ---------------------- 100 ----------------------
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 101
168 KUnit and KUnit tests can be compiled as modul !! 102 In order to enable KUnit itself, you simply need to enable the ``CONFIG_KUNIT``
169 will run when the module is loaded. !! 103 Kconfig option (it's under Kernel Hacking/Kernel Testing and Coverage in
>> 104 menuconfig). From there, you can enable any KUnit tests you want: they usually
>> 105 have config options ending in ``_KUNIT_TEST``.
>> 106
>> 107 KUnit and KUnit tests can be compiled as modules: in this case the tests in a
>> 108 module will be run when the module is loaded.
>> 109
170 110
171 Running Tests (without KUnit Wrapper) !! 111 Running the tests (w/o KUnit Wrapper)
172 ------------------------------------- 112 -------------------------------------
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 113
177 .. note :: !! 114 Build and run your kernel as usual. Test output will be written to the kernel
178 Some lines and/or data may get interspersed !! 115 log in `TAP <https://testanything.org/>`_ format.
179 116
180 Writing Your First Test !! 117 .. note::
>> 118 It's possible that there will be other lines and/or data interspersed in the
>> 119 TAP output.
>> 120
>> 121
>> 122 Writing your first test
181 ======================= 123 =======================
182 In your kernel repository, let's add some code <<
183 124
184 1. Create a file ``drivers/misc/example.h``, w !! 125 In your kernel repo let's add some code that we can test. Create a file
>> 126 ``drivers/misc/example.h`` with the contents:
185 127
186 .. code-block:: c 128 .. code-block:: c
187 129
188 int misc_example_add(int left, int rig 130 int misc_example_add(int left, int right);
189 131
190 2. Create a file ``drivers/misc/example.c``, w !! 132 create a file ``drivers/misc/example.c``:
191 133
192 .. code-block:: c 134 .. code-block:: c
193 135
194 #include <linux/errno.h> 136 #include <linux/errno.h>
195 137
196 #include "example.h" 138 #include "example.h"
197 139
198 int misc_example_add(int left, int rig 140 int misc_example_add(int left, int right)
199 { 141 {
200 return left + right; 142 return left + right;
201 } 143 }
202 144
203 3. Add the following lines to ``drivers/misc/K !! 145 Now add the following lines to ``drivers/misc/Kconfig``:
204 146
205 .. code-block:: kconfig 147 .. code-block:: kconfig
206 148
207 config MISC_EXAMPLE 149 config MISC_EXAMPLE
208 bool "My example" 150 bool "My example"
209 151
210 4. Add the following lines to ``drivers/misc/M !! 152 and the following lines to ``drivers/misc/Makefile``:
211 153
212 .. code-block:: make 154 .. code-block:: make
213 155
214 obj-$(CONFIG_MISC_EXAMPLE) += example. 156 obj-$(CONFIG_MISC_EXAMPLE) += example.o
215 157
216 Now we are ready to write the test cases. !! 158 Now we are ready to write the test. The test will be in
217 !! 159 ``drivers/misc/example-test.c``:
218 1. Add the below test case in ``drivers/misc/e <<
219 160
220 .. code-block:: c 161 .. code-block:: c
221 162
222 #include <kunit/test.h> 163 #include <kunit/test.h>
223 #include "example.h" 164 #include "example.h"
224 165
225 /* Define the test cases. */ 166 /* Define the test cases. */
226 167
227 static void misc_example_add_test_basi 168 static void misc_example_add_test_basic(struct kunit *test)
228 { 169 {
229 KUNIT_EXPECT_EQ(test, 1, misc_ 170 KUNIT_EXPECT_EQ(test, 1, misc_example_add(1, 0));
230 KUNIT_EXPECT_EQ(test, 2, misc_ 171 KUNIT_EXPECT_EQ(test, 2, misc_example_add(1, 1));
231 KUNIT_EXPECT_EQ(test, 0, misc_ 172 KUNIT_EXPECT_EQ(test, 0, misc_example_add(-1, 1));
232 KUNIT_EXPECT_EQ(test, INT_MAX, 173 KUNIT_EXPECT_EQ(test, INT_MAX, misc_example_add(0, INT_MAX));
233 KUNIT_EXPECT_EQ(test, -1, misc 174 KUNIT_EXPECT_EQ(test, -1, misc_example_add(INT_MAX, INT_MIN));
234 } 175 }
235 176
236 static void misc_example_test_failure( 177 static void misc_example_test_failure(struct kunit *test)
237 { 178 {
238 KUNIT_FAIL(test, "This test ne 179 KUNIT_FAIL(test, "This test never passes.");
239 } 180 }
240 181
241 static struct kunit_case misc_example_ 182 static struct kunit_case misc_example_test_cases[] = {
242 KUNIT_CASE(misc_example_add_te 183 KUNIT_CASE(misc_example_add_test_basic),
243 KUNIT_CASE(misc_example_test_f 184 KUNIT_CASE(misc_example_test_failure),
244 {} 185 {}
245 }; 186 };
246 187
247 static struct kunit_suite misc_example 188 static struct kunit_suite misc_example_test_suite = {
248 .name = "misc-example", 189 .name = "misc-example",
249 .test_cases = misc_example_tes 190 .test_cases = misc_example_test_cases,
250 }; 191 };
251 kunit_test_suite(misc_example_test_sui 192 kunit_test_suite(misc_example_test_suite);
252 193
253 MODULE_LICENSE("GPL"); !! 194 Now add the following to ``drivers/misc/Kconfig``:
254 <<
255 2. Add the following lines to ``drivers/misc/K <<
256 195
257 .. code-block:: kconfig 196 .. code-block:: kconfig
258 197
259 config MISC_EXAMPLE_TEST 198 config MISC_EXAMPLE_TEST
260 tristate "Test for my example" 199 tristate "Test for my example" if !KUNIT_ALL_TESTS
261 depends on MISC_EXAMPLE && KUN !! 200 depends on MISC_EXAMPLE && KUNIT=y
262 default KUNIT_ALL_TESTS 201 default KUNIT_ALL_TESTS
263 202
264 Note: If your test does not support being buil !! 203 and the following to ``drivers/misc/Makefile``:
265 discouraged), replace tristate by bool, and de <<
266 <<
267 3. Add the following lines to ``drivers/misc/M <<
268 204
269 .. code-block:: make 205 .. code-block:: make
270 206
271 obj-$(CONFIG_MISC_EXAMPLE_TEST) += exa !! 207 obj-$(CONFIG_MISC_EXAMPLE_TEST) += example-test.o
272 208
273 4. Add the following lines to ``.kunit/.kunitc !! 209 Now add it to your ``.kunitconfig``:
274 210
275 .. code-block:: none 211 .. code-block:: none
276 212
277 CONFIG_MISC_EXAMPLE=y 213 CONFIG_MISC_EXAMPLE=y
278 CONFIG_MISC_EXAMPLE_TEST=y 214 CONFIG_MISC_EXAMPLE_TEST=y
279 215
280 5. Run the test: !! 216 Now you can run the test:
281 217
282 .. code-block:: bash 218 .. code-block:: bash
283 219
284 ./tools/testing/kunit/kunit.py run 220 ./tools/testing/kunit/kunit.py run
285 221
286 You should see the following failure: 222 You should see the following failure:
287 223
288 .. code-block:: none 224 .. code-block:: none
289 225
290 ... 226 ...
291 [16:08:57] [PASSED] misc-example:misc_ 227 [16:08:57] [PASSED] misc-example:misc_example_add_test_basic
292 [16:08:57] [FAILED] misc-example:misc_ 228 [16:08:57] [FAILED] misc-example:misc_example_test_failure
293 [16:08:57] EXPECTATION FAILED at drive 229 [16:08:57] EXPECTATION FAILED at drivers/misc/example-test.c:17
294 [16:08:57] This test never passes !! 230 [16:08:57] This test never passes.
295 ... 231 ...
296 232
297 Congrats! You just wrote your first KUnit test !! 233 Congrats! You just wrote your first KUnit test!
298 234
299 Next Steps 235 Next Steps
300 ========== 236 ==========
301 !! 237 * Check out the Documentation/dev-tools/kunit/tips.rst page for tips on
302 If you're interested in using some of the more !! 238 writing idiomatic KUnit tests.
303 take a look at Documentation/dev-tools/kunit/r !! 239 * Check out the :doc:`running_tips` page for tips on
304 !! 240 how to make running KUnit tests easier.
305 If you'd like to run tests without using kunit !! 241 * Optional: see the :doc:`usage` page for a more
306 Documentation/dev-tools/kunit/run_manual.rst !! 242 in-depth explanation of KUnit.
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.