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