Getting Started

This page contains an overview of the kunit_tool and KUnit framework,teaching how to run existing tests and then how to write a simple test case,and covers common problems users face when using KUnit for the first time.

Installing Dependencies

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

Running tests with kunit_tool

kunit_tool is a Python script, which configures and builds a kernel, runstests, and formats the test results. From the kernel repository, youcan run kunit_tool:

./tools/testing/kunit/kunit.pyrun

Note

You may see the following error:“The source tree is not clean, please run ‘make ARCH=um mrproper’”

This happens because internally kunit.py specifies.kunit(default option) as the build directory in the commandmakeO=output/dirthrough the argument--build_dir. Hence, before starting anout-of-tree build, the source tree must be clean.

There is also the same caveat mentioned in the “Build directory forthe kernel” section of theadmin-guide,that is, its use, it must be used for all invocations ofmake.The good news is that it can indeed be solved by runningmakeARCH=ummrproper, just be aware that this will delete thecurrent configuration and all generated files.

If everything worked correctly, you should see the following:

Configuring KUnit Kernel ...Building KUnit Kernel ...Starting KUnit Kernel ...

The tests will pass or fail.

Note

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

For detailed information on this wrapper, see:Running tests with kunit_tool.

Selecting which tests to run

By default, kunit_tool runs all tests reachable with minimal configuration,that is, using default values for most of the kconfig options. However,you can select which tests to run by:

Customizing Kconfig

A good starting point for the.kunitconfig is the KUnit default config.If you didn’t runkunit.pyrun yet, you can generate it by running:

cd$PATH_TO_LINUX_REPOtools/testing/kunit/kunit.pyconfigcat.kunit/.kunitconfig

Note

.kunitconfig lives in the--build_dir used by kunit.py, which is.kunit by default.

Before running the tests, kunit_tool ensures that all config optionsset in.kunitconfig are set in the kernel.config. It will warnyou if you have not included dependencies for the options used.

There are many ways to customize the configurations:

  1. Edit.kunit/.kunitconfig. The file should contain the list of kconfigoptions required to run the desired tests, including their dependencies.You may want to remove CONFIG_KUNIT_ALL_TESTS from the.kunitconfig asit will enable a number of additional tests that you may not want.If you need to run on an architecture other than UML seeRunning tests on QEMU.

  2. Enable additional kconfig options on top of.kunit/.kunitconfig.For example, to include the kernel’s linked-list test you can run:

    ./tools/testing/kunit/kunit.py run \        --kconfig_add CONFIG_LIST_KUNIT_TEST=y

  3. Provide the path of one or more .kunitconfig files from the tree.For example, to run onlyFAT_FS andEXT4 tests you can run:

    ./tools/testing/kunit/kunit.py run \        --kunitconfig ./fs/fat/.kunitconfig \        --kunitconfig ./fs/ext4/.kunitconfig

  4. If you change the.kunitconfig, kunit.py will trigger a rebuild of the.config file. But you can edit the.config file directly or withtools likemakemenuconfigO=.kunit. As long as its a superset of.kunitconfig, kunit.py won’t overwrite your changes.

Note

To save a .kunitconfig after finding a satisfactory configuration:

make savedefconfig O=.kunitcp .kunit/defconfig .kunit/.kunitconfig

Filtering tests by name

If you want to be more specific than Kconfig can provide, it is also possibleto select which tests to execute at boot-time by passing a glob filter(read instructions regarding the pattern in the manpageglob(7)).If there is a"." (period) in the filter, it will be interpreted as aseparator between the name of the test suite and the test case,otherwise, it will be interpreted as the name of the test suite.For example, let’s assume we are using the default config:

  1. inform the name of a test suite, like"kunit_executor_test",to run every test case it contains:

    ./tools/testing/kunit/kunit.py run "kunit_executor_test"

  2. inform the name of a test case prefixed by its test suite,like"example.example_simple_test", to run specifically that test case:

    ./tools/testing/kunit/kunit.py run "example.example_simple_test"

  3. use wildcard characters (*?[) to run any test case that matches the pattern,like"*.*64*" to run test cases containing"64" in the name insideany test suite:

    ./tools/testing/kunit/kunit.py run "*.*64*"

Running Tests without the KUnit Wrapper

If you do not want to use the KUnit Wrapper (for example: you want codeunder test to integrate with other systems, or use a different/unsupported architecture or configuration), KUnit can be included inany kernel, and the results are read out and parsed manually.

Note

CONFIG_KUNIT should not be enabled in a production environment.Enabling KUnit disables Kernel Address-Space Layout Randomization(KASLR), and tests may affect the state of the kernel in ways notsuitable for production.

Configuring the Kernel

To enable KUnit itself, you need to enable theCONFIG_KUNIT Kconfigoption (under Kernel Hacking/Kernel Testing and Coverage inmenuconfig). From there, you can enable any KUnit tests. Theyusually have config options ending in_KUNIT_TEST.

KUnit and KUnit tests can be compiled as modules. The tests in a modulewill run when the module is loaded.

Running Tests (without KUnit Wrapper)

Build and run your kernel. In the kernel log, the test output is printedout in the TAP format. This will only happen by default if KUnit/testsare built-in. Otherwise the module will need to be loaded.

Note

Some lines and/or data may get interspersed in the TAP output.

Writing Your First Test

In your kernel repository, let’s add some code that we can test.

  1. Create a filedrivers/misc/example.h, which includes:

intmisc_example_add(intleft,intright);

  1. Create a filedrivers/misc/example.c, which includes:

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

  1. Add the following lines todrivers/misc/Kconfig:

configMISC_EXAMPLEbool"My example"

  1. Add the following lines todrivers/misc/Makefile:

obj-$(CONFIG_MISC_EXAMPLE)+=example.o

Now we are ready to write the test cases.

  1. Add the below test case 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);MODULE_LICENSE("GPL");

  1. Add the following lines todrivers/misc/Kconfig:

configMISC_EXAMPLE_TESTtristate"Test for my example"if!KUNIT_ALL_TESTSdepends onMISC_EXAMPLE&&KUNITdefaultKUNIT_ALL_TESTS

Note: If your test does not support being built as a loadable module (which isdiscouraged), replace tristate by bool, and depend on KUNIT=y instead of KUNIT.

  1. Add the following lines todrivers/misc/Makefile:

obj-$(CONFIG_MISC_EXAMPLE_TEST)+=example_test.o

  1. Add the following lines to.kunit/.kunitconfig:

CONFIG_MISC_EXAMPLE=yCONFIG_MISC_EXAMPLE_TEST=y

  1. Run the test:

./tools/testing/kunit/kunit.pyrun

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

If you’re interested in using some of the more advanced features of kunit.py,take a look atRunning tests with kunit_tool

If you’d like to run tests without using kunit.py, check outRun Tests without kunit_tool

For more information on writing KUnit tests (including some common techniquesfor testing different things), seeWriting Tests