Getting Started

Installing dependencies

KUnit has the same dependencies as the Linux kernel. As long as you can buildthe kernel, you can run KUnit.

Running tests with the KUnit Wrapper

Included with KUnit is a simple Python wrapper which runs tests under User ModeLinux, and formats the test results.

The wrapper can be run with:

./tools/testing/kunit/kunit.py run

For more information on this wrapper (also called kunit_tool) check out thekunit_tool How-To page.

Creating a .kunitconfig

If you want to run a specific set of tests (rather than those listed in theKUnit defconfig), you can provide Kconfig options in the.kunitconfig file.This file essentially contains the regular Kernel config, with the specifictest targets as well. The.kunitconfig should also contain any other configoptions required by the tests.

A good starting point for a.kunitconfig is the KUnit defconfig:

cd$PATH_TO_LINUX_REPOcp arch/um/configs/kunit_defconfig .kunitconfig

You can then add any other Kconfig options you wish, e.g.:

CONFIG_LIST_KUNIT_TEST=y

kunit_tool will ensure that all config options set in.kunitconfig are set in the kernel.config before running the tests.It’ll warn you if you haven’t included the dependencies of the options you’reusing.

Note

Note that removing something from the.kunitconfig will not trigger arebuild of the.config file: the configuration is only updated if the.kunitconfig is not a subset of.config. This means that you can useother tools (such as make menuconfig) to adjust other config options.

Running the tests (KUnit Wrapper)

To make sure that everything is set up correctly, simply invoke the Pythonwrapper from your kernel repo:

./tools/testing/kunit/kunit.py run

Note

You may want to runmakemrproper first.

If everything worked correctly, you should see the following:

Generating .config ...Building KUnit Kernel ...Starting KUnit Kernel ...

followed by a list of tests that are run. All of them should be passing.

Note

Because it is building a lot of sources for the first time, theBuildingKUnitkernel step may take a while.

Running tests without the KUnit Wrapper

If you’d rather not use the KUnit Wrapper (if, for example, you need tointegrate with other systems, or use an architecture other than UML), KUnit canbe included in any kernel, and the results read out and parsed manually.

Note

KUnit is not designed for use in a production system, and it’s possible thattests may reduce the stability or security of the system.

Configuring the kernel

In order to enable KUnit itself, you simply need to enable theCONFIG_KUNITKconfig option (it’s under Kernel Hacking/Kernel Testing and Coverage inmenuconfig). From there, you can enable any KUnit tests you want: they usuallyhave config options ending in_KUNIT_TEST.

KUnit and KUnit tests can be compiled as modules: in this case the tests in amodule will be run when the module is loaded.

Running the tests (w/o KUnit Wrapper)

Build and run your kernel as usual. Test output will be written to the kernellog inTAP format.

Note

It’s possible that there will be other lines and/or data interspersed in theTAP output.

Writing your first test

In your kernel repo let’s add some code that we can test. Create a filedrivers/misc/example.h with the contents:

intmisc_example_add(intleft,intright);

create a filedrivers/misc/example.c:

#include<linux/errno.h>#include"example.h"intmisc_example_add(intleft,intright){returnleft+right;}

Now add the following lines todrivers/misc/Kconfig:

config MISC_EXAMPLEbool"My example"

and the following lines todrivers/misc/Makefile:

obj-$(CONFIG_MISC_EXAMPLE)+= example.o

Now we are ready to write the test. The test will be indrivers/misc/example-test.c:

#include<kunit/test.h>#include"example.h"/* Define the test cases. */staticvoidmisc_example_add_test_basic(structkunit*test){KUNIT_EXPECT_EQ(test,1,misc_example_add(1,0));KUNIT_EXPECT_EQ(test,2,misc_example_add(1,1));KUNIT_EXPECT_EQ(test,0,misc_example_add(-1,1));KUNIT_EXPECT_EQ(test,INT_MAX,misc_example_add(0,INT_MAX));KUNIT_EXPECT_EQ(test,-1,misc_example_add(INT_MAX,INT_MIN));}staticvoidmisc_example_test_failure(structkunit*test){KUNIT_FAIL(test,"This test never passes.");}staticstructkunit_casemisc_example_test_cases[]={KUNIT_CASE(misc_example_add_test_basic),KUNIT_CASE(misc_example_test_failure),{}};staticstructkunit_suitemisc_example_test_suite={.name="misc-example",.test_cases=misc_example_test_cases,};kunit_test_suite(misc_example_test_suite);

Now add the following todrivers/misc/Kconfig:

config MISC_EXAMPLE_TESTbool"Test for my example"depends on MISC_EXAMPLE&& KUNIT

and the following todrivers/misc/Makefile:

obj-$(CONFIG_MISC_EXAMPLE_TEST)+= example-test.o

Now add it to your.kunitconfig:

CONFIG_MISC_EXAMPLE=yCONFIG_MISC_EXAMPLE_TEST=y

Now you can run the test:

./tools/testing/kunit/kunit.py run

You should see the following failure:

...[16:08:57] [PASSED] misc-example:misc_example_add_test_basic[16:08:57] [FAILED] misc-example:misc_example_test_failure[16:08:57] EXPECTATION FAILED at drivers/misc/example-test.c:17[16:08:57]      This test never passes....

Congrats! You just wrote your first KUnit test!

Next Steps

  • Check out theUsing KUnit page for a morein-depth explanation of KUnit.