1.. SPDX-License-Identifier: GPL-2.0
2
3=================================
4KUnit - Linux Kernel Unit Testing
5=================================
6
7.. toctree::
8	:maxdepth: 2
9	:caption: Contents:
10
11	start
12	architecture
13	run_wrapper
14	run_manual
15	usage
16	api/index
17	style
18	faq
19	tips
20	running_tips
21
22This section details the kernel unit testing framework.
23
24Introduction
25============
26
27KUnit (Kernel unit testing framework) provides a common framework for
28unit tests within the Linux kernel. Using KUnit, you can define groups
29of test cases called test suites. The tests either run on kernel boot
30if built-in, or load as a module. KUnit automatically flags and reports
31failed test cases in the kernel log. The test results appear in
32:doc:`KTAP (Kernel - Test Anything Protocol) format</dev-tools/ktap>`.
33It is inspired by JUnit, Python’s unittest.mock, and GoogleTest/GoogleMock
34(C++ unit testing framework).
35
36KUnit tests are part of the kernel, written in the C (programming)
37language, and test parts of the Kernel implementation (example: a C
38language function). Excluding build time, from invocation to
39completion, KUnit can run around 100 tests in less than 10 seconds.
40KUnit can test any kernel component, for example: file system, system
41calls, memory management, device drivers and so on.
42
43KUnit follows the white-box testing approach. The test has access to
44internal system functionality. KUnit runs in kernel space and is not
45restricted to things exposed to user-space.
46
47In addition, KUnit has kunit_tool, a script (``tools/testing/kunit/kunit.py``)
48that configures the Linux kernel, runs KUnit tests under QEMU or UML
49(:doc:`User Mode Linux </virt/uml/user_mode_linux_howto_v2>`),
50parses the test results and
51displays them in a user friendly manner.
52
53Features
54--------
55
56- Provides a framework for writing unit tests.
57- Runs tests on any kernel architecture.
58- Runs a test in milliseconds.
59
60Prerequisites
61-------------
62
63- Any Linux kernel compatible hardware.
64- For Kernel under test, Linux kernel version 5.5 or greater.
65
66Unit Testing
67============
68
69A unit test tests a single unit of code in isolation. A unit test is the finest
70granularity of testing and allows all possible code paths to be tested in the
71code under test. This is possible if the code under test is small and does not
72have any external dependencies outside of the test's control like hardware.
73
74
75Write Unit Tests
76----------------
77
78To write good unit tests, there is a simple but powerful pattern:
79Arrange-Act-Assert. This is a great way to structure test cases and
80defines an order of operations.
81
82- Arrange inputs and targets: At the start of the test, arrange the data
83  that allows a function to work. Example: initialize a statement or
84  object.
85- Act on the target behavior: Call your function/code under test.
86- Assert expected outcome: Verify that the result (or resulting state) is as
87  expected.
88
89Unit Testing Advantages
90-----------------------
91
92- Increases testing speed and development in the long run.
93- Detects bugs at initial stage and therefore decreases bug fix cost
94  compared to acceptance testing.
95- Improves code quality.
96- Encourages writing testable code.
97
98Read also :ref:`kinds-of-tests`.
99
100How do I use it?
101================
102
103*   Documentation/dev-tools/kunit/start.rst - for KUnit new users.
104*   Documentation/dev-tools/kunit/architecture.rst - KUnit architecture.
105*   Documentation/dev-tools/kunit/run_wrapper.rst - run kunit_tool.
106*   Documentation/dev-tools/kunit/run_manual.rst - run tests without kunit_tool.
107*   Documentation/dev-tools/kunit/usage.rst - write tests.
108*   Documentation/dev-tools/kunit/tips.rst - best practices with
109    examples.
110*   Documentation/dev-tools/kunit/api/index.rst - KUnit APIs
111    used for testing.
112*   Documentation/dev-tools/kunit/faq.rst - KUnit common questions and
113    answers.
114