Commit a3b23473 authored by Miguel Ojeda's avatar Miguel Ojeda
Browse files

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: default avatarDavid Gow <davidgow@google.com>
Acked-by: default avatarDanilo Krummrich <dakr@kernel.org>
Link: https://lore.kernel.org/r/20250502215133.1923676-8-ojeda@kernel.org


Signed-off-by: default avatarMiguel Ojeda <ojeda@kernel.org>
parent 0a8d4eab

Documentation/rust/testing.rst

+71 −0
Original line number Diff line number Diff line
@@ -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

---------------------------