.. 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
- For experimental 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://www.kernel.org/ (version 5.5 or later)
- Experimental: 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`.