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 three sorts of tests: 10 11- The KUnit tests. 12- The ``#[test]`` tests. 13- The Kselftests. 14 15The KUnit tests 16--------------- 17 18These are the tests that come from the examples in the Rust documentation. They 19get transformed into KUnit tests. 20 21Usage 22***** 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=y 28 29Alternatively, KUnit can run them as kernel built-in at boot. Refer to 30Documentation/dev-tools/kunit/index.rst for the general KUnit documentation 31and Documentation/dev-tools/kunit/architecture.rst for the details of kernel 32built-in vs. command line testing. 33 34To use these KUnit doctests, the following must be enabled:: 35 36 CONFIG_KUNIT 37 Kernel hacking -> Kernel Testing and Coverage -> KUnit - Enable support for unit tests 38 CONFIG_RUST_KERNEL_DOCTESTS 39 Kernel hacking -> Rust hacking -> Doctests for the `kernel` crate 40 41in the kernel config system. 42 43KUnit tests are documentation tests 44*********************************** 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 the 50documentation. For instance: 51 52.. code-block:: rust 53 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 + b 61 } 62 63In userspace, the tests are collected and run via ``rustdoc``. Using the tool 64as-is would be useful already, since it allows verifying that examples compile 65(thus enforcing they are kept in sync with the code they document) and as well 66as 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 to 70run against a built kernel. 71 72A benefit of this KUnit integration is that Rust doctests get to reuse existing 73testing facilities. For instance, the kernel log would look like:: 74 75 KTAP version 1 76 1..1 77 KTAP version 1 78 # Subtest: rust_doctests_kernel 79 1..59 80 # rust_doctest_kernel_build_assert_rs_0.location: rust/kernel/build_assert.rs:13 81 ok 1 rust_doctest_kernel_build_assert_rs_0 82 # rust_doctest_kernel_build_assert_rs_1.location: rust/kernel/build_assert.rs:56 83 ok 2 rust_doctest_kernel_build_assert_rs_1 84 # rust_doctest_kernel_init_rs_0.location: rust/kernel/init.rs:122 85 ok 3 rust_doctest_kernel_init_rs_0 86 ... 87 # rust_doctest_kernel_types_rs_2.location: rust/kernel/types.rs:150 88 ok 59 rust_doctest_kernel_types_rs_2 89 # rust_doctests_kernel: pass:59 fail:0 skip:0 total:59 90 # Totals: pass:59 fail:0 skip:0 total:59 91 ok 1 rust_doctests_kernel 92 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:: rust 97 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 normal 105code, thus also benefitting from extra linting. 106 107In order for developers to easily see which line of doctest code caused a 108failure, a KTAP diagnostic line is printed to the log. This contains the 109location (file and line) of the original test (i.e. instead of the location in 110the generated Rust file):: 111 112 # rust_doctest_kernel_types_rs_2.location: rust/kernel/types.rs:150 113 114Rust tests appear to assert using the usual ``assert!`` and ``assert_eq!`` 115macros from the Rust standard library (``core``). We provide a custom version 116that forwards the call to KUnit instead. Importantly, these macros do not 117require passing context, unlike those for KUnit testing (i.e. 118``struct kunit *``). This makes them easier to use, and readers of the 119documentation do not need to care about which testing framework is used. In 120addition, 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 assertion 124actually failed. Additionally, doctests are not run for nonpublic functions. 125 126The ``#[test]`` tests 127--------------------- 128 129Additionally, there are the ``#[test]`` tests. These can be run using the 130``rusttest`` Make target:: 131 132 make LLVM=1 rusttest 133 134This requires the kernel ``.config``. It runs the ``#[test]`` tests on the host 135(currently) and thus is fairly limited in what these tests can test. 136 137The Kselftests 138-------------- 139 140Kselftests are also available in the ``tools/testing/selftests/rust`` folder. 141 142The kernel config options required for the tests are listed in the 143``tools/testing/selftests/rust/config`` file and can be included with the aid 144of the ``merge_config.sh`` script:: 145 146 ./scripts/kconfig/merge_config.sh .config tools/testing/selftests/rust/config 147 148The kselftests are built within the kernel source tree and are intended to 149be executed on a system that is running the same kernel. 150 151Once a kernel matching the source tree has been installed and booted, the 152tests can be compiled and executed using the following command:: 153 154 make TARGETS="rust" kselftest 155 156Refer to Documentation/dev-tools/kselftest.rst for the general Kselftest 157documentation. 158