| .. KUnit documentation master file, created by |
| sphinx-quickstart on Mon Aug 26 16:07:42 2019. |
| You can adapt this file completely to your liking, but it should at least |
| contain the root `toctree` directive. |
| |
| ===== |
| KUnit |
| ===== |
| |
| .. toctree:: |
| :maxdepth: 2 |
| :caption: Contents: |
| |
| usage/index |
| development/index |
| third_party/kernel/index.rst |
| third_party/stable_kernel/index.rst |
| press |
| |
| What is KUnit? |
| ============== |
| |
| KUnit is a lightweight unit testing and mocking framework for the Linux kernel. |
| These tests are able to be run locally on a developer’s workstation without a |
| VM or special hardware. |
| |
| KUnit is heavily inspired by JUnit, Python's unittest.mock, and |
| Googletest/Googlemock for C++. KUnit provides facilities for defining unit test |
| cases, grouping related test cases into test suites, providing common |
| infrastructure for running tests, mocking, spying, and much more. Get started |
| now: :doc:`usage/index` |
| |
| Who is it for? |
| ============== |
| |
| If you work on the Linux kernel, then KUnit is for you. |
| |
| Why KUnit? |
| ========== |
| |
| Aside from KUnit there is no true unit testing framework for the Linux kernel. |
| Autotest and kselftest are sometimes cited as unit testing frameworks; however, |
| they are not by most reasonable definitions of unit tests. |
| |
| A unit test is supposed to test a single unit of code in isolation, hence the |
| name. A unit test should be the finest granularity of testing and as such |
| should allow all possible code paths to be tested in the code under test; this |
| is only possible if the code under test is very small and does not have any |
| external dependencies outside of the test's control like hardware. |
| |
| As far as I know, outside of KUnit, there are no testing frameworks currently |
| available for the kernel that do not require installing the kernel on a test |
| machine or in a VM and all require tests to be written in userspace running on |
| the kernel; this is true for Autotest, kselftest, and Kokonut, disqualifying |
| any of them from being considered unit testing frameworks. |
| |
| KUnit addresses the problem of being able to run tests without needing a |
| virtual machine or actual hardware with User Mode Linux. User Mode Linux is a |
| Linux architecture, like ARM or x86; however, unlike other architectures it |
| compiles to a standalone program that can be run like any other program |
| directly inside of a host operating system; to be clear, it does not require |
| any virtualization support; it is just a regular program. User Mode Linux is |
| fast: on my desktop it boots to init process in under a second. |
| |
| How do I use it? |
| ================ |
| |
| - :doc:`usage/index` - for new users of KUnit |
| - For upstream KUnit: |
| - `Usage <third_party/kernel/docs/usage.html>`__ - for a more detailed explanation of KUnit features |
| - `API <third_party/kernel/docs/api>`__ - for the list of KUnit APIs used for testing |
| |
| Where do I get it? |
| ================== |
| |
| - Upstream: https://www.kernel.org/ (version 5.5 or later) |
| - Deprecated version: https://kunit.googlesource.com/linux/+/kunit/alpha/master |
| |
| Connect with us |
| =============== |
| |
| - Mailing List: kunit-dev@googlegroups.com |
| - Google Groups (web interface for above): https://groups.google.com/forum/#!forum/kunit-dev |
| - IRC: #kunit on oftc.net |
| - Riot: `#kunit:matrix.org <https://riot.im/app/#/room/#_oftc_#kunit:matrix.org>`_ |
| |
| Contributing |
| ============ |
| |
| If you want to contribute to KUnit in the Linux kernel (which is just the same |
| as contributing to the Linux kernel, please see `the Linux kernel's guide on |
| contributing |
| <https://www.kernel.org/doc/html/latest/#introduction-to-kernel-development>`_. |
| |
| For other KUnit repositories (CI/CD, vim plugin, etc), please see |
| :download:`CONTRIBUTING.md <CONTRIBUTING.md>`. |
| |
| In all cases, you will also want to take a look at :doc:`development/index`. |