1.. SPDX-License-Identifier: GPL-2.0 2 3========================================= 4KUnit - 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 19What is KUnit? 20============== 21 22KUnit is a lightweight unit testing and mocking framework for the Linux kernel. 23 24KUnit is heavily inspired by JUnit, Python's unittest.mock, and 25Googletest/Googlemock for C++. KUnit provides facilities for defining unit test 26cases, grouping related test cases into test suites, providing common 27infrastructure for running tests, and much more. 28 29KUnit consists of a kernel component, which provides a set of macros for easily 30writing unit tests. Tests written against KUnit will run on kernel boot if 31built-in, or when loaded if built as a module. These tests write out results to 32the kernel log in `TAP <https://testanything.org/>`_ format. 33 34To 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 37results. This provides a quick way of running KUnit tests during development, 38without requiring a virtual machine or separate hardware. 39 40Get started now: Documentation/dev-tools/kunit/start.rst 41 42Why KUnit? 43========== 44 45A unit test is supposed to test a single unit of code in isolation, hence the 46name. A unit test should be the finest granularity of testing and as such should 47allow all possible code paths to be tested in the code under test; this is only 48possible if the code under test is very small and does not have any external 49dependencies outside of the test's control like hardware. 50 51KUnit provides a common framework for unit tests within the kernel. 52 53KUnit tests can be run on most architectures, and most tests are architecture 54independent. All built-in KUnit tests run on kernel startup. Alternatively, 55KUnit and KUnit tests can be built as modules and tests will run when the test 56module 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 66KUnit is fast. Excluding build time, from invocation to completion KUnit can run 67several dozen tests in only 10 to 20 seconds; this might not sound like a big 68deal to some people, but having such fast and easy to run tests fundamentally 69changes the way you go about testing and even writing code in the first place. 70Linus 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 78In this context Linus was talking about branching and merging, 79but this point also applies to testing. If your tests are slow, unreliable, are 80difficult to write, and require a special setup or special hardware to run, 81then you wait a lot longer to write tests, and you wait a lot longer to run 82tests; this means that tests are likely to break, unlikely to test a lot of 83things, and are unlikely to be rerun once they pass. If your tests are really 84fast, you run them all the time, every time you make a change, and every time 85someone sends you some code. Why trust that someone ran all their tests 86correctly on every change when you can just run them yourself in less time than 87it takes to read their test log? 88 89How 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 98