The kernel mode testing framework of OSTD.

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

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

By all means, ostd-test is an individule crate that only requires:

• a custom linker script section .ktest_array,
• and an alloc implementation.

And the OSTD happens to provide both of them. Thus, any crates depending on the OSTD can use ostd-test without any extra dependency.

Usage

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

#[cfg(ktest)]
mod test {
use ostd::prelude::*;

#[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");
}
}

Any crates using the ostd-test framework should be linked with ostd.

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

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,ostd::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=ostd
``

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.