Documentation/dev-tools/kunit/index.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 =========================================
   4 KUnit - Unit Testing for the Linux Kernel
   5 =========================================
   6
   7 .. toctree::
   8         :maxdepth: 2
   9
  10         start
  11         usage
  12         kunit-tool
  13         api/index
  14         style
  15         faq
  16         tips
  17         running_tips
  18
  19 What is KUnit?
  20 ==============
  21
  22 KUnit is a lightweight unit testing and mocking framework for the Linux kernel.
  23
  24 KUnit is heavily inspired by JUnit, Python's unittest.mock, and
  25 Googletest/Googlemock for C++. KUnit provides facilities for defining unit test
  26 cases, grouping related test cases into test suites, providing common
  27 infrastructure for running tests, and much more.
  28
  29 KUnit consists of a kernel component, which provides a set of macros for easily
  30 writing unit tests. Tests written against KUnit will run on kernel boot if
  31 built-in, or when loaded if built as a module. These tests write out results to
  32 the kernel log in `TAP <https://testanything.org/>`_ format.
  33
  34 To make running these tests (and reading the results) easier, KUnit offers
  35 :doc:`kunit_tool <kunit-tool>`, which builds a `User Mode Linux
  36 <http://user-mode-linux.sourceforge.net>`_ kernel, runs it, and parses the test
  37 results. This provides a quick way of running KUnit tests during development,
  38 without requiring a virtual machine or separate hardware.
  39
  40 Get started now: Documentation/dev-tools/kunit/start.rst
  41
  42 Why KUnit?
  43 ==========
  44
  45 A unit test is supposed to test a single unit of code in isolation, hence the
  46 name. A unit test should be the finest granularity of testing and as such should
  47 allow all possible code paths to be tested in the code under test; this is only
  48 possible if the code under test is very small and does not have any external
  49 dependencies outside of the test's control like hardware.
  50
  51 KUnit provides a common framework for unit tests within the kernel.
  52
  53 KUnit tests can be run on most architectures, and most tests are architecture
  54 independent. All built-in KUnit tests run on kernel startup.  Alternatively,
  55 KUnit and KUnit tests can be built as modules and tests will run when the test
  56 module is loaded.
  57
  58 .. note::
  59
  60         KUnit can also run tests without needing a virtual machine or actual
  61         hardware under User Mode Linux. User Mode Linux is a Linux architecture,
  62         like ARM or x86, which compiles the kernel as a Linux executable. KUnit
  63         can be used with UML either by building with ``ARCH=um`` (like any other
  64         architecture), or by using :doc:`kunit_tool <kunit-tool>`.
  65
  66 KUnit is fast. Excluding build time, from invocation to completion KUnit can run
  67 several dozen tests in only 10 to 20 seconds; this might not sound like a big
  68 deal to some people, but having such fast and easy to run tests fundamentally
  69 changes the way you go about testing and even writing code in the first place.
  70 Linus himself said in his `git talk at Google
  71 <https://gist.github.com/lorn/1272686/revisions#diff-53c65572127855f1b003db4064a94573R874>`_:
  72
  73         "... a lot of people seem to think that performance is about doing the
  74         same thing, just doing it faster, and that is not true. That is not what
  75         performance is all about. If you can do something really fast, really
  76         well, people will start using it differently."
  77
  78 In this context Linus was talking about branching and merging,
  79 but this point also applies to testing. If your tests are slow, unreliable, are
  80 difficult to write, and require a special setup or special hardware to run,
  81 then you wait a lot longer to write tests, and you wait a lot longer to run
  82 tests; this means that tests are likely to break, unlikely to test a lot of
  83 things, and are unlikely to be rerun once they pass. If your tests are really
  84 fast, you run them all the time, every time you make a change, and every time
  85 someone sends you some code. Why trust that someone ran all their tests
  86 correctly on every change when you can just run them yourself in less time than
  87 it takes to read their test log?
  88
  89 How do I use it?
  90 ================
  91
  92 *   Documentation/dev-tools/kunit/start.rst - for new users of KUnit
  93 *   Documentation/dev-tools/kunit/tips.rst - for short examples of best practices
  94 *   Documentation/dev-tools/kunit/usage.rst - for a more detailed explanation of KUnit features
  95 *   Documentation/dev-tools/kunit/api/index.rst - for the list of KUnit APIs used for testing
  96 *   Documentation/dev-tools/kunit/kunit-tool.rst - for more information on the kunit_tool helper script
  97 *   Documentation/dev-tools/kunit/faq.rst - for answers to some common questions about KUnit