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