On Sat, 3 May 2025 at 05:52, Miguel Ojeda <oj...@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 <oj...@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 <david...@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 >
smime.p7s
Description: S/MIME Cryptographic Signature
