index.rst - kunit-website - Git at Google

 .. 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 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 (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`.
	.. 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 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 (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`.