<!DOCTYPE html>
<html lang="en" data-content_root="../">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Testing — The Linux Kernel documentation</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=fa44fd50" />
<link rel="stylesheet" type="text/css" href="../_static/alabaster.css?v=3918102e" />
<script src="../_static/documentation_options.js?v=5929fcd5"></script>
<script src="../_static/doctools.js?v=9bcbadda"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="The Linux kernel user’s and administrator’s guide" href="../admin-guide/index.html" />
<link rel="prev" title="Arch Support" href="arch-support.html" />
<link rel="stylesheet" href="../_static/custom.css" type="text/css" />
</head><body>
<div class="document">
<div class="sphinxsidebar" role="navigation" aria-label="Main">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="../index.html">
<img class="logo" src="../_static/logo.svg" alt="Logo of The Linux Kernel"/>
</a></p>
<h1 class="logo"><a href="../index.html">The Linux Kernel</a></h1>
<p class="blurb">6.18.50</p>
<search id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</search>
<script>document.getElementById('searchbox').style.display = "block"</script>
<p>
<h3 class="kernel-toc-contents">Contents</h3>
<input type="checkbox" class="kernel-toc-toggle" id = "kernel-toc-toggle" checked>
<label class="kernel-toc-title" for="kernel-toc-toggle"></label>
<div class="kerneltoc" id="kerneltoc">
<ul>
<li class="toctree-l1"><a class="reference internal" href="../process/development-process.html">Development process</a></li>
<li class="toctree-l1"><a class="reference internal" href="../process/submitting-patches.html">Submitting patches</a></li>
<li class="toctree-l1"><a class="reference internal" href="../process/code-of-conduct.html">Code of conduct</a></li>
<li class="toctree-l1"><a class="reference internal" href="../maintainer/index.html">Maintainer handbook</a></li>
<li class="toctree-l1"><a class="reference internal" href="../process/index.html">All development-process docs</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../core-api/index.html">Core API</a></li>
<li class="toctree-l1"><a class="reference internal" href="../driver-api/index.html">Driver APIs</a></li>
<li class="toctree-l1"><a class="reference internal" href="../subsystem-apis.html">Subsystems</a></li>
<li class="toctree-l1"><a class="reference internal" href="../locking/index.html">Locking</a></li>
</ul>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../process/license-rules.html">Licensing rules</a></li>
<li class="toctree-l1"><a class="reference internal" href="../doc-guide/index.html">Writing documentation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../dev-tools/index.html">Development tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="../dev-tools/testing-overview.html">Testing guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../kernel-hacking/index.html">Hacking guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../trace/index.html">Tracing</a></li>
<li class="toctree-l1"><a class="reference internal" href="../fault-injection/index.html">Fault injection</a></li>
<li class="toctree-l1"><a class="reference internal" href="../livepatch/index.html">Livepatching</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">Rust</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="index.html#the-rust-experiment">The Rust experiment</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="index.html#code-documentation">Code documentation</a><ul class="current">
<li class="toctree-l3"><a class="reference internal" href="quick-start.html">Quick Start</a></li>
<li class="toctree-l3"><a class="reference internal" href="general-information.html">General Information</a></li>
<li class="toctree-l3"><a class="reference internal" href="coding-guidelines.html">Coding Guidelines</a></li>
<li class="toctree-l3"><a class="reference internal" href="arch-support.html">Arch Support</a></li>
<li class="toctree-l3 current"><a class="current reference internal" href="#">Testing</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../admin-guide/index.html">Administration</a></li>
<li class="toctree-l1"><a class="reference internal" href="../kbuild/index.html">Build system</a></li>
<li class="toctree-l1"><a class="reference internal" href="../admin-guide/reporting-issues.html">Reporting issues</a></li>
<li class="toctree-l1"><a class="reference internal" href="../tools/index.html">Userspace tools</a></li>
<li class="toctree-l1"><a class="reference internal" href="../userspace-api/index.html">Userspace API</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../firmware-guide/index.html">Firmware</a></li>
<li class="toctree-l1"><a class="reference internal" href="../devicetree/index.html">Firmware and Devicetree</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../arch/index.html">CPU architectures</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../staging/index.html">Unsorted documentation</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../translations/index.html">Translations</a></li>
</ul>
</div>
<script type="text/javascript"> <!--
var sbar = document.getElementsByClassName("sphinxsidebar")[0];
let currents = document.getElementsByClassName("current")
if (currents.length) {
sbar.scrollTop = currents[currents.length - 1].offsetTop;
}
--> </script>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/rust/testing.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
</div>
</div>
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="testing">
<h1>Testing<a class="headerlink" href="#testing" title="Link to this heading">¶</a></h1>
<p>This document contains useful information how to test the Rust code in the
kernel.</p>
<p>There are three sorts of tests:</p>
<ul class="simple">
<li><p>The KUnit tests.</p></li>
<li><p>The <code class="docutils literal notranslate"><span class="pre">#[test]</span></code> tests.</p></li>
<li><p>The Kselftests.</p></li>
</ul>
<section id="the-kunit-tests">
<h2>The KUnit tests<a class="headerlink" href="#the-kunit-tests" title="Link to this heading">¶</a></h2>
<p>These are the tests that come from the examples in the Rust documentation. They
get transformed into KUnit tests.</p>
<section id="usage">
<h3>Usage<a class="headerlink" href="#usage" title="Link to this heading">¶</a></h3>
<p>These tests can be run via KUnit. For example via <code class="docutils literal notranslate"><span class="pre">kunit_tool</span></code> (<code class="docutils literal notranslate"><span class="pre">kunit.py</span></code>)
on the command line:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>./tools/testing/kunit/kunit.py run --make_options LLVM=1 --arch x86_64 --kconfig_add CONFIG_RUST=y
</pre></div>
</div>
<p>Alternatively, KUnit can run them as kernel built-in at boot. Refer to
<a class="reference internal" href="../dev-tools/kunit/index.html"><span class="doc">KUnit - Linux Kernel Unit Testing</span></a> for the general KUnit documentation
and <a class="reference internal" href="../dev-tools/kunit/architecture.html"><span class="doc">KUnit Architecture</span></a> for the details of kernel
built-in vs. command line testing.</p>
<p>To use these KUnit doctests, the following must be enabled:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>CONFIG_KUNIT
Kernel hacking -> Kernel Testing and Coverage -> KUnit - Enable support for unit tests
CONFIG_RUST_KERNEL_DOCTESTS
Kernel hacking -> Rust hacking -> Doctests for the `kernel` crate
</pre></div>
</div>
<p>in the kernel config system.</p>
</section>
<section id="kunit-tests-are-documentation-tests">
<h3>KUnit tests are documentation tests<a class="headerlink" href="#kunit-tests-are-documentation-tests" title="Link to this heading">¶</a></h3>
<p>These documentation tests are typically examples of usage of any item (e.g.
function, struct, module...).</p>
<p>They are very convenient because they are just written alongside the
documentation. For instance:</p>
<div class="highlight-rust notranslate"><div class="highlight"><pre><span></span><span class="sd">/// Sums two numbers.</span>
<span class="sd">///</span>
<span class="sd">/// ```</span>
<span class="sd">/// assert_eq!(mymod::f(10, 20), 30);</span>
<span class="sd">/// ```</span>
<span class="k">pub</span><span class="w"> </span><span class="k">fn</span><span class="w"> </span><span class="nf">f</span><span class="p">(</span><span class="n">a</span><span class="p">:</span><span class="w"> </span><span class="kt">i32</span><span class="p">,</span><span class="w"> </span><span class="n">b</span><span class="p">:</span><span class="w"> </span><span class="kt">i32</span><span class="p">)</span><span class="w"> </span><span class="p">-></span><span class="w"> </span><span class="kt">i32</span><span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="n">a</span><span class="w"> </span><span class="o">+</span><span class="w"> </span><span class="n">b</span>
<span class="p">}</span>
</pre></div>
</div>
<p>In userspace, the tests are collected and run via <code class="docutils literal notranslate"><span class="pre">rustdoc</span></code>. Using the tool
as-is would be useful already, since it allows verifying that examples compile
(thus enforcing they are kept in sync with the code they document) and as well
as running those that do not depend on in-kernel APIs.</p>
<p>For the kernel, however, these tests get transformed into KUnit test suites.
This means that doctests get compiled as Rust kernel objects, allowing them to
run against a built kernel.</p>
<p>A benefit of this KUnit integration is that Rust doctests get to reuse existing
testing facilities. For instance, the kernel log would look like:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>KTAP version 1
1..1
KTAP version 1
# Subtest: rust_doctests_kernel
1..59
# rust_doctest_kernel_build_assert_rs_0.location: rust/kernel/build_assert.rs:13
ok 1 rust_doctest_kernel_build_assert_rs_0
# rust_doctest_kernel_build_assert_rs_1.location: rust/kernel/build_assert.rs:56
ok 2 rust_doctest_kernel_build_assert_rs_1
# rust_doctest_kernel_init_rs_0.location: rust/kernel/init.rs:122
ok 3 rust_doctest_kernel_init_rs_0
...
# rust_doctest_kernel_types_rs_2.location: rust/kernel/types.rs:150
ok 59 rust_doctest_kernel_types_rs_2
# rust_doctests_kernel: pass:59 fail:0 skip:0 total:59
# Totals: pass:59 fail:0 skip:0 total:59
ok 1 rust_doctests_kernel
</pre></div>
</div>
<p>Tests using the <a class="reference external" href="https://doc.rust-lang.org/reference/expressions/operator-expr.html#the-question-mark-operator">?</a>
operator are also supported as usual, e.g.:</p>
<div class="highlight-rust notranslate"><div class="highlight"><pre><span></span><span class="sd">/// ```</span>
<span class="sd">/// # use kernel::{spawn_work_item, workqueue};</span>
<span class="sd">/// spawn_work_item!(workqueue::system(), || pr_info!("x\n"))?;</span>
<span class="sd">/// # Ok::<(), Error>(())</span>
<span class="sd">/// ```</span>
</pre></div>
</div>
<p>The tests are also compiled with Clippy under <code class="docutils literal notranslate"><span class="pre">CLIPPY=1</span></code>, just like normal
code, thus also benefitting from extra linting.</p>
<p>In order for developers to easily see which line of doctest code caused a
failure, a KTAP diagnostic line is printed to the log. This contains the
location (file and line) of the original test (i.e. instead of the location in
the generated Rust file):</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span># rust_doctest_kernel_types_rs_2.location: rust/kernel/types.rs:150
</pre></div>
</div>
<p>Rust tests appear to assert using the usual <code class="docutils literal notranslate"><span class="pre">assert!</span></code> and <code class="docutils literal notranslate"><span class="pre">assert_eq!</span></code>
macros from the Rust standard library (<code class="docutils literal notranslate"><span class="pre">core</span></code>). We provide a custom version
that forwards the call to KUnit instead. Importantly, these macros do not
require passing context, unlike those for KUnit testing (i.e.
<code class="docutils literal notranslate"><span class="pre">struct</span> <span class="pre">kunit</span> <span class="pre">*</span></code>). This makes them easier to use, and readers of the
documentation do not need to care about which testing framework is used. In
addition, it may allow us to test third-party code more easily in the future.</p>
<p>A current limitation is that KUnit does not support assertions in other tasks.
Thus, we presently simply print an error to the kernel log if an assertion
actually failed. Additionally, doctests are not run for nonpublic functions.</p>
<p>Since these tests are examples, i.e. they are part of the documentation, they
should generally be written like “real code”. Thus, for example, instead of
using <code class="docutils literal notranslate"><span class="pre">unwrap()</span></code> or <code class="docutils literal notranslate"><span class="pre">expect()</span></code>, use the <code class="docutils literal notranslate"><span class="pre">?</span></code> operator. For more background,
please see:</p>
<blockquote>
<div><p><a class="reference external" href="https://rust.docs.kernel.org/kernel/error/type.Result.html#error-codes-in-c-and-rust">https://rust.docs.kernel.org/kernel/error/type.Result.html#error-codes-in-c-and-rust</a></p>
</div></blockquote>
</section>
</section>
<section id="the-test-tests">
<h2>The <code class="docutils literal notranslate"><span class="pre">#[test]</span></code> tests<a class="headerlink" href="#the-test-tests" title="Link to this heading">¶</a></h2>
<p>Additionally, there are the <code class="docutils literal notranslate"><span class="pre">#[test]</span></code> tests. Like for documentation tests,
these are also fairly similar to what you would expect from userspace, and they
are also mapped to KUnit.</p>
<p>These tests are introduced by the <code class="docutils literal notranslate"><span class="pre">kunit_tests</span></code> procedural macro, which takes
the name of the test suite as an argument.</p>
<p>For instance, assume we want to test the function <code class="docutils literal notranslate"><span class="pre">f</span></code> from the documentation
tests section. We could write, in the same file where we have our function:</p>
<div class="highlight-rust notranslate"><div class="highlight"><pre><span></span><span class="cp">#[kunit_tests(rust_kernel_mymod)]</span>
<span class="k">mod</span><span class="w"> </span><span class="nn">tests</span><span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="k">use</span><span class="w"> </span><span class="k">super</span><span class="p">::</span><span class="o">*</span><span class="p">;</span>
<span class="w"> </span><span class="cp">#[test]</span>
<span class="w"> </span><span class="k">fn</span><span class="w"> </span><span class="nf">test_f</span><span class="p">()</span><span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="fm">assert_eq!</span><span class="p">(</span><span class="n">f</span><span class="p">(</span><span class="mi">10</span><span class="p">,</span><span class="w"> </span><span class="mi">20</span><span class="p">),</span><span class="w"> </span><span class="mi">30</span><span class="p">);</span>
<span class="w"> </span><span class="p">}</span>
<span class="p">}</span>
</pre></div>
</div>
<p>And if we run it, the kernel log would look like:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span> KTAP version 1
# Subtest: rust_kernel_mymod
# speed: normal
1..1
# test_f.speed: normal
ok 1 test_f
ok 1 rust_kernel_mymod
</pre></div>
</div>
<p>Like documentation tests, the <code class="docutils literal notranslate"><span class="pre">assert!</span></code> and <code class="docutils literal notranslate"><span class="pre">assert_eq!</span></code> macros are mapped
back to KUnit and do not panic. Similarly, the
<a class="reference external" href="https://doc.rust-lang.org/reference/expressions/operator-expr.html#the-question-mark-operator">?</a>
operator is supported, i.e. the test functions may return either nothing (i.e.
the unit type <code class="docutils literal notranslate"><span class="pre">()</span></code>) or <code class="docutils literal notranslate"><span class="pre">Result</span></code> (i.e. any <code class="docutils literal notranslate"><span class="pre">Result<T,</span> <span class="pre">E></span></code>). For instance:</p>
<div class="highlight-rust notranslate"><div class="highlight"><pre><span></span><span class="cp">#[kunit_tests(rust_kernel_mymod)]</span>
<span class="k">mod</span><span class="w"> </span><span class="nn">tests</span><span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="k">use</span><span class="w"> </span><span class="k">super</span><span class="p">::</span><span class="o">*</span><span class="p">;</span>
<span class="w"> </span><span class="cp">#[test]</span>
<span class="w"> </span><span class="k">fn</span><span class="w"> </span><span class="nf">test_g</span><span class="p">()</span><span class="w"> </span><span class="p">-></span><span class="w"> </span><span class="nb">Result</span><span class="w"> </span><span class="p">{</span>
<span class="w"> </span><span class="kd">let</span><span class="w"> </span><span class="n">x</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">g</span><span class="p">()</span><span class="o">?</span><span class="p">;</span>
<span class="w"> </span><span class="fm">assert_eq!</span><span class="p">(</span><span class="n">x</span><span class="p">,</span><span class="w"> </span><span class="mi">30</span><span class="p">);</span>
<span class="w"> </span><span class="nb">Ok</span><span class="p">(())</span>
<span class="w"> </span><span class="p">}</span>
<span class="p">}</span>
</pre></div>
</div>
<p>If we run the test and the call to <code class="docutils literal notranslate"><span class="pre">g</span></code> fails, then the kernel log would show:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span> 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
</pre></div>
</div>
<p>If a <code class="docutils literal notranslate"><span class="pre">#[test]</span></code> 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.</p>
</section>
<section id="the-rusttest-host-tests">
<h2>The <code class="docutils literal notranslate"><span class="pre">rusttest</span></code> host tests<a class="headerlink" href="#the-rusttest-host-tests" title="Link to this heading">¶</a></h2>
<p>These are userspace tests that can be built and run in the host (i.e. the one
that performs the kernel build) using the <code class="docutils literal notranslate"><span class="pre">rusttest</span></code> Make target:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>make LLVM=1 rusttest
</pre></div>
</div>
<p>This requires the kernel <code class="docutils literal notranslate"><span class="pre">.config</span></code>.</p>
<p>Currently, they are mostly used for testing the <code class="docutils literal notranslate"><span class="pre">macros</span></code> crate’s examples.</p>
</section>
<section id="the-kselftests">
<h2>The Kselftests<a class="headerlink" href="#the-kselftests" title="Link to this heading">¶</a></h2>
<p>Kselftests are also available in the <code class="docutils literal notranslate"><span class="pre">tools/testing/selftests/rust</span></code> folder.</p>
<p>The kernel config options required for the tests are listed in the
<code class="docutils literal notranslate"><span class="pre">tools/testing/selftests/rust/config</span></code> file and can be included with the aid
of the <code class="docutils literal notranslate"><span class="pre">merge_config.sh</span></code> script:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>./scripts/kconfig/merge_config.sh .config tools/testing/selftests/rust/config
</pre></div>
</div>
<p>The kselftests are built within the kernel source tree and are intended to
be executed on a system that is running the same kernel.</p>
<p>Once a kernel matching the source tree has been installed and booted, the
tests can be compiled and executed using the following command:</p>
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>make TARGETS="rust" kselftest
</pre></div>
</div>
<p>Refer to <a class="reference internal" href="../dev-tools/kselftest.html"><span class="doc">Linux Kernel Selftests</span></a> for the general Kselftest
documentation.</p>
</section>
</section>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
©The kernel development community.
|
Powered by <a href="https://www.sphinx-doc.org/">Sphinx 8.1.3</a>
& <a href="https://alabaster.readthedocs.io">Alabaster 0.7.16</a>
|
<a href="../_sources/rust/testing.rst.txt"
rel="nofollow">Page source</a>
</div>
</body>
</html>