1 // SPDX-License-Identifier: GPL-2.0
2
3 //! KUnit-based macros for Rust unit tests.
4 //!
5 //! C header: [`include/kunit/test.h`](srctree/include/kunit/test.h)
6 //!
7 //! Reference: <https://docs.kernel.org/dev-tools/kunit/index.html>
8
9 use crate::fmt;
10 use crate::prelude::*;
11
12 #[cfg(CONFIG_PRINTK)]
13 use crate::c_str;
14
15 /// Prints a KUnit error-level message.
16 ///
17 /// Public but hidden since it should only be used from KUnit generated code.
18 #[doc(hidden)]
err(args: fmt::Arguments<'_>)19 pub fn err(args: fmt::Arguments<'_>) {
20 // SAFETY: The format string is null-terminated and the `%pA` specifier matches the argument we
21 // are passing.
22 #[cfg(CONFIG_PRINTK)]
23 unsafe {
24 bindings::_printk(
25 c_str!("\x013%pA").as_char_ptr(),
26 core::ptr::from_ref(&args).cast::<c_void>(),
27 );
28 }
29 }
30
31 /// Prints a KUnit info-level message.
32 ///
33 /// Public but hidden since it should only be used from KUnit generated code.
34 #[doc(hidden)]
info(args: fmt::Arguments<'_>)35 pub fn info(args: fmt::Arguments<'_>) {
36 // SAFETY: The format string is null-terminated and the `%pA` specifier matches the argument we
37 // are passing.
38 #[cfg(CONFIG_PRINTK)]
39 unsafe {
40 bindings::_printk(
41 c_str!("\x016%pA").as_char_ptr(),
42 core::ptr::from_ref(&args).cast::<c_void>(),
43 );
44 }
45 }
46
47 /// Asserts that a boolean expression is `true` at runtime.
48 ///
49 /// Public but hidden since it should only be used from generated tests.
50 ///
51 /// Unlike the one in `core`, this one does not panic; instead, it is mapped to the KUnit
52 /// facilities. See [`assert!`] for more details.
53 #[doc(hidden)]
54 #[macro_export]
55 macro_rules! kunit_assert {
56 ($name:literal, $file:literal, $diff:expr, $condition:expr $(,)?) => {
57 'out: {
58 // Do nothing if the condition is `true`.
59 if $condition {
60 break 'out;
61 }
62
63 static FILE: &'static $crate::str::CStr = $crate::c_str!($file);
64 static LINE: i32 = ::core::line!() as i32 - $diff;
65 static CONDITION: &'static $crate::str::CStr = $crate::c_str!(stringify!($condition));
66
67 // SAFETY: FFI call without safety requirements.
68 let kunit_test = unsafe { $crate::bindings::kunit_get_current_test() };
69 if kunit_test.is_null() {
70 // The assertion failed but this task is not running a KUnit test, so we cannot call
71 // KUnit, but at least print an error to the kernel log. This may happen if this
72 // macro is called from an spawned thread in a test (see
73 // `scripts/rustdoc_test_gen.rs`) or if some non-test code calls this macro by
74 // mistake (it is hidden to prevent that).
75 //
76 // This mimics KUnit's failed assertion format.
77 $crate::kunit::err($crate::prelude::fmt!(
78 " # {}: ASSERTION FAILED at {FILE}:{LINE}\n",
79 $name
80 ));
81 $crate::kunit::err($crate::prelude::fmt!(
82 " Expected {CONDITION} to be true, but is false\n"
83 ));
84 $crate::kunit::err($crate::prelude::fmt!(
85 " Failure not reported to KUnit since this is a non-KUnit task\n"
86 ));
87 break 'out;
88 }
89
90 #[repr(transparent)]
91 struct Location($crate::bindings::kunit_loc);
92
93 #[repr(transparent)]
94 struct UnaryAssert($crate::bindings::kunit_unary_assert);
95
96 // SAFETY: There is only a static instance and in that one the pointer field points to
97 // an immutable C string.
98 unsafe impl Sync for Location {}
99
100 // SAFETY: There is only a static instance and in that one the pointer field points to
101 // an immutable C string.
102 unsafe impl Sync for UnaryAssert {}
103
104 static LOCATION: Location = Location($crate::bindings::kunit_loc {
105 file: $crate::str::as_char_ptr_in_const_context(FILE),
106 line: LINE,
107 });
108 static ASSERTION: UnaryAssert = UnaryAssert($crate::bindings::kunit_unary_assert {
109 assert: $crate::bindings::kunit_assert {},
110 condition: $crate::str::as_char_ptr_in_const_context(CONDITION),
111 expected_true: true,
112 });
113
114 // SAFETY:
115 // - FFI call.
116 // - The `kunit_test` pointer is valid because we got it from
117 // `kunit_get_current_test()` and it was not null. This means we are in a KUnit
118 // test, and that the pointer can be passed to KUnit functions and assertions.
119 // - The string pointers (`file` and `condition` above) point to null-terminated
120 // strings since they are `CStr`s.
121 // - The function pointer (`format`) points to the proper function.
122 // - The pointers passed will remain valid since they point to `static`s.
123 // - The format string is allowed to be null.
124 // - There are, however, problems with this: first of all, this will end up stopping
125 // the thread, without running destructors. While that is problematic in itself,
126 // it is considered UB to have what is effectively a forced foreign unwind
127 // with `extern "C"` ABI. One could observe the stack that is now gone from
128 // another thread. We should avoid pinning stack variables to prevent library UB,
129 // too. For the moment, given that test failures are reported immediately before the
130 // next test runs, that test failures should be fixed and that KUnit is explicitly
131 // documented as not suitable for production environments, we feel it is reasonable.
132 unsafe {
133 $crate::bindings::__kunit_do_failed_assertion(
134 kunit_test,
135 ::core::ptr::addr_of!(LOCATION.0),
136 $crate::bindings::kunit_assert_type_KUNIT_ASSERTION,
137 ::core::ptr::addr_of!(ASSERTION.0.assert),
138 Some($crate::bindings::kunit_unary_assert_format),
139 ::core::ptr::null(),
140 );
141 }
142
143 // SAFETY: FFI call; the `test` pointer is valid because this hidden macro should only
144 // be called by the generated documentation tests which forward the test pointer given
145 // by KUnit.
146 unsafe {
147 $crate::bindings::__kunit_abort(kunit_test);
148 }
149 }
150 };
151 }
152
153 /// Asserts that two expressions are equal to each other (using [`PartialEq`]).
154 ///
155 /// Public but hidden since it should only be used from generated tests.
156 ///
157 /// Unlike the one in `core`, this one does not panic; instead, it is mapped to the KUnit
158 /// facilities. See [`assert!`] for more details.
159 #[doc(hidden)]
160 #[macro_export]
161 macro_rules! kunit_assert_eq {
162 ($name:literal, $file:literal, $diff:expr, $left:expr, $right:expr $(,)?) => {{
163 // For the moment, we just forward to the expression assert because, for binary asserts,
164 // KUnit supports only a few types (e.g. integers).
165 $crate::kunit_assert!($name, $file, $diff, $left == $right);
166 }};
167 }
168
169 trait TestResult {
is_test_result_ok(&self) -> bool170 fn is_test_result_ok(&self) -> bool;
171 }
172
173 impl TestResult for () {
is_test_result_ok(&self) -> bool174 fn is_test_result_ok(&self) -> bool {
175 true
176 }
177 }
178
179 impl<T, E> TestResult for Result<T, E> {
is_test_result_ok(&self) -> bool180 fn is_test_result_ok(&self) -> bool {
181 self.is_ok()
182 }
183 }
184
185 /// Returns whether a test result is to be considered OK.
186 ///
187 /// This will be `assert!`ed from the generated tests.
188 #[doc(hidden)]
189 #[expect(private_bounds)]
is_test_result_ok(t: impl TestResult) -> bool190 pub fn is_test_result_ok(t: impl TestResult) -> bool {
191 t.is_test_result_ok()
192 }
193
194 /// Represents an individual test case.
195 ///
196 /// The [`kunit_unsafe_test_suite!`] macro expects a NULL-terminated list of valid test cases.
197 /// Use [`kunit_case_null`] to generate such a delimiter.
198 #[doc(hidden)]
kunit_case( name: &'static kernel::str::CStr, run_case: unsafe extern "C" fn(*mut kernel::bindings::kunit), ) -> kernel::bindings::kunit_case199 pub const fn kunit_case(
200 name: &'static kernel::str::CStr,
201 run_case: unsafe extern "C" fn(*mut kernel::bindings::kunit),
202 ) -> kernel::bindings::kunit_case {
203 kernel::bindings::kunit_case {
204 run_case: Some(run_case),
205 name: kernel::str::as_char_ptr_in_const_context(name),
206 attr: kernel::bindings::kunit_attributes {
207 speed: kernel::bindings::kunit_speed_KUNIT_SPEED_NORMAL,
208 },
209 generate_params: None,
210 status: kernel::bindings::kunit_status_KUNIT_SUCCESS,
211 module_name: core::ptr::null_mut(),
212 log: core::ptr::null_mut(),
213 param_init: None,
214 param_exit: None,
215 }
216 }
217
218 /// Represents the NULL test case delimiter.
219 ///
220 /// The [`kunit_unsafe_test_suite!`] macro expects a NULL-terminated list of test cases. This
221 /// function returns such a delimiter.
222 #[doc(hidden)]
kunit_case_null() -> kernel::bindings::kunit_case223 pub const fn kunit_case_null() -> kernel::bindings::kunit_case {
224 kernel::bindings::kunit_case {
225 run_case: None,
226 name: core::ptr::null_mut(),
227 generate_params: None,
228 attr: kernel::bindings::kunit_attributes {
229 speed: kernel::bindings::kunit_speed_KUNIT_SPEED_NORMAL,
230 },
231 status: kernel::bindings::kunit_status_KUNIT_SUCCESS,
232 module_name: core::ptr::null_mut(),
233 log: core::ptr::null_mut(),
234 param_init: None,
235 param_exit: None,
236 }
237 }
238
239 /// Registers a KUnit test suite.
240 ///
241 /// # Safety
242 ///
243 /// `test_cases` must be a NULL terminated array of valid test cases,
244 /// whose lifetime is at least that of the test suite (i.e., static).
245 ///
246 /// # Examples
247 ///
248 /// ```ignore
249 /// extern "C" fn test_fn(_test: *mut kernel::bindings::kunit) {
250 /// let actual = 1 + 1;
251 /// let expected = 2;
252 /// assert_eq!(actual, expected);
253 /// }
254 ///
255 /// static mut KUNIT_TEST_CASES: [kernel::bindings::kunit_case; 2] = [
256 /// kernel::kunit::kunit_case(kernel::c_str!("name"), test_fn),
257 /// kernel::kunit::kunit_case_null(),
258 /// ];
259 /// kernel::kunit_unsafe_test_suite!(suite_name, KUNIT_TEST_CASES);
260 /// ```
261 #[doc(hidden)]
262 #[macro_export]
263 macro_rules! kunit_unsafe_test_suite {
264 ($name:ident, $test_cases:ident) => {
265 const _: () = {
266 const KUNIT_TEST_SUITE_NAME: [::kernel::ffi::c_char; 256] = {
267 let name_u8 = ::core::stringify!($name).as_bytes();
268 let mut ret = [0; 256];
269
270 if name_u8.len() > 255 {
271 panic!(concat!(
272 "The test suite name `",
273 ::core::stringify!($name),
274 "` exceeds the maximum length of 255 bytes."
275 ));
276 }
277
278 let mut i = 0;
279 while i < name_u8.len() {
280 ret[i] = name_u8[i] as ::kernel::ffi::c_char;
281 i += 1;
282 }
283
284 ret
285 };
286
287 static mut KUNIT_TEST_SUITE: ::kernel::bindings::kunit_suite =
288 ::kernel::bindings::kunit_suite {
289 name: KUNIT_TEST_SUITE_NAME,
290 #[allow(unused_unsafe)]
291 // SAFETY: `$test_cases` is passed in by the user, and
292 // (as documented) must be valid for the lifetime of
293 // the suite (i.e., static).
294 test_cases: unsafe {
295 ::core::ptr::addr_of_mut!($test_cases)
296 .cast::<::kernel::bindings::kunit_case>()
297 },
298 suite_init: None,
299 suite_exit: None,
300 init: None,
301 exit: None,
302 attr: ::kernel::bindings::kunit_attributes {
303 speed: ::kernel::bindings::kunit_speed_KUNIT_SPEED_NORMAL,
304 },
305 status_comment: [0; 256usize],
306 debugfs: ::core::ptr::null_mut(),
307 log: ::core::ptr::null_mut(),
308 suite_init_err: 0,
309 is_init: false,
310 };
311
312 #[used(compiler)]
313 #[allow(unused_unsafe)]
314 #[cfg_attr(not(target_os = "macos"), link_section = ".kunit_test_suites")]
315 static mut KUNIT_TEST_SUITE_ENTRY: *const ::kernel::bindings::kunit_suite =
316 // SAFETY: `KUNIT_TEST_SUITE` is static.
317 unsafe { ::core::ptr::addr_of_mut!(KUNIT_TEST_SUITE) };
318 };
319 };
320 }
321
322 /// Returns whether we are currently running a KUnit test.
323 ///
324 /// In some cases, you need to call test-only code from outside the test case, for example, to
325 /// create a function mock. This function allows to change behavior depending on whether we are
326 /// currently running a KUnit test or not.
327 ///
328 /// # Examples
329 ///
330 /// This example shows how a function can be mocked to return a well-known value while testing:
331 ///
332 /// ```
333 /// # use kernel::kunit::in_kunit_test;
334 /// fn fn_mock_example(n: i32) -> i32 {
335 /// if in_kunit_test() {
336 /// return 100;
337 /// }
338 ///
339 /// n + 1
340 /// }
341 ///
342 /// let mock_res = fn_mock_example(5);
343 /// assert_eq!(mock_res, 100);
344 /// ```
in_kunit_test() -> bool345 pub fn in_kunit_test() -> bool {
346 // SAFETY: `kunit_get_current_test()` is always safe to call (it has fallbacks for
347 // when KUnit is not enabled).
348 !unsafe { bindings::kunit_get_current_test() }.is_null()
349 }
350
351 #[kunit_tests(rust_kernel_kunit)]
352 mod tests {
353 use super::*;
354
355 #[test]
rust_test_kunit_example_test()356 fn rust_test_kunit_example_test() {
357 assert_eq!(1 + 1, 2);
358 }
359
360 #[test]
rust_test_kunit_in_kunit_test()361 fn rust_test_kunit_in_kunit_test() {
362 assert!(in_kunit_test());
363 }
364
365 #[test]
366 #[cfg(not(all()))]
rust_test_kunit_always_disabled_test()367 fn rust_test_kunit_always_disabled_test() {
368 // This test should never run because of the `cfg`.
369 assert!(false);
370 }
371 }
372