index.rst

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