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