Crate ktest

source ·
Expand description

The kernel mode testing framework of Asterinas.

ktest stands for kernel-mode testing framework. Its goal is to provide a cargo test-like experience for any #![no_std] bare metal crates.

In Asterinas, all the tests written in the source tree of the crates will be run immediately after the initialization of aster-frame. Thus you can use any feature provided by the frame including the heap allocator, etc.

By all means, ktest is an individule crate that only requires:

  • a custom linker script section .ktest_array,
  • and an alloc implementation. to work. And the frame happens to provide both of them. Thus, any crates depending on the frame can use ktest without any extra dependency.

Usage

To write a unit test for any crates, it is recommended to create a new test module, e.g.:

use ktest::ktest;
#[cfg(ktest)]
mod test {
    #[ktest]
    fn trivial_assertion() {
        assert_eq!(0, 0);
    }
    #[ktest]
    #[should_panic]
    fn failing_assertion() {
        assert_eq!(0, 1);
    }
    #[ktest]
    #[should_panic(expected = "expected panic message")]
    fn expect_panic() {
        panic!("expected panic message");
    }
}

And also, any crates using the ktest framework should be linked with aster-frame and import the ktest crate:

# Cargo.toml
[dependencies]
ktest = { path = "relative/path/to/ktest" }

By the way, #[ktest] attribute along also works, but it hinders test control using cfgs since plain attribute marked test will be executed in all test runs no matter what cfgs are passed to the compiler. More importantly, using #[ktest] without cfgs occupies binary real estate since the .ktest_array section is not explicitly stripped in normal builds.

Rust cfg is used to control the compilation of the test module. In cooperation with the ktest framework, the Makefile will set the RUSTFLAGS environment variable to pass the cfgs to all rustc invocations. To run the tests, you simply need to set a list of cfgs by specifying KTEST=1 to the Makefile, e.g.:

make run KTEST=1

Also, you can run a subset of tests by specifying the KTEST_WHITELIST variable. This is achieved by a whitelist filter on the test name.

make run KTEST=1 KTEST_WHITELIST=failing_assertion,aster_frame::test::expect_panic

KTEST_CRATES variable is used to specify in which crates the tests to be run. This is achieved by conditionally compiling the test module using the #[cfg].

make run KTEST=1 KTEST_CRATES=aster-frame
``

We support the `#[should_panic]` attribute just in the same way as the standard
library do, but the implementation is quite slow currently. Use it with cautious.

Doctest is not taken into consideration yet, and the interface is subject to
change.

Modules

  • path
  • runner
    Test runner enabling control over the tests.
  • tree
    The source module tree of ktests.

Structs

Enums

Attribute Macros

  • ktest
    The test attribute macro to mark a test function.