0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 =================================
0004 KUnit - Linux Kernel Unit Testing
0005 =================================
0006
0007 .. toctree::
0008 :maxdepth: 2
0009 :caption: Contents:
0010
0011 start
0012 architecture
0013 run_wrapper
0014 run_manual
0015 usage
0016 kunit-tool
0017 api/index
0018 style
0019 faq
0020 tips
0021 running_tips
0022
0023 This section details the kernel unit testing framework.
0024
0025 Introduction
0026 ============
0027
0028 KUnit (Kernel unit testing framework) provides a common framework for
0029 unit tests within the Linux kernel. Using KUnit, you can define groups
0030 of test cases called test suites. The tests either run on kernel boot
0031 if built-in, or load as a module. KUnit automatically flags and reports
0032 failed test cases in the kernel log. The test results appear in `TAP
0033 (Test Anything Protocol) format <https://testanything.org/>`_. It is inspired by
0034 JUnit, Python’s unittest.mock, and GoogleTest/GoogleMock (C++ unit testing
0035 framework).
0036
0037 KUnit tests are part of the kernel, written in the C (programming)
0038 language, and test parts of the Kernel implementation (example: a C
0039 language function). Excluding build time, from invocation to
0040 completion, KUnit can run around 100 tests in less than 10 seconds.
0041 KUnit can test any kernel component, for example: file system, system
0042 calls, memory management, device drivers and so on.
0043
0044 KUnit follows the white-box testing approach. The test has access to
0045 internal system functionality. KUnit runs in kernel space and is not
0046 restricted to things exposed to user-space.
0047
0048 In addition, KUnit has kunit_tool, a script (``tools/testing/kunit/kunit.py``)
0049 that configures the Linux kernel, runs KUnit tests under QEMU or UML (`User Mode
0050 Linux <http://user-mode-linux.sourceforge.net/>`_), parses the test results and
0051 displays them in a user friendly manner.
0052
0053 Features
0054 --------
0055
0056 - Provides a framework for writing unit tests.
0057 - Runs tests on any kernel architecture.
0058 - Runs a test in milliseconds.
0059
0060 Prerequisites
0061 -------------
0062
0063 - Any Linux kernel compatible hardware.
0064 - For Kernel under test, Linux kernel version 5.5 or greater.
0065
0066 Unit Testing
0067 ============
0068
0069 A unit test tests a single unit of code in isolation. A unit test is the finest
0070 granularity of testing and allows all possible code paths to be tested in the
0071 code under test. This is possible if the code under test is small and does not
0072 have any external dependencies outside of the test's control like hardware.
0073
0074
0075 Write Unit Tests
0076 ----------------
0077
0078 To write good unit tests, there is a simple but powerful pattern:
0079 Arrange-Act-Assert. This is a great way to structure test cases and
0080 defines an order of operations.
0081
0082 - Arrange inputs and targets: At the start of the test, arrange the data
0083 that allows a function to work. Example: initialize a statement or
0084 object.
0085 - Act on the target behavior: Call your function/code under test.
0086 - Assert expected outcome: Verify that the result (or resulting state) is as
0087 expected.
0088
0089 Unit Testing Advantages
0090 -----------------------
0091
0092 - Increases testing speed and development in the long run.
0093 - Detects bugs at initial stage and therefore decreases bug fix cost
0094 compared to acceptance testing.
0095 - Improves code quality.
0096 - Encourages writing testable code.
0097
0098 How do I use it?
0099 ================
0100
0101 * Documentation/dev-tools/kunit/start.rst - for KUnit new users.
0102 * Documentation/dev-tools/kunit/architecture.rst - KUnit architecture.
0103 * Documentation/dev-tools/kunit/run_wrapper.rst - run kunit_tool.
0104 * Documentation/dev-tools/kunit/run_manual.rst - run tests without kunit_tool.
0105 * Documentation/dev-tools/kunit/usage.rst - write tests.
0106 * Documentation/dev-tools/kunit/tips.rst - best practices with
0107 examples.
0108 * Documentation/dev-tools/kunit/api/index.rst - KUnit APIs
0109 used for testing.
0110 * Documentation/dev-tools/kunit/kunit-tool.rst - kunit_tool helper
0111 script.
0112 * Documentation/dev-tools/kunit/faq.rst - KUnit common questions and
0113 answers.
