158 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3Testing4=======5 6This document contains useful information how to test the Rust code in the7kernel.8 9There are three sorts of tests:10 11- The KUnit tests.12- The ``#[test]`` tests.13- The Kselftests.14 15The KUnit tests16---------------17 18These are the tests that come from the examples in the Rust documentation. They19get transformed into KUnit tests.20 21Usage22*****23 24These tests can be run via KUnit. For example via ``kunit_tool`` (``kunit.py``)25on the command line::26 27 ./tools/testing/kunit/kunit.py run --make_options LLVM=1 --arch x86_64 --kconfig_add CONFIG_RUST=y28 29Alternatively, KUnit can run them as kernel built-in at boot. Refer to30Documentation/dev-tools/kunit/index.rst for the general KUnit documentation31and Documentation/dev-tools/kunit/architecture.rst for the details of kernel32built-in vs. command line testing.33 34To use these KUnit doctests, the following must be enabled::35 36 CONFIG_KUNIT37 Kernel hacking -> Kernel Testing and Coverage -> KUnit - Enable support for unit tests38 CONFIG_RUST_KERNEL_DOCTESTS39 Kernel hacking -> Rust hacking -> Doctests for the `kernel` crate40 41in the kernel config system.42 43KUnit tests are documentation tests44***********************************45 46These documentation tests are typically examples of usage of any item (e.g.47function, struct, module...).48 49They are very convenient because they are just written alongside the50documentation. For instance:51 52.. code-block:: rust53 54 /// Sums two numbers.55 ///56 /// ```57 /// assert_eq!(mymod::f(10, 20), 30);58 /// ```59 pub fn f(a: i32, b: i32) -> i32 {60 a + b61 }62 63In userspace, the tests are collected and run via ``rustdoc``. Using the tool64as-is would be useful already, since it allows verifying that examples compile65(thus enforcing they are kept in sync with the code they document) and as well66as running those that do not depend on in-kernel APIs.67 68For the kernel, however, these tests get transformed into KUnit test suites.69This means that doctests get compiled as Rust kernel objects, allowing them to70run against a built kernel.71 72A benefit of this KUnit integration is that Rust doctests get to reuse existing73testing facilities. For instance, the kernel log would look like::74 75 KTAP version 176 1..177 KTAP version 178 # Subtest: rust_doctests_kernel79 1..5980 # rust_doctest_kernel_build_assert_rs_0.location: rust/kernel/build_assert.rs:1381 ok 1 rust_doctest_kernel_build_assert_rs_082 # rust_doctest_kernel_build_assert_rs_1.location: rust/kernel/build_assert.rs:5683 ok 2 rust_doctest_kernel_build_assert_rs_184 # rust_doctest_kernel_init_rs_0.location: rust/kernel/init.rs:12285 ok 3 rust_doctest_kernel_init_rs_086 ...87 # rust_doctest_kernel_types_rs_2.location: rust/kernel/types.rs:15088 ok 59 rust_doctest_kernel_types_rs_289 # rust_doctests_kernel: pass:59 fail:0 skip:0 total:5990 # Totals: pass:59 fail:0 skip:0 total:5991 ok 1 rust_doctests_kernel92 93Tests using the `? <https://doc.rust-lang.org/reference/expressions/operator-expr.html#the-question-mark-operator>`_94operator are also supported as usual, e.g.:95 96.. code-block:: rust97 98 /// ```99 /// # use kernel::{spawn_work_item, workqueue};100 /// spawn_work_item!(workqueue::system(), || pr_info!("x"))?;101 /// # Ok::<(), Error>(())102 /// ```103 104The tests are also compiled with Clippy under ``CLIPPY=1``, just like normal105code, thus also benefitting from extra linting.106 107In order for developers to easily see which line of doctest code caused a108failure, a KTAP diagnostic line is printed to the log. This contains the109location (file and line) of the original test (i.e. instead of the location in110the generated Rust file)::111 112 # rust_doctest_kernel_types_rs_2.location: rust/kernel/types.rs:150113 114Rust tests appear to assert using the usual ``assert!`` and ``assert_eq!``115macros from the Rust standard library (``core``). We provide a custom version116that forwards the call to KUnit instead. Importantly, these macros do not117require passing context, unlike those for KUnit testing (i.e.118``struct kunit *``). This makes them easier to use, and readers of the119documentation do not need to care about which testing framework is used. In120addition, it may allow us to test third-party code more easily in the future.121 122A current limitation is that KUnit does not support assertions in other tasks.123Thus, we presently simply print an error to the kernel log if an assertion124actually failed. Additionally, doctests are not run for nonpublic functions.125 126The ``#[test]`` tests127---------------------128 129Additionally, there are the ``#[test]`` tests. These can be run using the130``rusttest`` Make target::131 132 make LLVM=1 rusttest133 134This requires the kernel ``.config``. It runs the ``#[test]`` tests on the host135(currently) and thus is fairly limited in what these tests can test.136 137The Kselftests138--------------139 140Kselftests are also available in the ``tools/testing/selftests/rust`` folder.141 142The kernel config options required for the tests are listed in the143``tools/testing/selftests/rust/config`` file and can be included with the aid144of the ``merge_config.sh`` script::145 146 ./scripts/kconfig/merge_config.sh .config tools/testing/selftests/rust/config147 148The kselftests are built within the kernel source tree and are intended to149be executed on a system that is running the same kernel.150 151Once a kernel matching the source tree has been installed and booted, the152tests can be compiled and executed using the following command::153 154 make TARGETS="rust" kselftest155 156Refer to Documentation/dev-tools/kselftest.rst for the general Kselftest157documentation.158