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