Linux/Documentation/dev-tools/kunit/start.rst

Version: ~ [ linux-6.12-rc7 ] ~ [ linux-6.11.7 ] ~ [ linux-6.10.14 ] ~ [ linux-6.9.12 ] ~ [ linux-6.8.12 ] ~ [ linux-6.7.12 ] ~ [ linux-6.6.60 ] ~ [ linux-6.5.13 ] ~ [ linux-6.4.16 ] ~ [ linux-6.3.13 ] ~ [ linux-6.2.16 ] ~ [ linux-6.1.116 ] ~ [ linux-6.0.19 ] ~ [ linux-5.19.17 ] ~ [ linux-5.18.19 ] ~ [ linux-5.17.15 ] ~ [ linux-5.16.20 ] ~ [ linux-5.15.171 ] ~ [ linux-5.14.21 ] ~ [ linux-5.13.19 ] ~ [ linux-5.12.19 ] ~ [ linux-5.11.22 ] ~ [ linux-5.10.229 ] ~ [ linux-5.9.16 ] ~ [ linux-5.8.18 ] ~ [ linux-5.7.19 ] ~ [ linux-5.6.19 ] ~ [ linux-5.5.19 ] ~ [ linux-5.4.285 ] ~ [ linux-5.3.18 ] ~ [ linux-5.2.21 ] ~ [ linux-5.1.21 ] ~ [ linux-5.0.21 ] ~ [ linux-4.20.17 ] ~ [ linux-4.19.323 ] ~ [ linux-4.18.20 ] ~ [ linux-4.17.19 ] ~ [ linux-4.16.18 ] ~ [ linux-4.15.18 ] ~ [ linux-4.14.336 ] ~ [ linux-4.13.16 ] ~ [ linux-4.12.14 ] ~ [ linux-4.11.12 ] ~ [ linux-4.10.17 ] ~ [ linux-4.9.337 ] ~ [ linux-4.4.302 ] ~ [ linux-3.10.108 ] ~ [ linux-2.6.32.71 ] ~ [ linux-2.6.0 ] ~ [ linux-2.4.37.11 ] ~ [ unix-v6-master ] ~ [ ccs-tools-1.8.12 ] ~ [ policy-sample ] ~
Architecture: ~ [ i386 ] ~ [ alpha ] ~ [ m68k ] ~ [ mips ] ~ [ ppc ] ~ [ sparc ] ~ [ sparc64 ] ~

Diff markup

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

TOMOYO Linux Cross Reference
Linux/Documentation/dev-tools/kunit/start.rst

Diff markup

Differences between /Documentation/dev-tools/kunit/start.rst (Version linux-6.12-rc7) and /Documentation/dev-tools/kunit/start.rst (Version linux-5.5.19)

TOMOYO Linux Cross Reference Linux/Documentation/dev-tools/kunit/start.rst

Diff markup

Differences between /Documentation/dev-tools/kunit/start.rst (Version linux-6.12-rc7) and /Documentation/dev-tools/kunit/start.rst (Version linux-5.5.19)

TOMOYO Linux Cross Reference
Linux/Documentation/dev-tools/kunit/start.rst