blob: 4fb012fa26fe5719942e1e758a8bc051727f03d4 [file] [log] [blame] [edit]
.. 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
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 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, and more.
Check out the `Getting Started <https://docs.kernel.org/dev-tools/kunit/start.html>`__ guide.
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 <https://docs.kernel.org/dev-tools/testing/run_wrapper.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.
Check out the `Kernel Testing Guide <https://docs.kernel.org/dev-tools/testing-overview.html>`__
for an overview of when to use KUnit.
kunit.py and UML
----------------
KUnit provides a simple python script, ``kunit.py`` which can automate configuring,
building, and running kernels with KUnit tests. It also parses test results in
`KTAP <https://docs.kernel.org/dev-tools/ktap.html>`__ format, providing a nice
summary.
To get started, run:
``./tools/testing/kunit/kunit.py run``
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``) uses UML by default,
but also integrates with QEMU to support other architectures.
How do I use it?
================
- `Getting Started <https://docs.kernel.org/dev-tools/kunit/start.html>`__ - for new users of KUnit
- `Documentation Index <https://docs.kernel.org/dev-tools/kunit/start.html>`__ - for an index of all KUnit docs
- `Running tests with kunit.py <https://docs.kernel.org/dev-tools/kunit/run_wrapper.html>`__ - how to use the KUnit tooling
- `Running tests without kunit.py <https://docs.kernel.org/dev-tools/kunit/run_manual.html>`__ - how to run tests manually or in other environment
- `Writing Tests <https://docs.kernel.org/dev-tools/kunit/usage.html>`__ - detailed tips for writing KUnit tests
- `Common Patterns <https://docs.kernel.org/dev-tools/kunit/usage.html#common-patterns>`__ - useful techniques for testing more complex code
- `Style Guide and Nomenclature <https://docs.kernel.org/dev-tools/kunit/style.html>`__ - what to name your tests, files, and modules
- `API Reference <https://docs.kernel.org/dev-tools/kunit/api/index.html>`__ - a reference of all KUnit APIs
- `Kernel Testing Guide <https://docs.kernel.org/dev-tools/testing-overview.html>`__ - when to use KUnit
- `Testing Rust Code <https://docs.kernel.org/rust/testing.html>`__ - how to test code written in Rust
All of these can also be found in the ``Documentation/`` directory in the kernel source tree.
Where do I get it?
==================
- Upstream: https://www.kernel.org/ (version 5.5 or later)
- KUnit can be found in the ``lib/kunit`` directory.
- ``kunit.py`` lives in the ``tools/testing/kunit`` directory.
Connect with us
===============
- Mailing Lists: 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`.