Text of docs.kernel.org › dev-tools › kunit › run_wrapper.html as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Running tests with kunit_tool — The Linux Kernel documentation

The Linux Kernel 7.4.0-rc3 Quick search Contents Working with the development community Development process Submitting patches Code of conduct Maintainer handbook All development-process docs Internal API manuals Core API Driver APIs Subsystems Locking Development tools and processes Licensing rules Writing documentation Development tools Kernel Testing Guide Checkpatch clang-format Coccinelle Compiler-Based Context Analysis Sparse KCOV: code coverage for fuzzing Using gcov with the Linux kernel Kernel Address Sanitizer (KASAN) Kernel Memory Sanitizer (KMSAN) Undefined Behavior Sanitizer - UBSAN Kernel Memory Leak Detector Kernel Concurrency Sanitizer (KCSAN) Linux Kernel Memory Consistency Model (LKMM) Kernel Electric-Fence (KFENCE) Linux Kernel Selftests KUnit - Linux Kernel Unit Testing Getting Started KUnit Architecture Running tests with kunit_tool Run Tests without kunit_tool Writing Tests Common Patterns API Reference Test Style and Nomenclature Frequently Asked Questions Tips For Running KUnit Tests Introduction Unit Testing How do I use it?

The Kernel Test Anything Protocol (KTAP), version 1 UAPI Checker Linux Kernel GPIO based sloppy logic analyzer Using AutoFDO with the Linux kernel Using Propeller with the Linux kernel Containerized Builds Testing guide Hacking guide Tracing Fault injection Livepatching Rust User-oriented documentation Administration Build system Reporting issues Userspace tools Userspace API Firmware-related documentation Firmware Firmware and Devicetree Architecture-specific documentation CPU architectures Other documentation Unsorted documentation Translations Translations This Page Show Source Running tests with kunit_tool ¶ We can either run KUnit tests using kunit_tool or can run tests manually, and then use kunit_tool to parse the results.

To run tests manually, see: Run Tests without kunit_tool . As long as we can build the kernel, we can run KUnit. kunit_tool is a Python script which configures and builds a kernel, runs tests, and formats the test results. Run command: ./tools/testing/kunit/kunit.py run We should see the following: Configuring KUnit Kernel ... Building KUnit kernel... Starting KUnit kernel... We may want to use the following options: ./tools/testing/kunit/kunit.py run --timeout=30 --jobs=`nproc --all` --timeout sets a maximum amount of time for tests to run. --jobs sets the number of threads to build the kernel. kunit_tool will generate a .kunitconfig with a default configuration, if no other .kunitconfig file exists (in the build directory).

In addition, it verifies that the generated .config file contains the CONFIG options in the .kunitconfig . It is also possible to pass a separate .kunitconfig fragment to kunit_tool. This is useful if we have several different groups of tests we want to run independently, or if we want to use pre-defined test configs for certain subsystems. To use a different .kunitconfig file (such as one provided to test a particular subsystem), pass it as an option: ./tools/testing/kunit/kunit.py run --kunitconfig=fs/ext4/.kunitconfig To view kunit_tool flags (optional command-line arguments), run: ./tools/testing/kunit/kunit.py run --help Creating a .kunitconfig file ¶ If we want to run a specific set of tests (rather than those listed in the KUnit defconfig ), we can provide Kconfig options in the .kunitconfig file.

For default .kunitconfig, see: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/tools/testing/kunit/configs/default.config . A .kunitconfig is a minconfig (a .config generated by running make savedefconfig ), used for running a specific set of tests. This file contains the regular Kernel configs with specific test targets. The .kunitconfig also contains any other config options required by the tests (For example: dependencies for features under tests, configs that enable/disable certain code blocks, arch configs and so on).

To create a .kunitconfig , using the KUnit defconfig : cd $PATH_TO_LINUX_REPO cp tools/testing/kunit/configs/default.config .kunit/.kunitconfig We can then add any other Kconfig options. For example: CONFIG_LIST_KUNIT_TEST=y kunit_tool ensures that all config options in .kunitconfig are set in the kernel .config before running the tests. It warns if we have not included the options dependencies. Note Removing something from the .kunitconfig will not rebuild the .config file .

The configuration is only updated if the .kunitconfig is not a subset of .config . This means that we can use other tools (For example: make menuconfig ) to adjust other config options. The build dir needs to be set for make menuconfig to work, therefore by default use make O=.kunit menuconfig . Configuring, building, and running tests ¶ If we want to make manual changes to the KUnit build process, we can run part of the KUnit build process independently.

When running kunit_tool, from a .kunitconfig , we can generate a .config by using the config argument: ./tools/testing/kunit/kunit.py config To build a KUnit kernel from the current .config , we can use the build argument: ./tools/testing/kunit/kunit.py build If we already have built UML kernel with built-in KUnit tests, we can run the kernel, and display the test results with the exec argument: ./tools/testing/kunit/kunit.py exec The run command discussed in section: Running tests with kunit_tool , is equivalent to running the above three commands in sequence.

Parsing test results ¶ KUnit tests output displays results in TAP (Test Anything Protocol) format. When running tests, kunit_tool parses this output and prints a summary. To see the raw test results in TAP format, we can pass the --raw_output argument: ./tools/testing/kunit/kunit.py run --raw_output If we have KUnit results in the raw TAP format, we can parse them and print the human-readable summary with the parse command for kunit_tool.

This accepts a filename for an argument, or will read from standard input. # Reading from a file ./tools/testing/kunit/kunit.py parse /var/log/dmesg # Reading from stdin dmesg | ./tools/testing/kunit/kunit.py parse Filtering tests ¶ By passing a bash style glob filter to the exec or run commands, we can run a subset of the tests built into a kernel . For example: if we only want to run KUnit resource tests, use: ./tools/testing/kunit/kunit.py run 'kunit-resource*' This uses the standard glob format with wildcard characters.

Running tests on QEMU ¶ kunit_tool supports running tests on qemu as well as via UML. To run tests on qemu, by default it requires two flags: --arch : Selects a configs collection (Kconfig, qemu config options and so on), that allow KUnit tests to be run on the specified architecture in a minimal way. The architecture argument is same as the option name passed to the ARCH variable used by Kbuild. Not all architectures currently support this flag, but we can use --qemu_config to handle it.

If um is passed (or this flag is ignored), the tests will run via UML. Non-UML architectures, for example: i386, x86_64, arm and so on; run on qemu. --arch help lists all valid --arch values. --cross_compile : Specifies the Kbuild toolchain. It passes the same argument as passed to the CROSS_COMPILE variable used by Kbuild. As a reminder, this will be the prefix for the toolchain binaries such as GCC. For example: sparc64-linux-gnu if we have the sparc toolchain installed on our system. $HOME/toolchains/microblaze/gcc-9.2.0-nolibc/microblaze-linux/bin/microblaze-linux if we have downloaded the microblaze toolchain from the 0-day website to a directory in our home directory called toolchains.

This means that for most architectures, running under qemu is as simple as: ./tools/testing/kunit/kunit.py run --arch = x86_64 When cross-compiling, we’ll likely need to specify a different toolchain, for example: ./tools/testing/kunit/kunit.py run \ --arch = s390 \ --cross_compile = s390x-linux-gnu- If we want to run KUnit tests on an architecture not supported by the --arch flag, or want to run KUni

The rest of this page is on the live site.