blob: 55a8eb93548b7d70e7c484f84786304cdf882a1f [file] [log] [blame]
.. 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
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 developers 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 (and within Google, Kokonut) 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
- For stable KUnit:
- `Usage <third_party/stable_kernel/docs/usage.html>`__ - for a more detailed explanation of KUnit features
- `API <third_party/stable_kernel/docs/api>`__ - for the list of KUnit APIs used for testing
Where do I get it?
==================
- Upstream: https://git.kernel.org/pub/scm/linux/kernel/git/shuah/linux-kselftest.git/log/?h=next
- Stable: https://kunit.googlesource.com/linux/+/kunit/alpha/master
Not sure which one you want? Take a look at :doc:`usage/index`.
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`.