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
    release_notes
    mocking
    press

 What is KUnit?
 ==============

 KUnit is a lightweight unit testing 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, and more.

 Get started now: :doc:`usage/index`

 Who is it for?
 ==============

 If you work on the Linux kernel, then KUnit is for you.

 Why unit test the kernel?
 =========================

 The first question is, "why write unit tests in the first place?"

 A unit test is a test focused on testing a small "unit" of code. This is
 usually on the level of a few functions at most. Unit tests try to avoid
 external dependencies like hardware and/or stub them out where possible.

 This ideally makes unit tests more stable, faster, and easier to debug when
 they fail.

 In-kernel testing
 -----------------

 .. note::
 	In our case, "unit test" implies in-kernel test code. It's not really possible
 	to be a "unit test" if you're relying on a kernel working enough to have a
 	functional userspace on top of it.

 For internal libraries (e.g. ``include/linux/list.h``), there's no good way to
 test from userspace. It's *far* easier to write in-kernel code to test these.
 That are some tests that make this work, but if you're starting from scratch,
 just use KUnit.

 For code with a user facing component, you'll want some tests in userspace.
 But it can be useful to have unit tests as well. For example, it can be hard to
 trigger certain code paths from userspace, particularly error paths.
 Furthermore, it's probably much faster and more hermetic to build and run the
 tests under KUnit instead of booting a machine and waiting for all the needed
 userspace processes to come up.

 Why KUnit?
 ==========

 KUnit provides a library to help making writing tests easy: including making
 assertions, setting up and cleaning up test resources, and more.
 It also provides a `python script <third_party/kernel/docs/kunit-tool.html>`__
 to make building and running tests easy.

 kselftest has a way of writing unit tests as kernel modules via the helpers in
 ``tools/testing/selftests/kselftest_module.h``. But this requires more
 boilerplate scattered across several files and potentially several directories.

 UML
 ---

 KUnit is 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.

 The provided tooling (``tools/testing/kunit/kunit.py``) mainly works with UML,
 but you can use KUnit manually on different architectures, if wanted. See `here
 <third_party/kernel/docs/start.html>`__ for more details.

 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`.
	.. 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
	release_notes
	mocking
	press

	What is KUnit?
	==============

	KUnit is a lightweight unit testing 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, and more.

	Get started now: :doc:`usage/index`

	Who is it for?
	==============

	If you work on the Linux kernel, then KUnit is for you.

	Why unit test the kernel?
	=========================

	The first question is, "why write unit tests in the first place?"

	A unit test is a test focused on testing a small "unit" of code. This is
	usually on the level of a few functions at most. Unit tests try to avoid
	external dependencies like hardware and/or stub them out where possible.

	This ideally makes unit tests more stable, faster, and easier to debug when
	they fail.

	In-kernel testing
	-----------------

	.. note::
	In our case, "unit test" implies in-kernel test code. It's not really possible
	to be a "unit test" if you're relying on a kernel working enough to have a
	functional userspace on top of it.

	For internal libraries (e.g. ``include/linux/list.h``), there's no good way to
	test from userspace. It's far easier to write in-kernel code to test these.
	That are some tests that make this work, but if you're starting from scratch,
	just use KUnit.

	For code with a user facing component, you'll want some tests in userspace.
	But it can be useful to have unit tests as well. For example, it can be hard to
	trigger certain code paths from userspace, particularly error paths.
	Furthermore, it's probably much faster and more hermetic to build and run the
	tests under KUnit instead of booting a machine and waiting for all the needed
	userspace processes to come up.

	Why KUnit?
	==========

	KUnit provides a library to help making writing tests easy: including making
	assertions, setting up and cleaning up test resources, and more.
	It also provides a `python script <third_party/kernel/docs/kunit-tool.html>`__
	to make building and running tests easy.

	kselftest has a way of writing unit tests as kernel modules via the helpers in
	``tools/testing/selftests/kselftest_module.h``. But this requires more
	boilerplate scattered across several files and potentially several directories.

	UML
	---

	KUnit is 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.

	The provided tooling (``tools/testing/kunit/kunit.py``) mainly works with UML,
	but you can use KUnit manually on different architectures, if wanted. See `here
	<third_party/kernel/docs/start.html>`__ for more details.

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