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 build 10the kernel, you can run KUnit. 11 12KUnit Wrapper 13============= 14Included with KUnit is a simple Python wrapper that helps format the output to 15easily use and read KUnit output. It handles building and running the kernel, as 16well as formatting the output. 17 18The wrapper can be run with: 19 20.. code-block:: bash 21 22 ./tools/testing/kunit/kunit.py run --defconfig 23 24For more information on this wrapper (also called kunit_tool) checkout the 25:doc:`kunit-tool` page. 26 27Creating a .kunitconfig 28======================= 29The Python script is a thin wrapper around Kbuild. As such, it needs to be 30configured with a ``.kunitconfig`` file. This file essentially contains the 31regular Kernel config, with the specific test targets as well. 32 33.. code-block:: bash 34 35 cd $PATH_TO_LINUX_REPO 36 cp arch/um/configs/kunit_defconfig .kunitconfig 37 38Verifying KUnit Works 39--------------------- 40 41To make sure that everything is set up correctly, simply invoke the Python 42wrapper from your kernel repo: 43 44.. code-block:: bash 45 46 ./tools/testing/kunit/kunit.py run 47 48.. note:: 49 You may want to run ``make mrproper`` first. 50 51If everything worked correctly, you should see the following: 52 53.. code-block:: bash 54 55 Generating .config ... 56 Building KUnit Kernel ... 57 Starting KUnit Kernel ... 58 59followed by a list of tests that are run. All of them should be passing. 60 61.. note:: 62 Because it is building a lot of sources for the first time, the 63 ``Building KUnit kernel`` step may take a while. 64 65Writing your first test 66======================= 67 68In your kernel repo let's add some code that we can test. Create a file 69``drivers/misc/example.h`` with the contents: 70 71.. code-block:: c 72 73 int misc_example_add(int left, int right); 74 75create a file ``drivers/misc/example.c``: 76 77.. code-block:: c 78 79 #include <linux/errno.h> 80 81 #include "example.h" 82 83 int misc_example_add(int left, int right) 84 { 85 return left + right; 86 } 87 88Now add the following lines to ``drivers/misc/Kconfig``: 89 90.. code-block:: kconfig 91 92 config MISC_EXAMPLE 93 bool "My example" 94 95and the following lines to ``drivers/misc/Makefile``: 96 97.. code-block:: make 98 99 obj-$(CONFIG_MISC_EXAMPLE) += example.o 100 101Now we are ready to write the test. The test will be in 102``drivers/misc/example-test.c``: 103 104.. code-block:: c 105 106 #include <kunit/test.h> 107 #include "example.h" 108 109 /* Define the test cases. */ 110 111 static void misc_example_add_test_basic(struct kunit *test) 112 { 113 KUNIT_EXPECT_EQ(test, 1, misc_example_add(1, 0)); 114 KUNIT_EXPECT_EQ(test, 2, misc_example_add(1, 1)); 115 KUNIT_EXPECT_EQ(test, 0, misc_example_add(-1, 1)); 116 KUNIT_EXPECT_EQ(test, INT_MAX, misc_example_add(0, INT_MAX)); 117 KUNIT_EXPECT_EQ(test, -1, misc_example_add(INT_MAX, INT_MIN)); 118 } 119 120 static void misc_example_test_failure(struct kunit *test) 121 { 122 KUNIT_FAIL(test, "This test never passes."); 123 } 124 125 static struct kunit_case misc_example_test_cases[] = { 126 KUNIT_CASE(misc_example_add_test_basic), 127 KUNIT_CASE(misc_example_test_failure), 128 {} 129 }; 130 131 static struct kunit_suite misc_example_test_suite = { 132 .name = "misc-example", 133 .test_cases = misc_example_test_cases, 134 }; 135 kunit_test_suite(misc_example_test_suite); 136 137Now add the following to ``drivers/misc/Kconfig``: 138 139.. code-block:: kconfig 140 141 config MISC_EXAMPLE_TEST 142 bool "Test for my example" 143 depends on MISC_EXAMPLE && KUNIT 144 145and the following to ``drivers/misc/Makefile``: 146 147.. code-block:: make 148 149 obj-$(CONFIG_MISC_EXAMPLE_TEST) += example-test.o 150 151Now add it to your ``.kunitconfig``: 152 153.. code-block:: none 154 155 CONFIG_MISC_EXAMPLE=y 156 CONFIG_MISC_EXAMPLE_TEST=y 157 158Now you can run the test: 159 160.. code-block:: bash 161 162 ./tools/testing/kunit/kunit.py run 163 164You should see the following failure: 165 166.. code-block:: none 167 168 ... 169 [16:08:57] [PASSED] misc-example:misc_example_add_test_basic 170 [16:08:57] [FAILED] misc-example:misc_example_test_failure 171 [16:08:57] EXPECTATION FAILED at drivers/misc/example-test.c:17 172 [16:08:57] This test never passes. 173 ... 174 175Congrats! You just wrote your first KUnit test! 176 177Next Steps 178========== 179* Check out the :doc:`usage` page for a more 180 in-depth explanation of KUnit. 181