1.. SPDX-License-Identifier: GPL-2.0 2 3=============== 4Getting Started 5=============== 6 7Installing Dependencies 8======================= 9KUnit has the same dependencies as the Linux kernel. As long as you can 10build the kernel, you can run KUnit. 11 12Running tests with kunit_tool 13============================= 14kunit_tool is a Python script, which configures and builds a kernel, runs 15tests, and formats the test results. From the kernel repository, you 16can run kunit_tool: 17 18.. code-block:: bash 19 20 ./tools/testing/kunit/kunit.py run 21 22For more information on this wrapper, see: 23Documentation/dev-tools/kunit/run_wrapper.rst. 24 25Creating a ``.kunitconfig`` 26--------------------------- 27 28By default, kunit_tool runs a selection of tests. However, you can specify which 29unit tests to run by creating a ``.kunitconfig`` file with kernel config options 30that enable only a specific set of tests and their dependencies. 31The ``.kunitconfig`` file contains a list of kconfig options which are required 32to run the desired targets. The ``.kunitconfig`` also contains any other test 33specific 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`` 36or ``VFAT_FS``. To run ``FAT_KUNIT_TEST``, the ``.kunitconfig`` has: 37 38.. code-block:: none 39 40 CONFIG_KUNIT=y 41 CONFIG_MSDOS_FS=y 42 CONFIG_FAT_KUNIT_TEST=y 43 441. A good starting point for the ``.kunitconfig``, is the KUnit default 45 config. Run the command: 46 47.. code-block:: bash 48 49 cd $PATH_TO_LINUX_REPO 50 cp tools/testing/kunit/configs/default.config .kunitconfig 51 52.. note :: 53 You may want to remove CONFIG_KUNIT_ALL_TESTS from the ``.kunitconfig`` as 54 it will enable a number of additional tests that you may not want. 55 562. You can then add any other Kconfig options, for example: 57 58.. code-block:: none 59 60 CONFIG_LIST_KUNIT_TEST=y 61 62Before running the tests, kunit_tool ensures that all config options 63set in ``.kunitconfig`` are set in the kernel ``.config``. It will warn 64you if you have not included dependencies for the options used. 65 66.. note :: 67 If you change the ``.kunitconfig``, kunit.py will trigger a rebuild of the 68 ``.config`` file. But you can edit the ``.config`` file directly or with 69 tools like ``make menuconfig O=.kunit``. As long as its a superset of 70 ``.kunitconfig``, kunit.py won't overwrite your changes. 71 72Running Tests (KUnit Wrapper) 73----------------------------- 741. To make sure that everything is set up correctly, invoke the Python 75 wrapper from your kernel repository: 76 77.. code-block:: bash 78 79 ./tools/testing/kunit/kunit.py run 80 81If everything worked correctly, you should see the following: 82 83.. code-block:: 84 85 Generating .config ... 86 Building KUnit Kernel ... 87 Starting KUnit Kernel ... 88 89The tests will pass or fail. 90 91.. note :: 92 Because it is building a lot of sources for the first time, the 93 ``Building KUnit kernel`` may take a while. 94 95Running Tests without the KUnit Wrapper 96======================================= 97If you do not want to use the KUnit Wrapper (for example: you want code 98under test to integrate with other systems, or use a different/ 99unsupported architecture or configuration), KUnit can be included in 100any kernel, and the results are read out and parsed manually. 101 102.. note :: 103 ``CONFIG_KUNIT`` should not be enabled in a production environment. 104 Enabling KUnit disables Kernel Address-Space Layout Randomization 105 (KASLR), and tests may affect the state of the kernel in ways not 106 suitable for production. 107 108Configuring the Kernel 109---------------------- 110To enable KUnit itself, you need to enable the ``CONFIG_KUNIT`` Kconfig 111option (under Kernel Hacking/Kernel Testing and Coverage in 112``menuconfig``). From there, you can enable any KUnit tests. They 113usually have config options ending in ``_KUNIT_TEST``. 114 115KUnit and KUnit tests can be compiled as modules. The tests in a module 116will run when the module is loaded. 117 118Running Tests (without KUnit Wrapper) 119------------------------------------- 120Build and run your kernel. In the kernel log, the test output is printed 121out in the TAP format. This will only happen by default if KUnit/tests 122are built-in. Otherwise the module will need to be loaded. 123 124.. note :: 125 Some lines and/or data may get interspersed in the TAP output. 126 127Writing Your First Test 128======================= 129In your kernel repository, let's add some code that we can test. 130 1311. Create a file ``drivers/misc/example.h``, which includes: 132 133.. code-block:: c 134 135 int misc_example_add(int left, int right); 136 1372. Create a file ``drivers/misc/example.c``, which includes: 138 139.. code-block:: c 140 141 #include <linux/errno.h> 142 143 #include "example.h" 144 145 int misc_example_add(int left, int right) 146 { 147 return left + right; 148 } 149 1503. Add the following lines to ``drivers/misc/Kconfig``: 151 152.. code-block:: kconfig 153 154 config MISC_EXAMPLE 155 bool "My example" 156 1574. Add the following lines to ``drivers/misc/Makefile``: 158 159.. code-block:: make 160 161 obj-$(CONFIG_MISC_EXAMPLE) += example.o 162 163Now we are ready to write the test cases. 164 1651. Add the below test case in ``drivers/misc/example_test.c``: 166 167.. code-block:: c 168 169 #include <kunit/test.h> 170 #include "example.h" 171 172 /* Define the test cases. */ 173 174 static void misc_example_add_test_basic(struct kunit *test) 175 { 176 KUNIT_EXPECT_EQ(test, 1, misc_example_add(1, 0)); 177 KUNIT_EXPECT_EQ(test, 2, misc_example_add(1, 1)); 178 KUNIT_EXPECT_EQ(test, 0, misc_example_add(-1, 1)); 179 KUNIT_EXPECT_EQ(test, INT_MAX, misc_example_add(0, INT_MAX)); 180 KUNIT_EXPECT_EQ(test, -1, misc_example_add(INT_MAX, INT_MIN)); 181 } 182 183 static void misc_example_test_failure(struct kunit *test) 184 { 185 KUNIT_FAIL(test, "This test never passes."); 186 } 187 188 static struct kunit_case misc_example_test_cases[] = { 189 KUNIT_CASE(misc_example_add_test_basic), 190 KUNIT_CASE(misc_example_test_failure), 191 {} 192 }; 193 194 static struct kunit_suite misc_example_test_suite = { 195 .name = "misc-example", 196 .test_cases = misc_example_test_cases, 197 }; 198 kunit_test_suite(misc_example_test_suite); 199 2002. Add the following lines to ``drivers/misc/Kconfig``: 201 202.. code-block:: kconfig 203 204 config MISC_EXAMPLE_TEST 205 tristate "Test for my example" if !KUNIT_ALL_TESTS 206 depends on MISC_EXAMPLE && KUNIT=y 207 default KUNIT_ALL_TESTS 208 2093. Add the following lines to ``drivers/misc/Makefile``: 210 211.. code-block:: make 212 213 obj-$(CONFIG_MISC_EXAMPLE_TEST) += example_test.o 214 2154. Add the following lines to ``.kunitconfig``: 216 217.. code-block:: none 218 219 CONFIG_MISC_EXAMPLE=y 220 CONFIG_MISC_EXAMPLE_TEST=y 221 2225. Run the test: 223 224.. code-block:: bash 225 226 ./tools/testing/kunit/kunit.py run 227 228You should see the following failure: 229 230.. code-block:: none 231 232 ... 233 [16:08:57] [PASSED] misc-example:misc_example_add_test_basic 234 [16:08:57] [FAILED] misc-example:misc_example_test_failure 235 [16:08:57] EXPECTATION FAILED at drivers/misc/example-test.c:17 236 [16:08:57] This test never passes. 237 ... 238 239Congrats! You just wrote your first KUnit test. 240 241Next Steps 242========== 243 244* Documentation/dev-tools/kunit/architecture.rst - KUnit architecture. 245* Documentation/dev-tools/kunit/run_wrapper.rst - run kunit_tool. 246* Documentation/dev-tools/kunit/run_manual.rst - run tests without kunit_tool. 247* Documentation/dev-tools/kunit/usage.rst - write tests. 248* Documentation/dev-tools/kunit/tips.rst - best practices with 249 examples. 250* Documentation/dev-tools/kunit/api/index.rst - KUnit APIs 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. 256