Documentation/dev-tools/kunit/index.rst

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