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 running_tips 20 21.. warning:: 22 AOSP only supports running tests loaded with modules. Built-in 23 test execution support has been disabled. In addition, in order 24 to fully enable running module loaded tests both CONFIG_KUNIT 25 needs to be enabled and kernel command line argument 26 `kunit.enable` needs to be set to 1. 27 28 The remaining KUnit documentation has been left as-is. 29 30This section details the kernel unit testing framework. 31 32Introduction 33============ 34 35KUnit (Kernel unit testing framework) provides a common framework for 36unit tests within the Linux kernel. Using KUnit, you can define groups 37of test cases called test suites. The tests either run on kernel boot 38if built-in, or load as a module. KUnit automatically flags and reports 39failed test cases in the kernel log. The test results appear in 40:doc:`KTAP (Kernel - Test Anything Protocol) format</dev-tools/ktap>`. 41It is inspired by JUnit, Python’s unittest.mock, and GoogleTest/GoogleMock 42(C++ unit testing framework). 43 44KUnit tests are part of the kernel, written in the C (programming) 45language, and test parts of the Kernel implementation (example: a C 46language function). Excluding build time, from invocation to 47completion, KUnit can run around 100 tests in less than 10 seconds. 48KUnit can test any kernel component, for example: file system, system 49calls, memory management, device drivers and so on. 50 51KUnit follows the white-box testing approach. The test has access to 52internal system functionality. KUnit runs in kernel space and is not 53restricted to things exposed to user-space. 54 55In addition, KUnit has kunit_tool, a script (``tools/testing/kunit/kunit.py``) 56that configures the Linux kernel, runs KUnit tests under QEMU or UML 57(:doc:`User Mode Linux </virt/uml/user_mode_linux_howto_v2>`), 58parses the test results and 59displays them in a user friendly manner. 60 61Features 62-------- 63 64- Provides a framework for writing unit tests. 65- Runs tests on any kernel architecture. 66- Runs a test in milliseconds. 67 68Prerequisites 69------------- 70 71- Any Linux kernel compatible hardware. 72- For Kernel under test, Linux kernel version 5.5 or greater. 73 74Unit Testing 75============ 76 77A unit test tests a single unit of code in isolation. A unit test is the finest 78granularity of testing and allows all possible code paths to be tested in the 79code under test. This is possible if the code under test is small and does not 80have any external dependencies outside of the test's control like hardware. 81 82 83Write Unit Tests 84---------------- 85 86To write good unit tests, there is a simple but powerful pattern: 87Arrange-Act-Assert. This is a great way to structure test cases and 88defines an order of operations. 89 90- Arrange inputs and targets: At the start of the test, arrange the data 91 that allows a function to work. Example: initialize a statement or 92 object. 93- Act on the target behavior: Call your function/code under test. 94- Assert expected outcome: Verify that the result (or resulting state) is as 95 expected. 96 97Unit Testing Advantages 98----------------------- 99 100- Increases testing speed and development in the long run. 101- Detects bugs at initial stage and therefore decreases bug fix cost 102 compared to acceptance testing. 103- Improves code quality. 104- Encourages writing testable code. 105 106Read also :ref:`kinds-of-tests`. 107 108How do I use it? 109================ 110 111You can find a step-by-step guide to writing and running KUnit tests in 112Documentation/dev-tools/kunit/start.rst 113 114Alternatively, feel free to look through the rest of the KUnit documentation, 115or to experiment with tools/testing/kunit/kunit.py and the example test under 116lib/kunit/kunit-example-test.c 117 118Happy testing! 119