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 config. 45 You can generate it by running: 46 47.. code-block:: bash 48 49 cd $PATH_TO_LINUX_REPO 50 tools/testing/kunit/kunit.py config 51 cat .kunit/.kunitconfig 52 53.. note :: 54 ``.kunitconfig`` lives in the ``--build_dir`` used by kunit.py, which is 55 ``.kunit`` by default. 56 57.. note :: 58 You may want to remove CONFIG_KUNIT_ALL_TESTS from the ``.kunitconfig`` as 59 it will enable a number of additional tests that you may not want. 60 612. You can then add any other Kconfig options, for example: 62 63.. code-block:: none 64 65 CONFIG_LIST_KUNIT_TEST=y 66 67Before running the tests, kunit_tool ensures that all config options 68set in ``.kunitconfig`` are set in the kernel ``.config``. It will warn 69you if you have not included dependencies for the options used. 70 71.. note :: 72 If you change the ``.kunitconfig``, kunit.py will trigger a rebuild of the 73 ``.config`` file. But you can edit the ``.config`` file directly or with 74 tools like ``make menuconfig O=.kunit``. As long as its a superset of 75 ``.kunitconfig``, kunit.py won't overwrite your changes. 76 77Running Tests (KUnit Wrapper) 78----------------------------- 791. To make sure that everything is set up correctly, invoke the Python 80 wrapper from your kernel repository: 81 82.. code-block:: bash 83 84 ./tools/testing/kunit/kunit.py run 85 86If everything worked correctly, you should see the following: 87 88.. code-block:: 89 90 Generating .config ... 91 Building KUnit Kernel ... 92 Starting KUnit Kernel ... 93 94The tests will pass or fail. 95 96.. note :: 97 Because it is building a lot of sources for the first time, the 98 ``Building KUnit kernel`` may take a while. 99 100Running Tests without the KUnit Wrapper 101======================================= 102If you do not want to use the KUnit Wrapper (for example: you want code 103under test to integrate with other systems, or use a different/ 104unsupported architecture or configuration), KUnit can be included in 105any kernel, and the results are read out and parsed manually. 106 107.. note :: 108 ``CONFIG_KUNIT`` should not be enabled in a production environment. 109 Enabling KUnit disables Kernel Address-Space Layout Randomization 110 (KASLR), and tests may affect the state of the kernel in ways not 111 suitable for production. 112 113Configuring the Kernel 114---------------------- 115To enable KUnit itself, you need to enable the ``CONFIG_KUNIT`` Kconfig 116option (under Kernel Hacking/Kernel Testing and Coverage in 117``menuconfig``). From there, you can enable any KUnit tests. They 118usually have config options ending in ``_KUNIT_TEST``. 119 120KUnit and KUnit tests can be compiled as modules. The tests in a module 121will run when the module is loaded. 122 123Running Tests (without KUnit Wrapper) 124------------------------------------- 125Build and run your kernel. In the kernel log, the test output is printed 126out in the TAP format. This will only happen by default if KUnit/tests 127are built-in. Otherwise the module will need to be loaded. 128 129.. note :: 130 Some lines and/or data may get interspersed in the TAP output. 131 132Writing Your First Test 133======================= 134In your kernel repository, let's add some code that we can test. 135 1361. Create a file ``drivers/misc/example.h``, which includes: 137 138.. code-block:: c 139 140 int misc_example_add(int left, int right); 141 1422. Create a file ``drivers/misc/example.c``, which includes: 143 144.. code-block:: c 145 146 #include <linux/errno.h> 147 148 #include "example.h" 149 150 int misc_example_add(int left, int right) 151 { 152 return left + right; 153 } 154 1553. Add the following lines to ``drivers/misc/Kconfig``: 156 157.. code-block:: kconfig 158 159 config MISC_EXAMPLE 160 bool "My example" 161 1624. Add the following lines to ``drivers/misc/Makefile``: 163 164.. code-block:: make 165 166 obj-$(CONFIG_MISC_EXAMPLE) += example.o 167 168Now we are ready to write the test cases. 169 1701. Add the below test case in ``drivers/misc/example_test.c``: 171 172.. code-block:: c 173 174 #include <kunit/test.h> 175 #include "example.h" 176 177 /* Define the test cases. */ 178 179 static void misc_example_add_test_basic(struct kunit *test) 180 { 181 KUNIT_EXPECT_EQ(test, 1, misc_example_add(1, 0)); 182 KUNIT_EXPECT_EQ(test, 2, misc_example_add(1, 1)); 183 KUNIT_EXPECT_EQ(test, 0, misc_example_add(-1, 1)); 184 KUNIT_EXPECT_EQ(test, INT_MAX, misc_example_add(0, INT_MAX)); 185 KUNIT_EXPECT_EQ(test, -1, misc_example_add(INT_MAX, INT_MIN)); 186 } 187 188 static void misc_example_test_failure(struct kunit *test) 189 { 190 KUNIT_FAIL(test, "This test never passes."); 191 } 192 193 static struct kunit_case misc_example_test_cases[] = { 194 KUNIT_CASE(misc_example_add_test_basic), 195 KUNIT_CASE(misc_example_test_failure), 196 {} 197 }; 198 199 static struct kunit_suite misc_example_test_suite = { 200 .name = "misc-example", 201 .test_cases = misc_example_test_cases, 202 }; 203 kunit_test_suite(misc_example_test_suite); 204 2052. Add the following lines to ``drivers/misc/Kconfig``: 206 207.. code-block:: kconfig 208 209 config MISC_EXAMPLE_TEST 210 tristate "Test for my example" if !KUNIT_ALL_TESTS 211 depends on MISC_EXAMPLE && KUNIT=y 212 default KUNIT_ALL_TESTS 213 2143. Add the following lines to ``drivers/misc/Makefile``: 215 216.. code-block:: make 217 218 obj-$(CONFIG_MISC_EXAMPLE_TEST) += example_test.o 219 2204. Add the following lines to ``.kunitconfig``: 221 222.. code-block:: none 223 224 CONFIG_MISC_EXAMPLE=y 225 CONFIG_MISC_EXAMPLE_TEST=y 226 2275. Run the test: 228 229.. code-block:: bash 230 231 ./tools/testing/kunit/kunit.py run 232 233You should see the following failure: 234 235.. code-block:: none 236 237 ... 238 [16:08:57] [PASSED] misc-example:misc_example_add_test_basic 239 [16:08:57] [FAILED] misc-example:misc_example_test_failure 240 [16:08:57] EXPECTATION FAILED at drivers/misc/example-test.c:17 241 [16:08:57] This test never passes. 242 ... 243 244Congrats! You just wrote your first KUnit test. 245 246Next Steps 247========== 248 249* Documentation/dev-tools/kunit/architecture.rst - KUnit architecture. 250* Documentation/dev-tools/kunit/run_wrapper.rst - run kunit_tool. 251* Documentation/dev-tools/kunit/run_manual.rst - run tests without kunit_tool. 252* Documentation/dev-tools/kunit/usage.rst - write tests. 253* Documentation/dev-tools/kunit/tips.rst - best practices with 254 examples. 255* Documentation/dev-tools/kunit/api/index.rst - KUnit APIs 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. 261