On Sat, 3 May 2025 at 05:52, Miguel Ojeda ojeda@kernel.org wrote:
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.
Signed-off-by: Miguel Ojeda ojeda@kernel.org
Assuming all of the other changes go through, this looks good to me.
It _may_ be useful to add some notes about when to choose KUnit tests versus rusttest host tests: particularly around cross-compiling and/or the need to call kernel APIs / access global kernel state. But some of that is covered in the general kernel testing / KUnit documentation in Documentation/dev-tools, anyway.
Reviewed-by: David Gow davidgow@google.com
Cheers, -- David
Documentation/rust/testing.rst | 71 ++++++++++++++++++++++++++++++++++ 1 file changed, 71 insertions(+)
diff --git a/Documentation/rust/testing.rst b/Documentation/rust/testing.rst index 6337b83815ab..f43cb77bcc69 100644 --- a/Documentation/rust/testing.rst +++ b/Documentation/rust/testing.rst @@ -130,6 +130,77 @@ please see:
https://rust.docs.kernel.org/kernel/error/type.Result.html#error-codes-in-c-and-rust+The ``#[test]`` tests +---------------------
+Additionally, there are the ``#[test]`` tests. Like for documentation tests, +these are also fairly similar to what you would expect from userspace, and they +are also mapped to KUnit.
+These tests are introduced by the ``kunit_tests`` procedural macro, which takes +the name of the test suite as an argument.
+For instance, assume we want to test the function ``f`` from the documentation +tests section. We could write, in the same file where we have our function:
+.. code-block:: rust
#[kunit_tests(rust_kernel_mymod)]mod tests {use super::*;#[test]fn test_f() {assert_eq!(f(10, 20), 30);}}+And if we run it, the kernel log would look like::
KTAP version 1# Subtest: rust_kernel_mymod# speed: normal1..1# test_f.speed: normalok 1 test_fok 1 rust_kernel_mymod+Like documentation tests, the ``assert!`` and ``assert_eq!`` macros are mapped +back to KUnit and do not panic. Similarly, the +`? https://doc.rust-lang.org/reference/expressions/operator-expr.html#the-question-mark-operator`_ +operator is supported, i.e. the test functions may return either nothing (i.e. +the unit type ``()``) or ``Result`` (i.e. any ``Result<T, E>``). For instance:
+.. code-block:: rust
#[kunit_tests(rust_kernel_mymod)]mod tests {use super::*;#[test]fn test_g() -> Result {let x = g()?;assert_eq!(x, 30);Ok(())}}+If we run the test and the call to ``g`` fails, then the kernel log would show::
KTAP version 1# Subtest: rust_kernel_mymod# speed: normal1..1# test_g: ASSERTION FAILED at rust/kernel/lib.rs:335Expected is_test_result_ok(test_g()) to be true, but is false# test_g.speed: normalnot ok 1 test_gnot ok 1 rust_kernel_mymod+If a ``#[test]`` test could be useful as an example for the user, then please +use a documentation test instead. Even edge cases of an API, e.g. error or +boundary cases, can be interesting to show in examples.
The ``rusttest`` host tests
-- 2.49.0