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	faq
15
16What is KUnit?
17==============
18
19KUnit is a lightweight unit testing and mocking framework for the Linux kernel.
20These tests are able to be run locally on a developer's workstation without a VM
21or special hardware.
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
28Get started now: :doc:`start`
29
30Why KUnit?
31==========
32
33A unit test is supposed to test a single unit of code in isolation, hence the
34name. A unit test should be the finest granularity of testing and as such should
35allow all possible code paths to be tested in the code under test; this is only
36possible if the code under test is very small and does not have any external
37dependencies outside of the test's control like hardware.
38
39Outside of KUnit, there are no testing frameworks currently
40available for the kernel that do not require installing the kernel on a test
41machine or in a VM and all require tests to be written in userspace running on
42the kernel; this is true for Autotest, and kselftest, disqualifying
43any of them from being considered unit testing frameworks.
44
45KUnit addresses the problem of being able to run tests without needing a virtual
46machine or actual hardware with User Mode Linux. User Mode Linux is a Linux
47architecture, like ARM or x86; however, unlike other architectures it compiles
48to a standalone program that can be run like any other program directly inside
49of a host operating system; to be clear, it does not require any virtualization
50support; it is just a regular program.
51
52KUnit is fast. Excluding build time, from invocation to completion KUnit can run
53several dozen tests in only 10 to 20 seconds; this might not sound like a big
54deal to some people, but having such fast and easy to run tests fundamentally
55changes the way you go about testing and even writing code in the first place.
56Linus himself said in his `git talk at Google
57<https://gist.github.com/lorn/1272686/revisions#diff-53c65572127855f1b003db4064a94573R874>`_:
58
59	"... a lot of people seem to think that performance is about doing the
60	same thing, just doing it faster, and that is not true. That is not what
61	performance is all about. If you can do something really fast, really
62	well, people will start using it differently."
63
64In this context Linus was talking about branching and merging,
65but this point also applies to testing. If your tests are slow, unreliable, are
66difficult to write, and require a special setup or special hardware to run,
67then you wait a lot longer to write tests, and you wait a lot longer to run
68tests; this means that tests are likely to break, unlikely to test a lot of
69things, and are unlikely to be rerun once they pass. If your tests are really
70fast, you run them all the time, every time you make a change, and every time
71someone sends you some code. Why trust that someone ran all their tests
72correctly on every change when you can just run them yourself in less time than
73it takes to read their test log?
74
75How do I use it?
76================
77
78*   :doc:`start` - for new users of KUnit
79*   :doc:`usage` - for a more detailed explanation of KUnit features
80*   :doc:`api/index` - for the list of KUnit APIs used for testing
81