1.. SPDX-License-Identifier: GPL-2.0
  2
  3Testing
  4=======
  5
  6This document contains useful information how to test the Rust code in the
  7kernel.
  8
  9There are two sorts of tests:
 10
 11- The KUnit tests.
 12- The ``#[test]`` tests.
 13
 14The KUnit tests
 15---------------
 16
 17These are the tests that come from the examples in the Rust documentation. They
 18get transformed into KUnit tests.
 19
 20Usage
 21*****
 22
 23These tests can be run via KUnit. For example via ``kunit_tool`` (``kunit.py``)
 24on the command line::
 25
 26	./tools/testing/kunit/kunit.py run --make_options LLVM=1 --arch x86_64 --kconfig_add CONFIG_RUST=y
 27
 28Alternatively, KUnit can run them as kernel built-in at boot. Refer to
 29Documentation/dev-tools/kunit/index.rst for the general KUnit documentation
 30and Documentation/dev-tools/kunit/architecture.rst for the details of kernel
 31built-in vs. command line testing.
 32
 33To use these KUnit doctests, the following must be enabled::
 34
 35	CONFIG_KUNIT
 36	   Kernel hacking -> Kernel Testing and Coverage -> KUnit - Enable support for unit tests
 37	CONFIG_RUST_KERNEL_DOCTESTS
 38	   Kernel hacking -> Rust hacking -> Doctests for the `kernel` crate
 39
 40in the kernel config system.
 41
 42KUnit tests are documentation tests
 43***********************************
 44
 45These documentation tests are typically examples of usage of any item (e.g.
 46function, struct, module...).
 47
 48They are very convenient because they are just written alongside the
 49documentation. For instance:
 50
 51.. code-block:: rust
 52
 53	/// Sums two numbers.
 54	///
 55	/// ```
 56	/// assert_eq!(mymod::f(10, 20), 30);
 57	/// ```
 58	pub fn f(a: i32, b: i32) -> i32 {
 59	    a + b
 60	}
 61
 62In userspace, the tests are collected and run via ``rustdoc``. Using the tool
 63as-is would be useful already, since it allows verifying that examples compile
 64(thus enforcing they are kept in sync with the code they document) and as well
 65as running those that do not depend on in-kernel APIs.
 66
 67For the kernel, however, these tests get transformed into KUnit test suites.
 68This means that doctests get compiled as Rust kernel objects, allowing them to
 69run against a built kernel.
 70
 71A benefit of this KUnit integration is that Rust doctests get to reuse existing
 72testing facilities. For instance, the kernel log would look like::
 73
 74	KTAP version 1
 75	1..1
 76	    KTAP version 1
 77	    # Subtest: rust_doctests_kernel
 78	    1..59
 79	    # rust_doctest_kernel_build_assert_rs_0.location: rust/kernel/build_assert.rs:13
 80	    ok 1 rust_doctest_kernel_build_assert_rs_0
 81	    # rust_doctest_kernel_build_assert_rs_1.location: rust/kernel/build_assert.rs:56
 82	    ok 2 rust_doctest_kernel_build_assert_rs_1
 83	    # rust_doctest_kernel_init_rs_0.location: rust/kernel/init.rs:122
 84	    ok 3 rust_doctest_kernel_init_rs_0
 85	    ...
 86	    # rust_doctest_kernel_types_rs_2.location: rust/kernel/types.rs:150
 87	    ok 59 rust_doctest_kernel_types_rs_2
 88	# rust_doctests_kernel: pass:59 fail:0 skip:0 total:59
 89	# Totals: pass:59 fail:0 skip:0 total:59
 90	ok 1 rust_doctests_kernel
 91
 92Tests using the `? <https://doc.rust-lang.org/reference/expressions/operator-expr.html#the-question-mark-operator>`_
 93operator are also supported as usual, e.g.:
 94
 95.. code-block:: rust
 96
 97	/// ```
 98	/// # use kernel::{spawn_work_item, workqueue};
 99	/// spawn_work_item!(workqueue::system(), || pr_info!("x"))?;
100	/// # Ok::<(), Error>(())
101	/// ```
102
103The tests are also compiled with Clippy under ``CLIPPY=1``, just like normal
104code, thus also benefitting from extra linting.
105
106In order for developers to easily see which line of doctest code caused a
107failure, a KTAP diagnostic line is printed to the log. This contains the
108location (file and line) of the original test (i.e. instead of the location in
109the generated Rust file)::
110
111	# rust_doctest_kernel_types_rs_2.location: rust/kernel/types.rs:150
112
113Rust tests appear to assert using the usual ``assert!`` and ``assert_eq!``
114macros from the Rust standard library (``core``). We provide a custom version
115that forwards the call to KUnit instead. Importantly, these macros do not
116require passing context, unlike those for KUnit testing (i.e.
117``struct kunit *``). This makes them easier to use, and readers of the
118documentation do not need to care about which testing framework is used. In
119addition, it may allow us to test third-party code more easily in the future.
120
121A current limitation is that KUnit does not support assertions in other tasks.
122Thus, we presently simply print an error to the kernel log if an assertion
123actually failed. Additionally, doctests are not run for nonpublic functions.
124
125The ``#[test]`` tests
126---------------------
127
128Additionally, there are the ``#[test]`` tests. These can be run using the
129``rusttest`` Make target::
130
131	make LLVM=1 rusttest
132
133This requires the kernel ``.config`` and downloads external repositories. It
134runs the ``#[test]`` tests on the host (currently) and thus is fairly limited in
135what these tests can test.