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 - Unit Testing for the Linux Kernel
5 ================================= !! 5 =========================================
6 6
7 .. toctree:: 7 .. toctree::
8 :maxdepth: 2 8 :maxdepth: 2
9 :caption: Contents: <<
10 9
11 start 10 start
12 architecture <<
13 run_wrapper <<
14 run_manual <<
15 usage 11 usage
>> 12 kunit-tool
16 api/index 13 api/index
17 style <<
18 faq 14 faq
19 running_tips <<
20 15
21 This section details the kernel unit testing f !! 16 What is KUnit?
>> 17 ==============
22 18
23 Introduction !! 19 KUnit is a lightweight unit testing and mocking framework for the Linux kernel.
24 ============ !! 20 These tests are able to be run locally on a developer's workstation without a VM
25 !! 21 or special hardware.
26 KUnit (Kernel unit testing framework) provides !! 22
27 unit tests within the Linux kernel. Using KUni !! 23 KUnit is heavily inspired by JUnit, Python's unittest.mock, and
28 of test cases called test suites. The tests ei !! 24 Googletest/Googlemock for C++. KUnit provides facilities for defining unit test
29 if built-in, or load as a module. KUnit automa !! 25 cases, grouping related test cases into test suites, providing common
30 failed test cases in the kernel log. The test !! 26 infrastructure for running tests, and much more.
31 :doc:`KTAP (Kernel - Test Anything Protocol) f !! 27
32 It is inspired by JUnit, Python’s unittest.m !! 28 Get started now: :doc:`start`
33 (C++ unit testing framework). !! 29
34 !! 30 Why KUnit?
35 KUnit tests are part of the kernel, written in !! 31 ==========
36 language, and test parts of the Kernel impleme !! 32
37 language function). Excluding build time, from !! 33 A unit test is supposed to test a single unit of code in isolation, hence the
38 completion, KUnit can run around 100 tests in !! 34 name. A unit test should be the finest granularity of testing and as such should
39 KUnit can test any kernel component, for examp !! 35 allow all possible code paths to be tested in the code under test; this is only
40 calls, memory management, device drivers and s !! 36 possible if the code under test is very small and does not have any external
41 !! 37 dependencies outside of the test's control like hardware.
42 KUnit follows the white-box testing approach. !! 38
43 internal system functionality. KUnit runs in k !! 39 Outside of KUnit, there are no testing frameworks currently
44 restricted to things exposed to user-space. !! 40 available for the kernel that do not require installing the kernel on a test
45 !! 41 machine or in a VM and all require tests to be written in userspace running on
46 In addition, KUnit has kunit_tool, a script (` !! 42 the kernel; this is true for Autotest, and kselftest, disqualifying
47 that configures the Linux kernel, runs KUnit t !! 43 any of them from being considered unit testing frameworks.
48 (:doc:`User Mode Linux </virt/uml/user_mode_li !! 44
49 parses the test results and !! 45 KUnit addresses the problem of being able to run tests without needing a virtual
50 displays them in a user friendly manner. !! 46 machine or actual hardware with User Mode Linux. User Mode Linux is a Linux
51 !! 47 architecture, like ARM or x86; however, unlike other architectures it compiles
52 Features !! 48 to a standalone program that can be run like any other program directly inside
53 -------- !! 49 of a host operating system; to be clear, it does not require any virtualization
54 !! 50 support; it is just a regular program.
55 - Provides a framework for writing unit tests. !! 51
56 - Runs tests on any kernel architecture. !! 52 Alternatively, kunit and kunit tests can be built as modules and tests will
57 - Runs a test in milliseconds. !! 53 run when the test module is loaded.
58 !! 54
59 Prerequisites !! 55 KUnit is fast. Excluding build time, from invocation to completion KUnit can run
60 ------------- !! 56 several dozen tests in only 10 to 20 seconds; this might not sound like a big
61 !! 57 deal to some people, but having such fast and easy to run tests fundamentally
62 - Any Linux kernel compatible hardware. !! 58 changes the way you go about testing and even writing code in the first place.
63 - For Kernel under test, Linux kernel version !! 59 Linus himself said in his `git talk at Google
64 !! 60 <https://gist.github.com/lorn/1272686/revisions#diff-53c65572127855f1b003db4064a94573R874>`_:
65 Unit Testing !! 61
66 ============ !! 62 "... a lot of people seem to think that performance is about doing the
67 !! 63 same thing, just doing it faster, and that is not true. That is not what
68 A unit test tests a single unit of code in iso !! 64 performance is all about. If you can do something really fast, really
69 granularity of testing and allows all possible !! 65 well, people will start using it differently."
70 code under test. This is possible if the code !! 66
71 have any external dependencies outside of the !! 67 In this context Linus was talking about branching and merging,
72 !! 68 but this point also applies to testing. If your tests are slow, unreliable, are
73 !! 69 difficult to write, and require a special setup or special hardware to run,
74 Write Unit Tests !! 70 then you wait a lot longer to write tests, and you wait a lot longer to run
75 ---------------- !! 71 tests; this means that tests are likely to break, unlikely to test a lot of
76 !! 72 things, and are unlikely to be rerun once they pass. If your tests are really
77 To write good unit tests, there is a simple bu !! 73 fast, you run them all the time, every time you make a change, and every time
78 Arrange-Act-Assert. This is a great way to str !! 74 someone sends you some code. Why trust that someone ran all their tests
79 defines an order of operations. !! 75 correctly on every change when you can just run them yourself in less time than
80 !! 76 it takes to read their test log?
81 - Arrange inputs and targets: At the start of <<
82 that allows a function to work. Example: ini <<
83 object. <<
84 - Act on the target behavior: Call your functi <<
85 - Assert expected outcome: Verify that the res <<
86 expected. <<
87 <<
88 Unit Testing Advantages <<
89 ----------------------- <<
90 <<
91 - Increases testing speed and development in t <<
92 - Detects bugs at initial stage and therefore <<
93 compared to acceptance testing. <<
94 - Improves code quality. <<
95 - Encourages writing testable code. <<
96 <<
97 Read also :ref:`kinds-of-tests`. <<
98 77
99 How do I use it? 78 How do I use it?
100 ================ 79 ================
101 80
102 You can find a step-by-step guide to writing a !! 81 * :doc:`start` - for new users of KUnit
103 Documentation/dev-tools/kunit/start.rst !! 82 * :doc:`usage` - for a more detailed explanation of KUnit features
104 !! 83 * :doc:`api/index` - for the list of KUnit APIs used for testing
105 Alternatively, feel free to look through the r <<
106 or to experiment with tools/testing/kunit/kuni <<
107 lib/kunit/kunit-example-test.c <<
108 <<
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.