KUnit - Linux Kernel Unit Testing — The Linux Kernel 5.18.5-gnu-1 documentation

# KUnit - Linux Kernel Unit Testing

Contents:

- Getting Started
  - Installing Dependencies
  - Running tests with kunit_tool
  - Running Tests without the KUnit Wrapper
  - Writing Your First Test
  - Next Steps
- KUnit Architecture
  - In-Kernel Testing Framework
  - kunit_tool (Command Line Test Harness)
- Run Tests with kunit_tool
  - Create a `.kunitconfig` File
  - Configure, Build, and Run Tests
  - Parse Test Results
  - Run Selected Test Suites
  - Run Tests on qemu
  - Command-Line Arguments
- Run Tests without kunit_tool
  - Configure the Kernel
- Writing Tests
  - Test Cases
  - Writing Tests For Other Architectures
- Common Patterns
  - Isolating Behavior
  - Testing Against Multiple Inputs
  - Exiting Early on Failed Expectations
  - Allocating Memory
  - Testing Static Functions
  - Injecting Test-Only Code
  - Accessing The Current Test
  - Failing The Current Test
- kunit_tool How-To
  - What is kunit_tool?
  - What is a .kunitconfig?
  - Getting Started with kunit_tool
  - Configuring, Building, and Running Tests
  - Parsing Test Results
  - Filtering Tests
  - Running Tests on QEMU
  - Other Useful Options
- API Reference
  - Test API
- Test Style and Nomenclature
  - Subsystems, Suites, and Tests
  - Test Kconfig Entries
  - Test File and Module Names
- Frequently Asked Questions
  - How is this different from Autotest, kselftest, and so on?
  - Does KUnit support running on architectures other than UML?
  - What is the difference between a unit test and other kinds of tests?
  - KUnit is not working, what should I do?
- Tips For Writing KUnit Tests
  - Exiting early on failed expectations
  - Allocating memory
  - Testing static functions
  - Injecting test-only code
  - Accessing the current test
  - Failing the current test
  - Customizing error messages
- Tips For Running KUnit Tests
  - Using `kunit.py run` (“kunit tool”)
  - Running tests manually

This section details the kernel unit testing framework.

## Introduction

KUnit (Kernel unit testing framework) provides a common framework for unit tests within the Linux kernel. Using KUnit, you can define groups of test cases called test suites. The tests either run on kernel boot if built-in, or load as a module. KUnit automatically flags and reports failed test cases in the kernel log. The test results appear in TAP (Test Anything Protocol) format. It is inspired by JUnit, Python’s unittest.mock, and GoogleTest/GoogleMock (C++ unit testing framework).

KUnit tests are part of the kernel, written in the C (programming) language, and test parts of the Kernel implementation (example: a C language function). Excluding build time, from invocation to completion, KUnit can run around 100 tests in less than 10 seconds. KUnit can test any kernel component, for example: file system, system calls, memory management, device drivers and so on.

KUnit follows the white-box testing approach. The test has access to internal system functionality. KUnit runs in kernel space and is not restricted to things exposed to user-space.

In addition, KUnit has kunit_tool, a script (`tools/testing/kunit/kunit.py`) that configures the Linux kernel, runs KUnit tests under QEMU or UML (User Mode Linux), parses the test results and displays them in a user friendly manner.

### Features

- Provides a framework for writing unit tests.

- Runs tests on any kernel architecture.

- Runs a test in milliseconds.

### Prerequisites

- Any Linux kernel compatible hardware.

- For Kernel under test, Linux kernel version 5.5 or greater.

## Unit Testing

A unit test tests a single unit of code in isolation. A unit test is the finest granularity of testing and allows all possible code paths to be tested in the code under test. This is possible if the code under test is small and does not have any external dependencies outside of the test’s control like hardware.

### Write Unit Tests

To write good unit tests, there is a simple but powerful pattern: Arrange-Act-Assert. This is a great way to structure test cases and defines an order of operations.

- Arrange inputs and targets: At the start of the test, arrange the data that allows a function to work. Example: initialize a statement or object.

- Act on the target behavior: Call your function/code under test.

- Assert expected outcome: Verify that the result (or resulting state) is as expected.

### Unit Testing Advantages

- Increases testing speed and development in the long run.

- Detects bugs at initial stage and therefore decreases bug fix cost compared to acceptance testing.

- Improves code quality.

- Encourages writing testable code.

## How do I use it?

- Getting Started - for KUnit new users.

- KUnit Architecture - KUnit architecture.

- Run Tests with kunit_tool - run kunit_tool.

- Run Tests without kunit_tool - run tests without kunit_tool.

- Writing Tests - write tests.

- Tips For Writing KUnit Tests - best practices with examples.

- API Reference - KUnit APIs used for testing.

- kunit_tool How-To - kunit_tool helper script.

- Frequently Asked Questions - KUnit common questions and answers.