1 .. SPDX-License-Identifier: GPL-2.0
2
3 Testing
4 =======
5
6 This document contains useful information how
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 example
19 get transformed into KUnit tests.
20
21 Usage
22 *****
23
24 These tests can be run via KUnit. For example
25 on the command line::
26
27 ./tools/testing/kunit/kunit.py run --m
28
29 Alternatively, KUnit can run them as kernel bu
30 Documentation/dev-tools/kunit/index.rst for th
31 and Documentation/dev-tools/kunit/architecture
32 built-in vs. command line testing.
33
34 To use these KUnit doctests, the following mus
35
36 CONFIG_KUNIT
37 Kernel hacking -> Kernel Testing an
38 CONFIG_RUST_KERNEL_DOCTESTS
39 Kernel hacking -> Rust hacking -> D
40
41 in the kernel config system.
42
43 KUnit tests are documentation tests
44 ***********************************
45
46 These documentation tests are typically exampl
47 function, struct, module...).
48
49 They are very convenient because they are just
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
64 as-is would be useful already, since it allows
65 (thus enforcing they are kept in sync with the
66 as running those that do not depend on in-kern
67
68 For the kernel, however, these tests get trans
69 This means that doctests get compiled as Rust
70 run against a built kernel.
71
72 A benefit of this KUnit integration is that Ru
73 testing facilities. For instance, the kernel l
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
81 ok 1 rust_doctest_kernel_build_ass
82 # rust_doctest_kernel_build_assert
83 ok 2 rust_doctest_kernel_build_ass
84 # rust_doctest_kernel_init_rs_0.lo
85 ok 3 rust_doctest_kernel_init_rs_0
86 ...
87 # rust_doctest_kernel_types_rs_2.l
88 ok 59 rust_doctest_kernel_types_rs
89 # rust_doctests_kernel: pass:59 fail:0
90 # Totals: pass:59 fail:0 skip:0 total:
91 ok 1 rust_doctests_kernel
92
93 Tests using the `? <https://doc.rust-lang.org/
94 operator are also supported as usual, e.g.:
95
96 .. code-block:: rust
97
98 /// ```
99 /// # use kernel::{spawn_work_item, wo
100 /// spawn_work_item!(workqueue::system
101 /// # Ok::<(), Error>(())
102 /// ```
103
104 The tests are also compiled with Clippy under
105 code, thus also benefitting from extra linting
106
107 In order for developers to easily see which li
108 failure, a KTAP diagnostic line is printed to
109 location (file and line) of the original test
110 the generated Rust file)::
111
112 # rust_doctest_kernel_types_rs_2.locat
113
114 Rust tests appear to assert using the usual ``
115 macros from the Rust standard library (``core`
116 that forwards the call to KUnit instead. Impor
117 require passing context, unlike those for KUni
118 ``struct kunit *``). This makes them easier to
119 documentation do not need to care about which
120 addition, it may allow us to test third-party
121
122 A current limitation is that KUnit does not su
123 Thus, we presently simply print an error to th
124 actually failed. Additionally, doctests are no
125
126 The ``#[test]`` tests
127 ---------------------
128
129 Additionally, there are the ``#[test]`` tests.
130 ``rusttest`` Make target::
131
132 make LLVM=1 rusttest
133
134 This requires the kernel ``.config``. It runs
135 (currently) and thus is fairly limited in what
136
137 The Kselftests
138 --------------
139
140 Kselftests are also available in the ``tools/t
141
142 The kernel config options required for the tes
143 ``tools/testing/selftests/rust/config`` file a
144 of the ``merge_config.sh`` script::
145
146 ./scripts/kconfig/merge_config.sh .con
147
148 The kselftests are built within the kernel sou
149 be executed on a system that is running the sa
150
151 Once a kernel matching the source tree has bee
152 tests can be compiled and executed using the f
153
154 make TARGETS="rust" kselftest
155
156 Refer to Documentation/dev-tools/kselftest.rst
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.