Skip to content

Commit a3b2347

Browse files
committed
Documentation: rust: testing: add docs on the new KUnit #[test] tests
There was no documentation yet on the KUnit-based `#[test]`s. Thus add it now. It includes an explanation about the `assert*!` macros being mapped to KUnit and the support for `-> Result` introduced in these series. Reviewed-by: David Gow <[email protected]> Acked-by: Danilo Krummrich <[email protected]> Link: https://lore.kernel.org/r/[email protected] Signed-off-by: Miguel Ojeda <[email protected]>
1 parent 0a8d4ea commit a3b2347

File tree

1 file changed

+71
-0
lines changed

1 file changed

+71
-0
lines changed

Documentation/rust/testing.rst

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -130,6 +130,77 @@ please see:
130130

131131
https://rust.docs.kernel.org/kernel/error/type.Result.html#error-codes-in-c-and-rust
132132

133+
The ``#[test]`` tests
134+
---------------------
135+
136+
Additionally, there are the ``#[test]`` tests. Like for documentation tests,
137+
these are also fairly similar to what you would expect from userspace, and they
138+
are also mapped to KUnit.
139+
140+
These tests are introduced by the ``kunit_tests`` procedural macro, which takes
141+
the name of the test suite as an argument.
142+
143+
For instance, assume we want to test the function ``f`` from the documentation
144+
tests section. We could write, in the same file where we have our function:
145+
146+
.. code-block:: rust
147+
148+
#[kunit_tests(rust_kernel_mymod)]
149+
mod tests {
150+
use super::*;
151+
152+
#[test]
153+
fn test_f() {
154+
assert_eq!(f(10, 20), 30);
155+
}
156+
}
157+
158+
And if we run it, the kernel log would look like::
159+
160+
KTAP version 1
161+
# Subtest: rust_kernel_mymod
162+
# speed: normal
163+
1..1
164+
# test_f.speed: normal
165+
ok 1 test_f
166+
ok 1 rust_kernel_mymod
167+
168+
Like documentation tests, the ``assert!`` and ``assert_eq!`` macros are mapped
169+
back to KUnit and do not panic. Similarly, the
170+
`? <https://doc.rust-lang.org/reference/expressions/operator-expr.html#the-question-mark-operator>`_
171+
operator is supported, i.e. the test functions may return either nothing (i.e.
172+
the unit type ``()``) or ``Result`` (i.e. any ``Result<T, E>``). For instance:
173+
174+
.. code-block:: rust
175+
176+
#[kunit_tests(rust_kernel_mymod)]
177+
mod tests {
178+
use super::*;
179+
180+
#[test]
181+
fn test_g() -> Result {
182+
let x = g()?;
183+
assert_eq!(x, 30);
184+
Ok(())
185+
}
186+
}
187+
188+
If we run the test and the call to ``g`` fails, then the kernel log would show::
189+
190+
KTAP version 1
191+
# Subtest: rust_kernel_mymod
192+
# speed: normal
193+
1..1
194+
# test_g: ASSERTION FAILED at rust/kernel/lib.rs:335
195+
Expected is_test_result_ok(test_g()) to be true, but is false
196+
# test_g.speed: normal
197+
not ok 1 test_g
198+
not ok 1 rust_kernel_mymod
199+
200+
If a ``#[test]`` test could be useful as an example for the user, then please
201+
use a documentation test instead. Even edge cases of an API, e.g. error or
202+
boundary cases, can be interesting to show in examples.
203+
133204
The ``rusttest`` host tests
134205
---------------------------
135206

0 commit comments

Comments
 (0)