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