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