Documentation/rust/testing.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 Testing
   4 =======
   5
   6 This document contains useful information how to test the Rust code in the
   7 kernel.
   8
   9 There are two sorts of tests:
  10
  11 - The KUnit tests.
  12 - The ``#[test]`` tests.
  13
  14 The KUnit tests
  15 ---------------
  16
  17 These are the tests that come from the examples in the Rust documentation. They
  18 get transformed into KUnit tests.
  19
  20 Usage
  21 *****
  22
  23 These tests can be run via KUnit. For example via ``kunit_tool`` (``kunit.py``)
  24 on the command line::
  25
  26         ./tools/testing/kunit/kunit.py run --make_options LLVM=1 --arch x86_64 --kconfig_add CONFIG_RUST=y
  27
  28 Alternatively, KUnit can run them as kernel built-in at boot. Refer to
  29 Documentation/dev-tools/kunit/index.rst for the general KUnit documentation
  30 and Documentation/dev-tools/kunit/architecture.rst for the details of kernel
  31 built-in vs. command line testing.
  32
  33 To 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
  40 in the kernel config system.
  41
  42 KUnit tests are documentation tests
  43 ***********************************
  44
  45 These documentation tests are typically examples of usage of any item (e.g.
  46 function, struct, module...).
  47
  48 They are very convenient because they are just written alongside the
  49 documentation. 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
  62 In userspace, the tests are collected and run via ``rustdoc``. Using the tool
  63 as-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
  65 as running those that do not depend on in-kernel APIs.
  66
  67 For the kernel, however, these tests get transformed into KUnit test suites.
  68 This means that doctests get compiled as Rust kernel objects, allowing them to
  69 run against a built kernel.
  70
  71 A benefit of this KUnit integration is that Rust doctests get to reuse existing
  72 testing 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
  92 Tests using the `? <https://doc.rust-lang.org/reference/expressions/operator-expr.html#the-question-mark-operator>`_
  93 operator 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
 103 The tests are also compiled with Clippy under ``CLIPPY=1``, just like normal
 104 code, thus also benefitting from extra linting.
 105
 106 In order for developers to easily see which line of doctest code caused a
 107 failure, a KTAP diagnostic line is printed to the log. This contains the
 108 location (file and line) of the original test (i.e. instead of the location in
 109 the generated Rust file)::
 110
 111         # rust_doctest_kernel_types_rs_2.location: rust/kernel/types.rs:150
 112
 113 Rust tests appear to assert using the usual ``assert!`` and ``assert_eq!``
 114 macros from the Rust standard library (``core``). We provide a custom version
 115 that forwards the call to KUnit instead. Importantly, these macros do not
 116 require passing context, unlike those for KUnit testing (i.e.
 117 ``struct kunit *``). This makes them easier to use, and readers of the
 118 documentation do not need to care about which testing framework is used. In
 119 addition, it may allow us to test third-party code more easily in the future.
 120
 121 A current limitation is that KUnit does not support assertions in other tasks.
 122 Thus, we presently simply print an error to the kernel log if an assertion
 123 actually failed. Additionally, doctests are not run for nonpublic functions.
 124
 125 The ``#[test]`` tests
 126 ---------------------
 127
 128 Additionally, there are the ``#[test]`` tests. These can be run using the
 129 ``rusttest`` Make target::
 130
 131         make LLVM=1 rusttest
 132
 133 This requires the kernel ``.config`` and downloads external repositories. It
 134 runs the ``#[test]`` tests on the host (currently) and thus is fairly limited in
 135 what these tests can test.