Using KUnit

Contents:

Where is KUnit? 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 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

Tip

You may want to run KUnit with flags like:

./tools/testing/kunit/kunit.py run --timeout=30 --jobs=24 --defconfig

  • --timeout sets a maximum amount of time to allow tests to run.

  • --jobs sets the number of threads to use to build the kernel.

  • --defconfig uses an default kunitconfig in the kernel source.

For more information on these and other flags, try running:

./tools/testing/kunit/kunit.py run --help

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

Tip

If you get the error message: /bin/sh: flex: command not found or similarly /bin/sh: bison: command not found, you are most likely missing the flex and bison packages. On a system using the apt package manager you can install them with

sudo apt-get install flex bison

For more information on building the kernel, see https://www.kernel.org/doc/html/latest/process/changes.html

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 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. Unless they affect KUnit itself, 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 changes to KUnit itself, we recommend submitting patches via the linux-kselftest/kunit 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. You should still get a review from any relevant the subsystem maintainers, 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