===========
Using KUnit
===========

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   getting_kunit
   faq

Where is KUnit?
:doc:`getting_kunit`


KUnit is integrated into the Linux kernel, so all you need is a version of the
kernel which contains KUnit, and a config file with which to build it. The
:doc: `getting_kunit` page covers the different versions of KUnit available, and
where to get them.


Running tests
=============

To run KUnit tests, you'll need to provide a 'kunitconfig' file, which contains
the list of test modules to build, and their dependencies.

Once you have the ``kunitconfig`` file, just run:

``$ ./tools/testing/kunit/kunit.py run``

This will build a UML (User Mode Linux) kernel, run the specified tests, and
print the results (nicely formatted) to the screen.


Writing tests
=============

Once you have KUnit working, writing tests is easy. Each test is a function
which accepts a ``struct kunit`` argument, and which calls the various
``KUNIT_EXPECT_*`` macros to verify the state under test.

More details can be found in the `Getting Started <../third_party/kernel/docs/start.html>`_
guide.


Submitting tests upstream
=========================

Ideally, KUnit tests will be submitted upstream alongside the code being tested,
so any user or developer can run the tests and test any changes they make. Once
KUnit itself is upstream, this means that KUnit tests should ideally be treated
as any other change, and submitted via the maintainer of the subsystem being
tested. (Though do feel free to copy in the ``kunit-dev@googlegroups.com`` list
if you want.)

For the time being, though, we recommend submitting patches via the
``linux-kselftest/test`` branch, which contains the version of KUnit likely to
head upstream. To do so, please send your patch via the
``linux-kselftest@vger.kernel.org`` list, and include ``linux-kselftest/test``
in the subject prefix. You should still get a review from the subsystem
maintainer, though.

And, of course, you should follow the general rules and guidelines laid out in
https://www.kernel.org/doc/html/latest/process/submitting-patches.html