1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0
2 2
3 ================================= 3 =================================
4 KUnit - Linux Kernel Unit Testing 4 KUnit - Linux Kernel Unit Testing
5 ================================= 5 =================================
6 6
7 .. toctree:: 7 .. toctree::
8 :maxdepth: 2 8 :maxdepth: 2
9 :caption: Contents: 9 :caption: Contents:
10 10
11 start 11 start
12 architecture 12 architecture
13 run_wrapper 13 run_wrapper
14 run_manual 14 run_manual
15 usage 15 usage
>> 16 kunit-tool
16 api/index 17 api/index
17 style 18 style
18 faq 19 faq
>> 20 tips
19 running_tips 21 running_tips
20 22
21 This section details the kernel unit testing f 23 This section details the kernel unit testing framework.
22 24
23 Introduction 25 Introduction
24 ============ 26 ============
25 27
26 KUnit (Kernel unit testing framework) provides 28 KUnit (Kernel unit testing framework) provides a common framework for
27 unit tests within the Linux kernel. Using KUni 29 unit tests within the Linux kernel. Using KUnit, you can define groups
28 of test cases called test suites. The tests ei 30 of test cases called test suites. The tests either run on kernel boot
29 if built-in, or load as a module. KUnit automa 31 if built-in, or load as a module. KUnit automatically flags and reports
30 failed test cases in the kernel log. The test !! 32 failed test cases in the kernel log. The test results appear in `TAP
31 :doc:`KTAP (Kernel - Test Anything Protocol) f !! 33 (Test Anything Protocol) format <https://testanything.org/>`_. It is inspired by
32 It is inspired by JUnit, Python’s unittest.m !! 34 JUnit, Python’s unittest.mock, and GoogleTest/GoogleMock (C++ unit testing
33 (C++ unit testing framework). !! 35 framework).
34 36
35 KUnit tests are part of the kernel, written in 37 KUnit tests are part of the kernel, written in the C (programming)
36 language, and test parts of the Kernel impleme 38 language, and test parts of the Kernel implementation (example: a C
37 language function). Excluding build time, from 39 language function). Excluding build time, from invocation to
38 completion, KUnit can run around 100 tests in 40 completion, KUnit can run around 100 tests in less than 10 seconds.
39 KUnit can test any kernel component, for examp 41 KUnit can test any kernel component, for example: file system, system
40 calls, memory management, device drivers and s 42 calls, memory management, device drivers and so on.
41 43
42 KUnit follows the white-box testing approach. 44 KUnit follows the white-box testing approach. The test has access to
43 internal system functionality. KUnit runs in k 45 internal system functionality. KUnit runs in kernel space and is not
44 restricted to things exposed to user-space. 46 restricted to things exposed to user-space.
45 47
46 In addition, KUnit has kunit_tool, a script (` 48 In addition, KUnit has kunit_tool, a script (``tools/testing/kunit/kunit.py``)
47 that configures the Linux kernel, runs KUnit t !! 49 that configures the Linux kernel, runs KUnit tests under QEMU or UML (`User Mode
48 (:doc:`User Mode Linux </virt/uml/user_mode_li !! 50 Linux <http://user-mode-linux.sourceforge.net/>`_), parses the test results and
49 parses the test results and <<
50 displays them in a user friendly manner. 51 displays them in a user friendly manner.
51 52
52 Features 53 Features
53 -------- 54 --------
54 55
55 - Provides a framework for writing unit tests. 56 - Provides a framework for writing unit tests.
56 - Runs tests on any kernel architecture. 57 - Runs tests on any kernel architecture.
57 - Runs a test in milliseconds. 58 - Runs a test in milliseconds.
58 59
59 Prerequisites 60 Prerequisites
60 ------------- 61 -------------
61 62
62 - Any Linux kernel compatible hardware. 63 - Any Linux kernel compatible hardware.
63 - For Kernel under test, Linux kernel version 64 - For Kernel under test, Linux kernel version 5.5 or greater.
64 65
65 Unit Testing 66 Unit Testing
66 ============ 67 ============
67 68
68 A unit test tests a single unit of code in iso 69 A unit test tests a single unit of code in isolation. A unit test is the finest
69 granularity of testing and allows all possible 70 granularity of testing and allows all possible code paths to be tested in the
70 code under test. This is possible if the code 71 code under test. This is possible if the code under test is small and does not
71 have any external dependencies outside of the 72 have any external dependencies outside of the test's control like hardware.
72 73
73 74
74 Write Unit Tests 75 Write Unit Tests
75 ---------------- 76 ----------------
76 77
77 To write good unit tests, there is a simple bu 78 To write good unit tests, there is a simple but powerful pattern:
78 Arrange-Act-Assert. This is a great way to str 79 Arrange-Act-Assert. This is a great way to structure test cases and
79 defines an order of operations. 80 defines an order of operations.
80 81
81 - Arrange inputs and targets: At the start of 82 - Arrange inputs and targets: At the start of the test, arrange the data
82 that allows a function to work. Example: ini 83 that allows a function to work. Example: initialize a statement or
83 object. 84 object.
84 - Act on the target behavior: Call your functi 85 - Act on the target behavior: Call your function/code under test.
85 - Assert expected outcome: Verify that the res 86 - Assert expected outcome: Verify that the result (or resulting state) is as
86 expected. 87 expected.
87 88
88 Unit Testing Advantages 89 Unit Testing Advantages
89 ----------------------- 90 -----------------------
90 91
91 - Increases testing speed and development in t 92 - Increases testing speed and development in the long run.
92 - Detects bugs at initial stage and therefore 93 - Detects bugs at initial stage and therefore decreases bug fix cost
93 compared to acceptance testing. 94 compared to acceptance testing.
94 - Improves code quality. 95 - Improves code quality.
95 - Encourages writing testable code. 96 - Encourages writing testable code.
96 97
97 Read also :ref:`kinds-of-tests`. <<
98 <<
99 How do I use it? 98 How do I use it?
100 ================ 99 ================
101 100
102 You can find a step-by-step guide to writing a !! 101 * Documentation/dev-tools/kunit/start.rst - for KUnit new users.
103 Documentation/dev-tools/kunit/start.rst !! 102 * Documentation/dev-tools/kunit/architecture.rst - KUnit architecture.
104 !! 103 * Documentation/dev-tools/kunit/run_wrapper.rst - run kunit_tool.
105 Alternatively, feel free to look through the r !! 104 * Documentation/dev-tools/kunit/run_manual.rst - run tests without kunit_tool.
106 or to experiment with tools/testing/kunit/kuni !! 105 * Documentation/dev-tools/kunit/usage.rst - write tests.
107 lib/kunit/kunit-example-test.c !! 106 * Documentation/dev-tools/kunit/tips.rst - best practices with
108 !! 107 examples.
109 Happy testing! !! 108 * Documentation/dev-tools/kunit/api/index.rst - KUnit APIs
>> 109 used for testing.
>> 110 * Documentation/dev-tools/kunit/kunit-tool.rst - kunit_tool helper
>> 111 script.
>> 112 * Documentation/dev-tools/kunit/faq.rst - KUnit common questions and
>> 113 answers.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.