Documentation/rust/testing.rst

1 .. SPDX-License-Identifier: GPL-2.0
6 This document contains useful information how to test the Rust code in the
7 kernel.
11 - The KUnit tests.
12 - The ``#[test]`` tests.
13 - The Kselftests.
16 ---------------
18 These are the tests that come from the examples in the Rust documentation. They
27 	./tools/testing/kunit/kunit.py run --make_options LLVM=1 --arch x86_64 --kconfig_add CONFIG_RUST=y
29 Alternatively, KUnit can run them as kernel built-in at boot. Refer to
30 Documentation/dev-tools/kunit/index.rst for the general KUnit documentation
31 and Documentation/dev-tools/kunit/architecture.rst for the details of kernel
32 built-in vs. command line testing.
37 	   Kernel hacking -> Kernel Testing and Coverage -> KUnit - Enable support for unit tests
39 	   Kernel hacking -> Rust hacking -> Doctests for the `kernel` crate
41 in the kernel config system.
52 .. code-block:: rust
59 	pub fn f(a: i32, b: i32) -> i32 {
63 In userspace, the tests are collected and run via ``rustdoc``. Using the tool
64 as-is would be useful already, since it allows verifying that examples compile
65 (thus enforcing they are kept in sync with the code they document) and as well
66 as running those that do not depend on in-kernel APIs.
68 For the kernel, however, these tests get transformed into KUnit test suites.
69 This means that doctests get compiled as Rust kernel objects, allowing them to
70 run against a built kernel.
73 testing facilities. For instance, the kernel log would look like::
80 	    # rust_doctest_kernel_build_assert_rs_0.location: rust/kernel/build_assert.rs:13
82 	    # rust_doctest_kernel_build_assert_rs_1.location: rust/kernel/build_assert.rs:56
84 	    # rust_doctest_kernel_init_rs_0.location: rust/kernel/init.rs:122
87 	    # rust_doctest_kernel_types_rs_2.location: rust/kernel/types.rs:150
93 Tests using the `? <https://doc.rust-lang.org/reference/expressions/operator-expr.html#the-question…
96 .. code-block:: rust
99 	/// # use kernel::{spawn_work_item, workqueue};
107 In order for developers to easily see which line of doctest code caused a
109 location (file and line) of the original test (i.e. instead of the location in
112 	# rust_doctest_kernel_types_rs_2.location: rust/kernel/types.rs:150
119 documentation do not need to care about which testing framework is used. In
120 addition, it may allow us to test third-party code more easily in the future.
122 A current limitation is that KUnit does not support assertions in other tasks.
123 Thus, we presently simply print an error to the kernel log if an assertion
127 ---------------------
134 This requires the kernel ``.config``. It runs the ``#[test]`` tests on the host
135 (currently) and thus is fairly limited in what these tests can test.
138 --------------
140 Kselftests are also available in the ``tools/testing/selftests/rust`` folder.
142 The kernel config options required for the tests are listed in the
148 The kselftests are built within the kernel source tree and are intended to
149 be executed on a system that is running the same kernel.
151 Once a kernel matching the source tree has been installed and booted, the
156 Refer to Documentation/dev-tools/kselftest.rst for the general Kselftest