[7/7] 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.

Signed-off-by: Miguel Ojeda <ojeda@kernel.org>
---
 Documentation/rust/testing.rst | 71 ++++++++++++++++++++++++++++++++++
 1 file changed, 71 insertions(+)

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: normal
> +           1..1
> +           # test_f.speed: normal
> +           ok 1 test_f
> +       ok 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: normal
> +           1..1
> +           # test_g: ASSERTION FAILED at rust/kernel/lib.rs:335
> +           Expected is_test_result_ok(test_g()) to be true, but is false
> +           # test_g.speed: normal
> +           not ok 1 test_g
> +       not 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
>