1 .. SPDX-License-Identifier: GPL-2.0
3 =================================
4 KUnit - Linux Kernel Unit Testing
5 =================================
23 This section details the kernel unit testing framework.
28 KUnit (Kernel unit testing framework) provides a common framework for
29 unit tests within the Linux kernel. Using KUnit, you can define groups
30 of test cases called test suites. The tests either run on kernel boot
31 if built-in, or load as a module. KUnit automatically flags and reports
32 failed test cases in the kernel log. The test results appear in `TAP
33 (Test Anything Protocol) format <https://testanything.org/>`_. It is inspired by
34 JUnit, Python’s unittest.mock, and GoogleTest/GoogleMock (C++ unit testing
37 KUnit tests are part of the kernel, written in the C (programming)
38 language, and test parts of the Kernel implementation (example: a C
39 language function). Excluding build time, from invocation to
40 completion, KUnit can run around 100 tests in less than 10 seconds.
41 KUnit can test any kernel component, for example: file system, system
42 calls, memory management, device drivers and so on.
44 KUnit follows the white-box testing approach. The test has access to
45 internal system functionality. KUnit runs in kernel space and is not
46 restricted to things exposed to user-space.
48 In addition, KUnit has kunit_tool, a script (``tools/testing/kunit/kunit.py``)
49 that configures the Linux kernel, runs KUnit tests under QEMU or UML (`User Mode
50 Linux <http://user-mode-linux.sourceforge.net/>`_), parses the test results and
51 displays them in a user friendly manner.
56 - Provides a framework for writing unit tests.
57 - Runs tests on any kernel architecture.
58 - Runs a test in milliseconds.
63 - Any Linux kernel compatible hardware.
64 - For Kernel under test, Linux kernel version 5.5 or greater.
69 A unit test tests a single unit of code in isolation. A unit test is the finest
70 granularity of testing and allows all possible code paths to be tested in the
71 code under test. This is possible if the code under test is small and does not
72 have any external dependencies outside of the test's control like hardware.
78 To write good unit tests, there is a simple but powerful pattern:
79 Arrange-Act-Assert. This is a great way to structure test cases and
80 defines an order of operations.
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
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
89 Unit Testing Advantages
90 -----------------------
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.
101 * Documentation/dev-tools/kunit/start.rst - for KUnit new users.
102 * Documentation/dev-tools/kunit/architecture.rst - KUnit architecture.
103 * Documentation/dev-tools/kunit/run_wrapper.rst - run kunit_tool.
104 * Documentation/dev-tools/kunit/run_manual.rst - run tests without kunit_tool.
105 * Documentation/dev-tools/kunit/usage.rst - write tests.
106 * Documentation/dev-tools/kunit/tips.rst - best practices with
108 * Documentation/dev-tools/kunit/api/index.rst - KUnit APIs
110 * Documentation/dev-tools/kunit/kunit-tool.rst - kunit_tool helper
112 * Documentation/dev-tools/kunit/faq.rst - KUnit common questions and