1 .. SPDX-License-Identifier: GPL-2.0
2
3 Testing
4 =======
5
6 This document contains useful information how to test the Rust code in the
7 kernel.
8
9 There are three sorts of tests:
10
11 - The KUnit tests.
12 - The ``#[test]`` tests.
13 - The Kselftests.
14
15 The KUnit tests
16 ---------------
17
18 These are the tests that come from the examples in the Rust documentation. They
19 get transformed into KUnit tests.
20
21 Usage
22 *****
23
24 These tests can be run via KUnit. For example via ``kunit_tool`` (``kunit.py``)
25 on the command line::
26
27 ./tools/testing/kunit/kunit.py run --make_options LLVM=1 --arch x86_64 --kconfig_add CONFIG_RUST=y
28
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.
33
34 To use these KUnit doctests, the following must be enabled::
35
36 CONFIG_KUNIT
37 Kernel hacking -> Kernel Testing and Coverage -> KUnit - Enable support for unit tests
38 CONFIG_RUST_KERNEL_DOCTESTS
39 Kernel hacking -> Rust hacking -> Doctests for the `kernel` crate
40
41 in the kernel config system.
42
43 KUnit tests are documentation tests
44 ***********************************
45
46 These documentation tests are typically examples of usage of any item (e.g.
47 function, struct, module...).
48
49 They are very convenient because they are just written alongside the
50 documentation. For instance:
51
52 .. code-block:: rust
53
54 /// Sums two numbers.
55 ///
56 /// ```
57 /// assert_eq!(mymod::f(10, 20), 30);
58 /// ```
59 pub fn f(a: i32, b: i32) -> i32 {
60 a + b
61 }
62
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.
67
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.
71
72 A benefit of this KUnit integration is that Rust doctests get to reuse existing
73 testing facilities. For instance, the kernel log would look like::
74
75 KTAP version 1
76 1..1
77 KTAP version 1
78 # Subtest: rust_doctests_kernel
79 1..59
80 # rust_doctest_kernel_build_assert_rs_0.location: rust/kernel/build_assert.rs:13
81 ok 1 rust_doctest_kernel_build_assert_rs_0
82 # rust_doctest_kernel_build_assert_rs_1.location: rust/kernel/build_assert.rs:56
83 ok 2 rust_doctest_kernel_build_assert_rs_1
84 # rust_doctest_kernel_init_rs_0.location: rust/kernel/init.rs:122
85 ok 3 rust_doctest_kernel_init_rs_0
86 ...
87 # rust_doctest_kernel_types_rs_2.location: rust/kernel/types.rs:150
88 ok 59 rust_doctest_kernel_types_rs_2
89 # rust_doctests_kernel: pass:59 fail:0 skip:0 total:59
90 # Totals: pass:59 fail:0 skip:0 total:59
91 ok 1 rust_doctests_kernel
92
93 Tests using the `? <https://doc.rust-lang.org/reference/expressions/operator-expr.html#the-question-mark-operator>`_
94 operator are also supported as usual, e.g.:
95
96 .. code-block:: rust
97
98 /// ```
99 /// # use kernel::{spawn_work_item, workqueue};
100 /// spawn_work_item!(workqueue::system(), || pr_info!("x"))?;
101 /// # Ok::<(), Error>(())
102 /// ```
103
104 The tests are also compiled with Clippy under ``CLIPPY=1``, just like normal
105 code, thus also benefitting from extra linting.
106
107 In order for developers to easily see which line of doctest code caused a
108 failure, a KTAP diagnostic line is printed to the log. This contains the
109 location (file and line) of the original test (i.e. instead of the location in
110 the generated Rust file)::
111
112 # rust_doctest_kernel_types_rs_2.location: rust/kernel/types.rs:150
113
114 Rust tests appear to assert using the usual ``assert!`` and ``assert_eq!``
115 macros from the Rust standard library (``core``). We provide a custom version
116 that forwards the call to KUnit instead. Importantly, these macros do not
117 require passing context, unlike those for KUnit testing (i.e.
118 ``struct kunit *``). This makes them easier to use, and readers of the
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.
121
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
124 actually failed. Additionally, doctests are not run for nonpublic functions.
125
126 The ``#[test]`` tests
127 ---------------------
128
129 Additionally, there are the ``#[test]`` tests. These can be run using the
130 ``rusttest`` Make target::
131
132 make LLVM=1 rusttest
133
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.
136
137 The Kselftests
138 --------------
139
140 Kselftests are also available in the ``tools/testing/selftests/rust`` folder.
141
142 The kernel config options required for the tests are listed in the
143 ``tools/testing/selftests/rust/config`` file and can be included with the aid
144 of the ``merge_config.sh`` script::
145
146 ./scripts/kconfig/merge_config.sh .config tools/testing/selftests/rust/config
147
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.
150
151 Once a kernel matching the source tree has been installed and booted, the
152 tests can be compiled and executed using the following command::
153
154 make TARGETS="rust" kselftest
155
156 Refer to Documentation/dev-tools/kselftest.rst for the general Kselftest
157 documentation.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.