1.. SPDX-License-Identifier: GPL-2.0
2
3=========================================
4KUnit - Unit Testing for the Linux Kernel
5=========================================
6
7.. toctree::
8	:maxdepth: 2
9
10	start
11	usage
12	kunit-tool
13	api/index
14	style
15	faq
16	tips
17
18What is KUnit?
19==============
20
21KUnit is a lightweight unit testing and mocking framework for the Linux kernel.
22
23KUnit is heavily inspired by JUnit, Python's unittest.mock, and
24Googletest/Googlemock for C++. KUnit provides facilities for defining unit test
25cases, grouping related test cases into test suites, providing common
26infrastructure for running tests, and much more.
27
28KUnit consists of a kernel component, which provides a set of macros for easily
29writing unit tests. Tests written against KUnit will run on kernel boot if
30built-in, or when loaded if built as a module. These tests write out results to
31the kernel log in `TAP <https://testanything.org/>`_ format.
32
33To make running these tests (and reading the results) easier, KUnit offers
34:doc:`kunit_tool <kunit-tool>`, which builds a `User Mode Linux
35<http://user-mode-linux.sourceforge.net>`_ kernel, runs it, and parses the test
36results. This provides a quick way of running KUnit tests during development,
37without requiring a virtual machine or separate hardware.
38
39Get started now: :doc:`start`
40
41Why KUnit?
42==========
43
44A unit test is supposed to test a single unit of code in isolation, hence the
45name. A unit test should be the finest granularity of testing and as such should
46allow all possible code paths to be tested in the code under test; this is only
47possible if the code under test is very small and does not have any external
48dependencies outside of the test's control like hardware.
49
50KUnit provides a common framework for unit tests within the kernel.
51
52KUnit tests can be run on most architectures, and most tests are architecture
53independent. All built-in KUnit tests run on kernel startup.  Alternatively,
54KUnit and KUnit tests can be built as modules and tests will run when the test
55module is loaded.
56
57.. note::
58
59        KUnit can also run tests without needing a virtual machine or actual
60        hardware under User Mode Linux. User Mode Linux is a Linux architecture,
61        like ARM or x86, which compiles the kernel as a Linux executable. KUnit
62        can be used with UML either by building with ``ARCH=um`` (like any other
63        architecture), or by using :doc:`kunit_tool <kunit-tool>`.
64
65KUnit is fast. Excluding build time, from invocation to completion KUnit can run
66several dozen tests in only 10 to 20 seconds; this might not sound like a big
67deal to some people, but having such fast and easy to run tests fundamentally
68changes the way you go about testing and even writing code in the first place.
69Linus himself said in his `git talk at Google
70<https://gist.github.com/lorn/1272686/revisions#diff-53c65572127855f1b003db4064a94573R874>`_:
71
72	"... a lot of people seem to think that performance is about doing the
73	same thing, just doing it faster, and that is not true. That is not what
74	performance is all about. If you can do something really fast, really
75	well, people will start using it differently."
76
77In this context Linus was talking about branching and merging,
78but this point also applies to testing. If your tests are slow, unreliable, are
79difficult to write, and require a special setup or special hardware to run,
80then you wait a lot longer to write tests, and you wait a lot longer to run
81tests; this means that tests are likely to break, unlikely to test a lot of
82things, and are unlikely to be rerun once they pass. If your tests are really
83fast, you run them all the time, every time you make a change, and every time
84someone sends you some code. Why trust that someone ran all their tests
85correctly on every change when you can just run them yourself in less time than
86it takes to read their test log?
87
88How do I use it?
89================
90
91*   :doc:`start` - for new users of KUnit
92*   :doc:`tips` - for short examples of best practices
93*   :doc:`usage` - for a more detailed explanation of KUnit features
94*   :doc:`api/index` - for the list of KUnit APIs used for testing
95*   :doc:`kunit-tool` - for more information on the kunit_tool helper script
96*   :doc:`faq` - for answers to some common questions about KUnit
97