KUnit Testing Framework

Relevant source files

The following files were used as context for generating this wiki page:

• Documentation/dev-tools/kunit/architecture.rst
• Documentation/dev-tools/kunit/index.rst
• Documentation/dev-tools/kunit/start.rst
• Documentation/dev-tools/kunit/style.rst
• Documentation/dev-tools/kunit/running_tips.rst
• Documentation/rust/testing.rst
• scripts/rustdoc_test_gen.rs

KUnit is the unit testing framework for the Linux kernel. It provides a common environment to define, run, and report the results of kernel-space tests written in C or Rust. KUnit follows a white-box testing approach, allowing tests to access internal system functionality not exposed to user-space.

The framework enables developers to group test cases into suites that run either during kernel boot (if built-in) or when a module loads. Results appear in the Kernel - Test Anything Protocol (KTAP) format, providing automated flagging and reporting of failed cases in the kernel log. KUnit supports testing various kernel components, including file systems, system calls, and device drivers, typically running hundreds of tests in seconds.

Sources: Documentation/dev-tools/kunit/index.rst:19-38, Documentation/dev-tools/kunit/architecture.rst:11-14

Core Architecture

KUnit architecture divides into two primary parts: the In-Kernel Testing Framework and the kunit_tool command-line harness.

In-Kernel Testing Framework

The in-kernel component manages the organization, execution, and reporting of tests. It uses specific data structures to define the hierarchy of testing units.

The diagram shows the relationship between suites, cases, and the test context object.
Sources: Documentation/dev-tools/kunit/architecture.rst:17-48, Documentation/dev-tools/kunit/running_tips.rst:228-243

Logical Testing Hierarchy

Tests are structured into a three-level hierarchy for organizational clarity:

• Subsystems: A collection of suites testing a specific driver or kernel part (e.g., ext4, apparmor).
• Suites: A group of related test cases within a subsystem. Suites can share initialization (init) and shutdown (exit) code.
• Test Cases: Individual functions that test a single codepath or property.

Sources: Documentation/dev-tools/kunit/style.rst:18-63

Execution Logic

KUnit tests run in a dedicated thread context. This isolation ensures that certain error classes in one test do not impact other tests or the kernel's overall stability.

Executor Flow

The KUnit executor manages the lifecycle of built-in tests during boot.

The flow shows how the executor iterates through linker-stored suites to run tests at boot.
Sources: Documentation/dev-tools/kunit/architecture.rst:55-75

Assertion Handling

KUnit uses expectations and assertions to verify state. Expectations log failures but allow the test to continue. Assertions terminate the test case immediately upon failure.

Feature	Expectation (KUNIT_EXPECT_...)	Assertion (KUNIT_ASSERT_...)
Failure Result	Marks test failed, logs failure.	Terminates test case immediately.
Execution Flow	Continues to next instruction.	Calls __kunit_abort() and exits thread.
Common Ops	EQ, TRUE, NOT_ERR_OR_NULL	EQ, TRUE, NOT_ERR_OR_NULL

Sources: Documentation/dev-tools/kunit/architecture.rst:79-106

Tooling and Configuration

kunit_tool

The Python script tools/testing/kunit/kunit.py serves as a wrapper to simplify the testing workflow. It performs four main commands:

1. config: Generates .config from .kunitconfig.
2. build: Compiles the kernel with the required options.
3. exec: Runs the kernel in UML or QEMU and captures the log.
4. parse: Extracts and formats KTAP output from the raw log.

Sources: Documentation/dev-tools/kunit/architecture.rst:118-142

Kconfig Requirements

Every test suite must be tied to a Kconfig entry following these rules:

• Named CONFIG_<NAME>_KUNIT_TEST.
• Depends on CONFIG_KUNIT.
• Visible only if CONFIG_KUNIT_ALL_TESTS is disabled (typically).
• Defaults to CONFIG_KUNIT_ALL_TESTS.

Sources: Documentation/dev-tools/kunit/style.rst:95-117

Rust Integration

KUnit supports Rust code through two primary methods: Documentation tests (doctests) and #[test] modules.

Doctests

Rust documentation examples are automatically transformed into KUnit test suites. This allows developers to write usage examples that are verified against the running kernel.

• Transformation: scripts/rustdoc_test_gen.rs generates C declarations and Rust wrappers for tests extracted by rustdoc.
• Macros: KUnit provides custom versions of assert! and assert_eq! for Rust that forward calls to the KUnit framework without requiring a manual context pointer.

Sources: Documentation/rust/testing.rst:26-64, scripts/rustdoc_test_gen.rs:136-180

Attributes and Filtering

Tests can be marked with attributes like speed (normal, slow, very_slow) to facilitate selective execution.

The diagram illustrates the resolution logic for test attributes during filtering.
Sources: Documentation/dev-tools/kunit/running_tips.rst:296-306

Summary

KUnit provides a high-speed, kernel-native testing environment that integrates with both C and Rust. By utilizing a specific linker section for test suites and providing a user-friendly Python wrapper, it enables fast "Arrange-Act-Assert" cycles within kernel development. Its use of KTAP ensures compatibility with standard kernel testing infrastructure like Kselftest.

Sources: Documentation/dev-tools/kunit/index.rst:40-54, Documentation/dev-tools/kunit/architecture.rst:108-112