编写内核，测试必不可少；本篇文章中，我们将了解在no_std环境下进行单元测试和集成测试的方法。使用Rust的自定义测试框架，我们的内核能够执行一些测试函数，如为VGA缓冲区模块添加并执行单元测试。为了将结果反馈到QEMU上，我们需要使用QEMU的一些其它的功能以及bootimage工具。
原文： https:// os.phil-opp.com/testing / 原作者：@phil-opp 翻译：readlnh 审校：洛佳 华中科技大学 译文链接：洛佳：使用Rust编写操作系统（四）：内核测试 本翻译已被许可。转载请注明出处，商业转载请联系原作者
Rust中的测试
Rust有一个内置的测试框架[1]，无需任何额外设置就可以进行单元测试：只需创建一个通过断言（assert）来检查结果的函数，并在该函数的头部加上#[test]属性即可；在这之后，cargo test将会自动寻找crate中所有的测试函数，并依次执行测试。
不幸的是，对于一个no_std的应用——比如我们的内核——这将会有点点复杂。现在的问题是，Rust的测试框架会隐式调用内置的test库[2]，而且这个库依赖于标准库；这也就是说，我们的 #[no_std]内核将无法使用默认的测试框架。
为了验证这一点，我们试图在项目中执行cargo xtest。可以看到如下的错误：
> cargo xtest
Compiling blog_os v0.1.0 (/…/blog_os)
error[E0463]: can't find crate for `test`由于testcrate依赖于标准库，所以它在我们的裸机目标上并不可用。虽然将testcrate移植到一个 #[no_std] 上下文环境中是可能的[3]；但是这样做将高度不稳定，且可能需要一些特殊的手段，例如重定义 panic 宏。
自定义测试框架
幸运的是，Rust支持通过使用不稳定的自定义测试框架（custom_test_frameworks） 功能来替换默认的测试框架。该功能不需要额外的库，因此在 #[no_std]环境中它也可以工作。它的工作原理是收集所有标注了#[test_case]属性的函数，然后将这个测试函数的列表作为参数传递给用户指定的runner函数。因此，它实现了对测试过程的最大控制。
与默认的测试框架相比，它的缺点是有一些高级功能都不可使用，诸如should_panic测试[4]；相对的，如果要求使用这些功能，我们需要自己提供实现。当然，这点对我们来说是好事，因为我们的环境非常特殊——在这个环境里，这些高级功能的默认实现是无论如何都无法工作的：举个例子，#[should_panic]属性依赖于栈展开来捕获内核panic，而我们的内核早已将其禁用了。
要为我们的内核实现自定义测试框架，我们需要将如下代码添加到我们的main.rs中去:
// in src/main.rs
#![feature(custom_test_frameworks)]
#![test_runner(crate::test_runner)]
#[cfg(test)]
fn test_runner(tests: &[&dyn Fn()]) {
println!("Running {} tests", tests.len());
for test in tests {
test();
}
}
我们的runner会打印一个简短的debug信息，然后将调用列表中的每个测试函数。这里，参数tests拥有类型&[&dyn Fn()]，它是Fn() trait的Trait对象（trait object）引用的一个切片（slice）；它的元素基本上可以被看做可像函数一样被调用的类型。由于这个函数在不进行测试的时候不会派上用场，这里我们使用#[cfg(test)]属性，保证它只在测试中生成。
现在当我们执行cargo xtest ，可以发现运行成功。然而，我们看到的仍然是字符串"Hello World"，而不是test_runner传递来的信息；这是由于我们的入口点仍然是 _start 函数——自定义测试框架确实会生成一个main函数来调用test_runner，但由于我们使用#[no_main]并提供自己的入口点，这个main函数将被编译器忽略。
为了修复这个问题，我们需要通过reexport_test_harness_main属性，将生成的函数的名称更改为与main不同。使用下面的代码，我们可在_start函数里调用已经重命名的函数：
// in src/main.rs
#![reexport_test_harness_main = "test_main"]
#[no_mangle]
pub extern "C" fn _start() -> ! {
println!("Hello World{}", "!");
#[cfg(test)]
test_main();
loop {}
}
我们将测试框架入口函数的名字定为test_main，并在我们的 _start入口点里调用它。通过使用条件编译（conditional compilation），我们能够只在上下文环境为测试（test）时调用test_main；此时该函数将不在非测试上下文中生成。
现在，执行 cargo xtest之后，可以看到我们的test_runner将"Running 0 tests"信息显示在屏幕上。这意味着，我们可以创建第一个测试函数了，像这样:
// in src/main.rs
#[test_case]
fn trivial_assertion() {
print!("trivial assertion... ");
assert_eq!(1, 1);
println!("[ok]");
}
我们再次运行 cargo xtest。可以看到如下输出：
传递给 test_runner函数的tests切片里包含了一个 trivial_assertion 函数的引用（还记得tests的变量类型和定义吗？）。这里，从屏幕上输出的 trivial assertion... [ok]信息可见，我们的测试已被调用并且顺利通过。
在执行完tests后， test_runner会将结果返回给 test_main函数，而这个函数又返回到 _start入口点函数——这样我们就进入了一个死循环，因为入口点函数是不允许返回的。这将导致一个问题：我们希望cargo xtest在所有的测试运行完毕后，才返回并退出。
退出QEMU
现在我们在_start函数结束后进入了一个死循环，所以每次执行完cargo xtest后我们都需要手动去关闭QEMU；但是我们还想在没有用户交互的脚本环境下执行 cargo xtest。解决这个问题的最佳方式，是实现一个合适的方法，来关闭我们的操作系统——不幸的是，这个方式实现起来相对有些复杂，因为这要求我们实现对APM或ACPI电源管理标准的支持。
幸运的是，还有一个绕开这些问题的办法：QEMU支持一种名为 isa-debug-exit的特殊设备，它提供了一种从客户系统（guest system）里退出QEMU的简单方式。为了使用这个设备，我们需要向QEMU传递一个-device参数。当然，我们也可以通过将配置关键字package.metadata.bootimage.test-args添加到我们的Cargo.toml中来达到目的：
# in Cargo.toml
[package.metadata.bootimage]
test-args = ["-device", "isa-debug-exit,iobase=0xf4,iosize=0x04"]bootimage runner 会在QEMU的默认测试命令后添加test-args 参数。（对于cargo xrun命令，这个参数将被忽略。）
在传递设备名 (isa-debug-exit）的同时，我们还传递了两个参数：iobase和iosize。这两个参数指定了一个I/O端口，我们的内核将通过它来访问设备。
I/O 端口
在x86平台上，CPU和外围硬件通信通常有两种方式，内存映射I/O和端口映射I/O。之前，我们已经使用内存映射的方式，通过内存地址0xb8000访问了VGA文本缓冲区[5]。该地址并没有映射到RAM，而是映射到VGA设备的一部分内存上。
与内存映射不同，端口映射I/O使用独立的I/O总线来进行通信。每个外围设备都有一个或数个端口号。x86 CPU使用特殊的in和out指令来和端口通信，这些指令要求一个端口号和一个字节的数据作为参数（有些这种指令的变体也允许发送u16或是u32等长度的数据）。
isa-debug-exit设备使用的就是端口映射I/O。其中，iobase 参数指定了设备对应的端口地址（在x86中，0xf4通常是一个未被使用的端口[6]），而iosize则指定了端口的大小（0x04代表4字节）。
使用退出(Exit)设备
isa-debug-exit设备的功能非常简单。当一个 value被写入iobase指定的端口时，它将导致QEMU以退出状态（exit status）(value << 1) | 1退出。也就是说，当我们向端口写入0时，QEMU将以退出状态(0 << 1) | 1 = 1退出；而当我们向端口写入1时，它将以退出状态(1 << 1) | 1 = 3退出。
这里我们使用x86_64 crate[7]提供的抽象，而不是手动调用in或out指令。为了添加对该crate的依赖，我们可以将其添加到项目配置Cargo.toml的dependencies小节中去：
# in Cargo.toml
[dependencies]
x86_64 = "0.7.5"现在我们可以使用crate中提供的Port类型（struct Port）来创建一个exit_qemu 函数了:
// in src/main.rs
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(u32)]
pub enum QemuExitCode {
Success = 0x10,
Failed = 0x11,
}
pub fn exit_qemu(exit_code: QemuExitCode) {
use x86_64::instructions::port::Port;
unsafe {
let mut port = Port::new(0xf4);
port.write(exit_code as u32);
}
}
该函数在0xf4处定义了一个新端口，该端口同时也是 isa-debug-exit 设备的 iobase ；这之后，它会向端口写入传递的退出代码。本段代码中，我们使用u32来传递数据，因为我们之前已经将 isa-debug-exit设备的宽度iosize指定为4个字节。上述两个操作都属于unsafe操作——因为从编译器静态检查考虑，写入I/O端口可能会导致不可预知的行为。
为了指定退出状态，我们创建了一个 QemuExitCode枚举。我们思路大体上是：如果所有的测试均成功，就以成功退出码退出；否则就以失败退出码退出。这个枚举类型被标记为 #[repr(u32)]，代表每个变量都是一个u32的整数类型。我们使用退出代码0x10代表成功，0x11代表失败。实际的退出代码并不重要，只要它们不与QEMU的默认退出代码冲突即可：例如，使用退出代码0表示成功可能并不是一个好主意，因为它在转换后就变成了(0 << 1) | 1 = 1 ，而1是QEMU运行失败时的默认退出代码——这样，我们就无法将QEMU错误与成功的测试运行区分开来了。
现在我们来更新test_runner的代码，让程序在运行所有测试完毕后退出QEMU：
fn test_runner(tests: &[&dyn Fn()]) {
println!("Running {} tests", tests.len());
for test in tests {
test();
}
/// new
exit_qemu(QemuExitCode::Success);
}
当我们现在运行cargo xtest时，QEMU会在测试运行后立刻退出。然而，即使我们传递了表示成功（Success）的退出代码， cargo test依然会将所有的测试都视为失败：
> cargo xtest
Finished dev [unoptimized + debuginfo] target(s) in 0.03s
Running target/x86_64-blog_os/debug/deps/blog_os-5804fc7d2dd4c9be
Building bootloader
Compiling bootloader v0.5.3 (/home/philipp/Documents/bootloader)
Finished release [optimized + debuginfo] target(s) in 1.07s
Running: `qemu-system-x86_64 -drive format=raw,file=/…/target/x86_64-blog_os/debug/
deps/bootimage-blog_os-5804fc7d2dd4c9be.bin -device isa-debug-exit,iobase=0xf4,
iosize=0x04`
error: test failed, to rerun pass '--bin blog_os'这里的问题在于，cargo test会将所有非0的错误码都视为测试失败。
成功退出（Exit）代码
为了解决这个问题，bootimage包提供了一个 test-success-exit-code配置项，可以将指定的退出代码映射到表示成功的退出代码0：
[package.metadata.bootimage]
test-args = […]
test-success-exit-code = 33 # (0x10 << 1) | 1有了这个配置，bootimage就会将成功退出码映射到退出码0；这样一来，cargo xtest就能正确地识别出测试成功的情况，而不会将其视为测试失败。
我们的测试runner现在会在正确报告测试结果后自动关闭QEMU。我们可以看到QEMU的窗口只会显示很短的时间——我们不容易看清测试的结果。如果测试结果会打印在控制台上而不是QEMU里，让我们能在QEMU退出后仍然能看到测试结果就好了。
打印到控制台
要在控制台上查看测试输出，我们需要以某种方式将数据从内核发送到宿主系统。 有多种方法可以实现这一点，例如通过TCP网络接口来发送数据。但是，设置网络堆栈是一项很复杂的任务——这里我们选择更简单的解决方案。
串口
发送数据的一个简单的方式是通过串行端口，这是一个现代电脑中也许已不存在的旧标准接口[8]。串口非常易于编程；QEMU可将通过串口发送的数据重定向到宿主机的标准输出或是外部文件中。
用来实现串行接口的芯片被称为UARTs。在x86架构中有很多UART模型；但幸运的是，它们之间仅有的那些不同之处都是我们用不到的高级功能。目前通用的UARTs都会兼容16550 UART，所以我们在我们测试框架里采用该模型。
我们使用uart_16550 crate[9]来初始化UART，并通过串口来发送数据。为了将该crate添加为依赖，我们将我们的Cargo.toml和main.rs修改为如下：
# in Cargo.toml
[dependencies]
uart_16550 = "0.2.0"uart_16550 crate包含了一个代表UART寄存器的SerialPort结构体，但是我们仍然需要自己来创建一个相应的实例。我们使用以下内容来创建一个新的串口模块serial：
// in src/main.rs
mod serial;
// in src/serial.rs
use uart_16550::SerialPort;
use spin::Mutex;
use lazy_static::lazy_static;
lazy_static! {
pub static ref SERIAL1: Mutex<SerialPort> = {
let mut serial_port = unsafe { SerialPort::new(0x3F8) };
serial_port.init();
Mutex::new(serial_port)
};
}
就像VGA文本缓冲区一样，我们使用 lazy_static 和一个自旋锁来创建一个 static writer实例。通过使用 lazy_static ，我们可以保证init方法只会在该示例第一次被使用使被调用。
和 isa-debug-exit设备一样，UART也是用过I/O端口进行编程的。由于UART相对来讲更加复杂，它使用多个I/O端口来对不同的设备寄存器进行编程。不安全的SerialPort::new函数需要UART的第一个I/O端口的地址作为参数，从该地址中可以计算出所有所需端口的地址。我们传递的端口地址为0x3F8 ，该地址是第一个串行接口的标准端口号。
为了使串口更加易用，我们添加了 serial_print! 和 serial_println!宏:
#[doc(hidden)]
pub fn _print(args: ::core::fmt::Arguments) {
use core::fmt::Write;
SERIAL1.lock().write_fmt(args).expect("Printing to serial failed");
}
/// Prints to the host through the serial interface.
#[macro_export]
macro_rules! serial_print {
($($arg:tt)*) => {
$crate::serial::_print(format_args!($($arg)*));
};
}
/// Prints to the host through the serial interface, appending a newline.
#[macro_export]
macro_rules! serial_println {
() => ($crate::serial_print!("n"));
($fmt:expr) => ($crate::serial_print!(concat!($fmt, "n")));
($fmt:expr, $($arg:tt)*) => ($crate::serial_print!(
concat!($fmt, "n"), $($arg)*));
}
该实现和我们此前的print和println宏的实现非常类似。 由于SerialPort类型已经实现了fmt::Write trait[10]，所以我们不需要提供我们自己的实现了。
现在我们可以从测试代码里向串行接口打印而不是向VGA文本缓冲区打印了：
// in src/main.rs
#[cfg(test)]
fn test_runner(tests: &[&dyn Fn()]) {
serial_println!("Running {} tests", tests.len());
[…]
}
#[test_case]
fn trivial_assertion() {
serial_print!("trivial assertion... ");
assert_eq!(1, 1);
serial_println!("[ok]");
}
注意，由于我们使用了 #[macro_export] 属性，serial_println宏直接位于根命名空间下——所以通过use crate::serial::serial_println来导入该宏是不起作用的。
QEMU参数
为了查看QEMU的串行输出，我们需要使用-serial参数将输出重定向到stdout：
# in Cargo.toml
[package.metadata.bootimage]
test-args = [
"-device", "isa-debug-exit,iobase=0xf4,iosize=0x04", "-serial", "stdio"
]现在，当我们运行 cargo xtest，我们可以直接在控制台看到测试输出了：
> cargo xtest
Finished dev [unoptimized + debuginfo] target(s) in 0.02s
Running target/x86_64-blog_os/debug/deps/blog_os-7b7c37b4ad62551a
Building bootloader
Finished release [optimized + debuginfo] target(s) in 0.02s
Running: `qemu-system-x86_64 -drive format=raw,file=/…/target/x86_64-blog_os/debug/
deps/bootimage-blog_os-7b7c37b4ad62551a.bin -device
isa-debug-exit,iobase=0xf4,iosize=0x04 -serial stdio`
Running 1 tests
trivial assertion... [ok]然而，当测试失败时，我们仍然会在QEMU内看到输出结果——因为我们的panic handler还是依赖于println。为了模拟这个过程，我们将我们的trivial_assertion test中的断言（assertion）修改为assert_eq!(0, 1)：
可以看到，panic信息被打印到了VGA缓冲区里，而测试输出则被打印到串口上了。panic信息非常有用，所以我们希望能够在控制台中来查看它。
为panic打印错误信息
为了在panic时使用错误信息来退出QEMU，我们可以使用条件编译（conditional compilation）在测试模式下使用（与非测试模式下）不同的panic处理方式:
// our existing panic handler
#[cfg(not(test))] // new attribute
#[panic_handler]
fn panic(info: &PanicInfo) -> ! {
println!("{}", info);
loop {}
}
// our panic handler in test mode
#[cfg(test)]
#[panic_handler]
fn panic(info: &PanicInfo) -> ! {
serial_println!("[failed]n");
serial_println!("Error: {}n", info);
exit_qemu(QemuExitCode::Failed);
loop {}
}
在我们的测试panic处理中，我们用 serial_println来代替println 并使用失败代码来退出QEMU。注意，在exit_qemu调用后，我们仍然需要一个无限循环的loop——因为编译器并不知道 isa-debug-exit设备会导致程序退出。
现在，即使在测试失败的情况下QEMU仍然会运行，并会将一些有用的错误信息打印到控制台：
> cargo xtest
Finished dev [unoptimized + debuginfo] target(s) in 0.02s
Running target/x86_64-blog_os/debug/deps/blog_os-7b7c37b4ad62551a
Building bootloader
Finished release [optimized + debuginfo] target(s) in 0.02s
Running: `qemu-system-x86_64 -drive format=raw,file=/…/target/x86_64-blog_os/debug/
deps/bootimage-blog_os-7b7c37b4ad62551a.bin -device
isa-debug-exit,iobase=0xf4,iosize=0x04 -serial stdio`
Running 1 tests
trivial assertion... [failed]
Error: panicked at 'assertion failed: `(left == right)`
left: `0`,
right: `1`', src/main.rs:65:5由于现在所有的测试都将输出到控制台上，我们不再需要弹出一小会儿的QEMU窗口了——不妨把窗口藏起来吧。
隐藏 QEMU
由于我们使用isa-debug-exit设备和串行端口来报告完整的测试结果，所以我们不再需要QMEU的窗口了。我们可以通过向QEMU传递-display none参数来隐藏弹出的窗口：
# in Cargo.toml
[package.metadata.bootimage]
test-args = [
"-device", "isa-debug-exit,iobase=0xf4,iosize=0x04", "-serial", "stdio",
"-display", "none"
]这之后，QEMU将完全在后台运行：没有任何窗口会被打开。这不仅没有那么恼人，还允许我们的测试框架在没有图形界面的环境里运行——诸如自动测试CI服务器或是SSH连接里。
超时
由于 cargo xtest 会等待test runner退出，如果一个测试永远不返回，它将一直阻塞test runner。在实际应用中，这也许并不是一个大问题，因为无限循环通常是很容易避免的。在我们的这个例子里，无限循环会发生在以下几种不同的情况中：
- 引导程序bootloader加载内核失败，导致系统不停重启；
- BIOS/UEFI固件加载bootloader失败，同样会导致无限重启；
- CPU在某些函数结束时进入一个
loop {}语句，例如因为QEMU的exit设备无法正常工作而导致死循环； - 硬件触发了系统重置，例如未捕获CPU异常时（后续的文章将会详细解释）。
由于无限循环可能会在各种情况中发生，因此，bootimage工具默认为每个可执行测试设置了一个长度为5分钟的超时时间限——如果测试未在此时间限内完成，则将其标记为失败，并向控制台输出"Timed Out"即超时错误。这个功能能确保那些卡在无限循环里的测试不会一直阻塞cargo xtest。
你可以将loop {}语句添加到 trivial_assertion测试中来进行尝试。当你运行 cargo xtest时，你可以发现该测试会在五分钟后被标记为超时。超时持续的时间限可以通过Cargo.toml中的test-timeout来进行配置[11]：
# in Cargo.toml
[package.metadata.bootimage]
test-timeout = 300 # (in seconds)如果你不想为了观察trivial_assertion测试超时而等待5分钟之久，你可以暂时降低将上述值。
此后，我们不再需要trivial_assertion测试，所以我们可以将其删除。
测试VGA缓冲区
现在我们已经有了一个可以工作的测试框架了，我们可以为我们的VGA缓冲区实现创建一些测试。首先，我们创建一个非常简单的测试，来验证println是否正常运行且不会panic：
// in src/vga_buffer.rs
#[cfg(test)]
use crate::{serial_print, serial_println};
#[test_case]
fn test_println_simple() {
serial_print!("test_println... ");
println!("test_println_simple output");
serial_println!("[ok]");
}
这个测试所做的仅仅是将一些内容打印到VGA缓冲区。如果它正常结束并且没有panic，也就意味着println调用也没有panic。由于我们只需要将serial_println导入到测试模式里，所以我们添加了cfg(test)属性（attribute），来避免正常模式下 cargo xbuild可能出现的未使用导入警告（unused import warning）。
向缓冲区打印过多的行，也可能发生错误，因为有些已打印的行将会被推出屏幕。要确保即使打印很多行的也没有panic发生，我们可以创建另一个测试：
// in src/vga_buffer.rs
#[test_case]
fn test_println_many() {
serial_print!("test_println_many... ");
for _ in 0..200 {
println!("test_println_many output");
}
serial_println!("[ok]");
}
这里，我们还可以创建另一个测试函数，来验证打印的几行字符是否真的已出现在屏幕上：
// in src/vga_buffer.rs
#[test_case]
fn test_println_output() {
serial_print!("test_println_output... ");
let s = "Some test string that fits on a single line";
println!("{}", s);
for (i, c) in s.chars().enumerate() {
let screen_char = WRITER.lock().buffer.chars[BUFFER_HEIGHT - 2][i].read();
assert_eq!(char::from(screen_char.ascii_character), c);
}
serial_println!("[ok]");
}
该函数定义了一个测试字符串，使用println将其打印，然后遍历静态WRITER也就是vga字符缓冲区的屏幕字符。由于println在将字符串打印到屏幕上最后一行后会立刻附加一个新行(即输出完后有一个换行符)，所以这个字符串应该会出现在第 BUFFER_HEIGHT - 2行。
通过使用enumerate函数[12]，我们统计了变量i的迭代次数，然后用它来加载对应于c的屏幕字符。通过比较屏幕字符的ascii_character和c，我们可以确保字符串的每个字符确实出现在vga文本缓冲区中。
如你所想，我们可以创建更多的测试函数：例如一个用来测试当打印一个很长的且包装正确的行时是否会发生panic的函数，或是一个用于测试换行符、不可打印字符、非unicode字符是否能被正确处理的函数。
在这篇文章的剩余部分，我们还会解释如何创建一个集成测试，以测试不同组件之间的交互。
集成测试
在Rust中，集成测试（integration tests）的约定是将其放到项目根目录中的tests目录下(即src的同级目录)。无论是默认测试框架还是自定义测试框架都将自动获取并执行该目录下所有的测试。
所有的集成测试都是它们自己的可执行文件，并且与我们的main.rs完全独立——这也就意味着每个测试都需要定义它们自己的函数入口点。让我们创建一个名为basic_boot的例子，来看看集成测试的工作细节吧：
// in tests/basic_boot.rs
#![no_std]
#![no_main]
#![feature(custom_test_frameworks)]
#![test_runner(crate::test_runner)]
#![reexport_test_harness_main = "test_main"]
use core::panic::PanicInfo;
#[no_mangle] // don't mangle the name of this function
pub extern "C" fn _start() -> ! {
test_main();
loop {}
}
fn test_runner(tests: &[&dyn Fn()]) {
unimplemented!();
}
#[panic_handler]
fn panic(info: &PanicInfo) -> ! {
loop {}
}
由于集成测试都是单独的可执行文件，所以我们需要再次提供所有的crate属性(no_std, no_main, test_runner, 等等)。我们还需要创建一个新的入口点函数_start，用于调用测试入口函数test_main。我们不需要任何的cfg(test)属性（attribute），因为集成测试的二进制文件在非测试模式下根本不会被编译构建。
这里我们使用unimplemented宏[13]，充当test_runner暂未实现的占位符；添加简单的loop {}循环，作为panic处理器的内容。理想情况下，我们希望能向我们在main.rs里所做的一样使用serial_println宏和exit_qemu函数来实现这个函数。但是，由于这些测试的构建和我们的main.rs的可执行文件是完全独立的，我们没有办法使用这些函数。
如果现阶段你运行cargo xtest，你将进入一个无限循环，因为目前panic处理函数暂时只包含一个无限循环；你需要使用快捷键Ctrl+c，才能退出QEMU。
创建一个库
为了让这些函数能在我们的集成测试中使用，我们需要从我们的main.rs中分割出一个库，这个库应当可以被其他的crate和集成测试可执行文件使用。为了达成这个目的，我们创建一个新文件src/lib.rs：
// src/lib.rs
#![no_std]
和main.rs一样，lib.rs也是一个可以被cargo自动识别的特殊文件。我们的库现在是一个独立的编译单元，所以我们需要再次指定#![no_std]属性。
为了让我们的库可以和cargo xtest一起协同工作，我们还需要添加以下测试函数和属性：
// in src/lib.rs
#![cfg_attr(test, no_main)]
#![feature(custom_test_frameworks)]
#![test_runner(crate::test_runner)]
#![reexport_test_harness_main = "test_main"]
use core::panic::PanicInfo;
pub fn test_runner(tests: &[&dyn Fn()]) {
serial_println!("Running {} tests", tests.len());
for test in tests {
test();
}
exit_qemu(QemuExitCode::Success);
}
pub fn test_panic_handler(info: &PanicInfo) -> ! {
serial_println!("[failed]n");
serial_println!("Error: {}n", info);
exit_qemu(QemuExitCode::Failed);
loop {}
}
/// Entry point for `cargo xtest`
#[cfg(test)]
#[no_mangle]
pub extern "C" fn _start() -> ! {
test_main();
loop {}
}
#[cfg(test)]
#[panic_handler]
fn panic(info: &PanicInfo) -> ! {
test_panic_handler(info)
}
为了能在可执行文件和集成测试中使用test_runner，我们不对其应用cfg(test) 属性（attribute），且应将其设置为公有函数。同时，我们还将panic的处理程序分解为public函数test_panic_handler，这样一来它也可以用于可执行文件了。
由于我们的lib.rs是独立于main.rs进行测试的，因此当该库实在测试模式下编译时我们需要添加一个_start入口点和一个panic处理程序。通过使用cfg_attr[14]，我们可以在这种情况下有条件地启用no_main 属性。
我们还将QemuExitCode枚举和exit_qemu函数从main.rs移过来，并设置其为公有函数：
// in src/lib.rs
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[repr(u32)]
pub enum QemuExitCode {
Success = 0x10,
Failed = 0x11,
}
pub fn exit_qemu(exit_code: QemuExitCode) {
use x86_64::instructions::port::Port;
unsafe {
let mut port = Port::new(0xf4);
port.write(exit_code as u32);
}
}
现在，可执行文件和集成测试都可以从库中导入这些函数，而不需要实现自己的定义。为了使println 和 serial_println可用，我们将以下的模块声明代码也移动到lib.rs中：
// in src/lib.rs
pub mod serial;
pub mod vga_buffer;
我们将这些模块设置为公有（public），这样一来我们在库的外部也一样能使用它们了。由于这两者都用了该模块内的_print函数，所以这也是让println 和 serial_println宏可用的必要条件。
现在，可以修改main.rs代码来使用我们的库：
// src/main.rs
#![no_std]
#![no_main]
#![feature(custom_test_frameworks)]
#![test_runner(blog_os::test_runner)]
#![reexport_test_harness_main = "test_main"]
use core::panic::PanicInfo;
use blog_os::println;
#[no_mangle]
pub extern "C" fn _start() -> ! {
println!("Hello World{}", "!");
#[cfg(test)]
test_main();
loop {}
}
/// This function is called on panic.
#[cfg(not(test))]
#[panic_handler]
fn panic(info: &PanicInfo) -> ! {
println!("{}", info);
loop {}
}
#[cfg(test)]
#[panic_handler]
fn panic(info: &PanicInfo) -> ! {
blog_os::test_panic_handler(info)
}
可以看到，这个库用起来就像一个普通的外部crate。它的调用方法与其它crate无异；在我们的这个例子中，位置可能为blog_os。上述代码将blog_os::test_runner函数用于test_runner中，将blog_os::test_panic_handler函数用于cfg(test)的panic处理中。它还导入了println宏，这样一来，我们可以在我们的_start 和 panic函数中使用它了。
与此同时，cargo xrun 和 cargo xtest可以再次正常工作了。当然了，cargo xtest仍然会进入无限循环（你可以通过ctrl+c来退出）。接下来让我们在我们的集成测试中通过所需要的库函数来修复这个问题吧。
完成集成测试
就像我们的src/main.rs，我们的tests/basic_boot.rs可执行文件同样可以从我们的新库中导入类型。这也就意味着我们可以导入缺失的组件来完成我们的测试。
// in tests/basic_boot.rs
#![test_runner(blog_os::test_runner)]
#[panic_handler]
fn panic(info: &PanicInfo) -> ! {
blog_os::test_panic_handler(info)
}
这里我们使用我们的库中的test_runner函数，而不是重新实现一个test runner。至于panic处理，调用blog_os::test_panic_handler函数即可，就像我们之前在我们的main.rs里面做的一样。
现在，cargo xtest又能够正常退出了。当你运行该命令时，你会发现它为我们的lib.rs, main.rs, 和 basic_boot.rs分别构建并运行了测试。对于main.rs 和 basic_boot的集成测试，它会报告"Running 0 tests"（正在运行0个测试），因为这些文中暂时没有任何用 #[test_case]标注的函数。
我们来为basic_boot.rs中添加测试函数。举个例子，我们可以测试println是否能够正常工作而不panic，就像我们之前在vga缓冲区测试中做的那样：
// in tests/basic_boot.rs
use blog_os::{println, serial_print, serial_println};
#[test_case]
fn test_println() {
serial_print!("test_println... ");
println!("test_println output");
serial_println!("[ok]");
}
当我们运行cargo xtest时，我们可以看到它会寻找并执行这些测试函数。
由于该测试和vga缓冲区测试中的一个几乎完全相同，所以目前它看起来似乎没什么用。然而，在将来，我们的main.rs和lib.rs中的_start函数的内容会不断增长，并且在运行test_main之前需要调用一系列的初始化进程，所以这两个测试将会运行在完全不同的环境中[15]。
通过在basic_boot环境里不掉用任何初始化例程的_start中测试println函数，我们可以确保println在启动（boot）后可以正常工作。这一点非常重要，因为我们有很多部分依赖于println，例如打印panic信息。
更多的测试
集成测试的强大之处在于，它们可以被看成是完全独立的可执行文件；这也给了它们完全控制环境的能力，使得他们能够测试代码和CPU或是其他硬件的交互是否正确。
我们的basic_boot测试正是集成测试的一个非常简单的例子。在将来，我们的内核的功能会变得更多，和硬件交互的方式也会变得多种多样。通过添加集成测试，我们可以保证这些交互按预期工作（并一直保持工作）。下面是一些对于更多测试的设想：
- CPU异常：当代码执行无效操作（例如除以零）时，CPU就会抛出异常。内核会为这些异常注册处理函数。集成测试可以验证在CPU异常时是否调用了正确的异常处理程序，或者在可解析的异常之后程序是否能正确执行；
- 页表：页表定义了哪些内存区域是有效且可访问的。通过修改页表，可以重新分配新的内存区域，例如，当你启动一个软件的时候。我们可以在集成测试中调整
_start函数中的一些页表项，并确认这些改动是否会对#[test_case]的函数产生影响； - 用户空间程序：用户空间程序是只能访问有限的系统资源的程序。例如，他们无法访问内核数据结构或是其他应用程序的内存。集成测试可以启动执行禁止操作的用户空间程序验证认内核是否会将这些操作全都阻止。
可以想象，还有更多的测试可以进行。通过添加各种各样的测试，我们确保在为我们的内核添加新功能或是重构代码时，不会意外地破坏他们。这一点在我们的内核变得更大和更复杂的时候显得尤为重要。
应当panic的测试
标准库的测试框架支持允许构造失败测试的#[should_panic]标签[16]。这个功能对于验证传递无效参数时函数是否会失败非常有用——不幸的是，这个属性需要标准库的支持，因此在#[no_std]环境中将无法使用。
尽管我们不能在我们的内核中使用#[should_panic] 属性，但是通过创建一个集成测试我们可以达到类似的效果——该集成测试可以从panic处理程序中返回一个成功错误代码。接下来让我们一起创建一个文件名为should_panic的测试吧：
// in tests/should_panic.rs
#![no_std]
#![no_main]
use core::panic::PanicInfo;
use blog_os::{QemuExitCode, exit_qemu, serial_println};
#[panic_handler]
fn panic(_info: &PanicInfo) -> ! {
serial_println!("[ok]");
exit_qemu(QemuExitCode::Success);
loop {}
}
这个测试还没有完成，因为它尚未定义_start函数或是其他自定义的test runner属性。我们来补充缺少的内容：
// in tests/should_panic.rs
#![feature(custom_test_frameworks)]
#![test_runner(test_runner)]
#![reexport_test_harness_main = "test_main"]
#[no_mangle]
pub extern "C" fn _start() -> ! {
test_main();
loop {}
}
pub fn test_runner(tests: &[&dyn Fn()]) {
serial_println!("Running {} tests", tests.len());
for test in tests {
test();
serial_println!("[test did not panic]");
exit_qemu(QemuExitCode::Failed);
}
exit_qemu(QemuExitCode::Success);
}
这个测试定义了自己的test_runner函数，而不是复用lib.rs中的test_runner，该函数会在测试没有panic而是正常退出时，返回一个错误退出代码——因为这里我们希望测试会panic。如果没有定义测试函数，runner就会以一个成功错误代码退出。由于这个runner总是在执行完单个的测试后就退出，因此定义超过一个#[test_case]的函数都是没有意义的。
现在我们来创建一个应当失败的测试：
// in tests/should_panic.rs
use blog_os::serial_print;
#[test_case]
fn should_fail() {
serial_print!("should_fail... ");
assert_eq!(0, 1);
}
该测试用 assert_eq来断言（assert）0和1是否相等。毫无疑问，这当然会失败(0当然不等于1)，所以我们的测试就会像我们想要的那样panic。
当我们通过cargo xtest --test should_panic运行该测试时，我们会发现成功了因为该测试如我们预期的那样panic了。当我们将断言部分（即assert_eq!(0, 1);）注释掉后，我们就会发现测试失败，返回了信息"test did not panic"。
这种方法的缺点是它只使用于单个的测试函数；对于多个#[test_case]函数，它只会执行第一个函数因为程序无法在panic处理被调用后继续执行。我目前没有想到解决这个问题的方法，如果你有任何想法，请务必告诉我！
无约束测试
对于那些只有单个测试函数的集成测试而言(例如我们的should_panic测试)，其实并不需要test runner。对于这种情况，我们可以完全禁用test runner，直接在_start函数中直接运行我们的测试。
这里的关键就是在Cargo.toml中为测试禁用 harness flag，这个标志（flag）定义了是否将test runner用于集成测试中：如果该标志位被设置为false，那么默认的test runner和自定义的test runner功能都将被禁用，这样一来该测试就可以像一个普通的可执行程序一样运行了。
现在让我们为我们的should_panic测试禁用harness flag吧：
# in Cargo.toml
[[test]]
name = "should_panic"
harness = false移除test runner相关的代码后，我们的should_panic测试简化了不少。结果看起来如下：
// in tests/should_panic.rs
#![no_std]
#![no_main]
use core::panic::PanicInfo;
use blog_os::{QemuExitCode, exit_qemu, serial_println};
#[no_mangle]
pub extern "C" fn _start() -> ! {
should_fail();
serial_println!("[test did not panic]");
exit_qemu(QemuExitCode::Failed);
loop{}
}
fn should_fail() {
serial_print!("should_fail... ");
assert_eq!(0, 1);
}
#[panic_handler]
fn panic(_info: &PanicInfo) -> ! {
serial_println!("[ok]");
exit_qemu(QemuExitCode::Success);
loop {}
}
现在我们可以通过我们的_start函数来直接调用should_fail函数了，如果返回则返回一个失败退出代码并退出——现在当我们执行cargo xtest --test should_panic时，我们可以发现测试的行为和之前完全一样。
除了创建should_panic测试，禁用harness attribute对复杂集成测试也很有用：例如，当单个测试函数会产生一些边际效应需要通过特定的顺序执行时。
总结
测试是一种非常有用的技术，它能确保特定的部件拥有我们期望的行为。即使不能直接显示是否有bug，测试仍然是用来寻找bug的利器，尤其是用来避免回归。
本文讲述了如何为我们的Rust内核创建测试框架。我们使用Rust的自定义框架功能，为我们的裸机环境实现了一个简单的#[test_case] 属性支持；通过使用QEMU的isa-debug-exit设备，我们的test runner可以在运行测试后退出QEMU并报告测试状态；我们还为串行端口实现了一个简单的驱动，使得错误信息可以被打印到控制台而不是VGA buffer中。
在为println宏创建了一些测试后，我们在本文的后半部分还探索了集成测试。我们了解到它们位于tests目录中，并被视为完全独立的可执行文件。为了使他们能够使用exit_qemu 函数和 serial_println 宏，我们将大部分代码移动到一个库里，使其能够被导入到所有可执行文件和集成测试中。由于集成测试在各自独立的环境中运行，所以能够测试与硬件的交互或是创建应该panic的测试。
我们现在有了一个在QEMU虚拟环境上运行的测试框架。在未来的文章里，我们会创建更多的测试，来让我们的内核在变更复杂的同时仍然保持可维护性。
下期预告
在下一篇文章中，我们将会探索CPU异常。这些异常将在一些非法事件发生时由CPU抛出，例如抛出除以零或是访问没有映射的内存页（通常也被称为page fault即缺页异常）。能够捕获和检查这些异常，对将来的调试来说是非常重要的。异常处理与键盘支持所需的硬件中断处理十分相似。
参考
- ^https://doc.rust-lang.org/book/second-edition/ch11-00-testing.html
- ^Crate `test` https://doc.rust-lang.org/test/index.html
- ^请参考这个实现： https://github.com/japaric/utest
- ^#[should_panic] tests https://doc.rust-lang.org/book/ch11-01-writing-tests.html#checking-for-panics-with-should_panic
- ^本系列文章第三章有提及 https://zhuanlan.zhihu.com/p/53745617
- ^https://wiki.osdev.org/I/O_Ports#The_list
- ^https://docs.rs/x86_64/0.7.5/x86_64/
- ^译者注：玩过单片机的同学应该知道，其实译者上大学的时候有些同学的笔记本电脑还有串口的，没有串口的同学在烧录单片机程序的时候也都会需要usb转串口线，一般是51；像stm32虽然有st-link，不过其实也可以用串口来下载
- ^Crate `uart_16550` https://docs.rs/uart_16550
- ^https://doc.rust-lang.org/nightly/core/fmt/trait.Write.html
- ^https://github.com/rust-osdev/bootimage#configuration
- ^https://doc.rust-lang.org/core/iter/trait.Iterator.html#method.enumerate
- ^https://doc.rust-lang.org/core/macro.unimplemented.html
- ^https://doc.rust-lang.org/reference/conditional-compilation.html#the-cfg_attr-attribute
- ^译者注：也就是说虽然现在看起来差不多，但是在将来该测试和vga buffer中的测试会很不一样，有必要单独拿出来，这两者并没有重复
- ^https://doc.rust-lang.org/rust-by-example/testing/unit_testing.html#testing-panics
扫一扫
2580
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
