文档测试 ​

核心概念 ​

文档测试(doctest)是 Rust 独特的测试机制——文档注释中的代码块会在 cargo test 时被自动编译和运行。这保证了文档中的示例代码始终与实际 API 保持同步,不会出现文档过时、示例无法运行的问题。

每个文档注释中用 ``` 标记的代码块默认被视为 Rust 代码,会被包装在一个隐藏的 fn main() 中编译执行。可以通过标记(如 ignore、no_run、should_panic、compile_fail)控制测试行为。

rust
/// 将字符串转为大写
///
/// # 示例
///
/// ```
/// // 这段代码会在 cargo test 时自动运行
/// let result = to_upper("hello");
/// assert_eq!(result, "HELLO");
/// ```
///
/// 空字符串也能正常处理:
///
/// ```
/// let result = to_upper("");
/// assert_eq!(result, "");
/// ```
pub fn to_upper(s: &str) -> String {
    s.to_uppercase()
}

fn main() {
    println!("{}", to_upper("hello"));
}

代码块标记 ​

rust
/// 各种文档测试标记
///
/// 默认:编译并运行
/// ```
/// assert_eq!(1 + 1, 2);
/// ```
///
/// `no_run`:编译但不运行(用于有副作用的代码)
/// ```no_run
/// std::process::exit(0);
/// ```
///
/// `ignore`:完全跳过(不编译也不运行)
/// ```ignore
/// // 这段代码不会被测试
/// unimplemented!()
/// ```
///
/// `should_panic`:预期 panic
/// ```should_panic
/// panic!("预期的 panic");
/// ```
///
/// `compile_fail`:预期编译失败
/// ```compile_fail
/// let x: i32 = "not a number";
/// ```
///
/// `text`:纯文本,不作为代码处理
/// ```text
/// 这不是代码,只是说明文字
/// ```
pub fn example() {}

fn main() {}
标记编译运行用途
无标记是是普通示例
no_run是否网络/文件操作
ignore否否临时跳过
should_panic是是(预期 panic)错误处理示例
compile_fail是(预期失败)否类型安全示例
text否否纯文本说明

隐藏代码行 ​

rust
/// 计算平均值
///
/// ```
/// # // 以 # 开头的行在文档中不显示,但会被编译运行
/// # fn average(nums: &[f64]) -> f64 {
/// #     if nums.is_empty() { return 0.0; }
/// #     nums.iter().sum::<f64>() / nums.len() as f64
/// # }
/// let nums = vec![1.0, 2.0, 3.0, 4.0, 5.0];
/// let avg = average(&nums);
/// assert_eq!(avg, 3.0);
/// ```
pub fn average(nums: &[f64]) -> f64 {
    if nums.is_empty() {
        return 0.0;
    }
    nums.iter().sum::<f64>() / nums.len() as f64
}

/// 使用外部 crate 的示例
///
/// ```
/// # // # 行用于添加必要的 use 和 fn main,但不在文档中显示
/// # use std::collections::HashMap;
/// let mut map = HashMap::new();
/// map.insert("key", "value");
/// assert_eq!(map.get("key"), Some(&"value"));
/// ```
pub fn map_example() {}

fn main() {
    let avg = average(&[10.0, 20.0, 30.0]);
    println!("平均值: {}", avg);
}

文档测试中使用 ? 运算符 ​

rust
/// 解析整数
///
/// ```
/// # // 文档测试默认包装在 fn main() 中
/// # // 要使用 ?,需要让 main 返回 Result
/// # fn main() -> Result<(), Box<dyn std::error::Error>> {
/// let num: i32 = "42".parse()?;
/// assert_eq!(num, 42);
/// # Ok(())
/// # }
/// ```
///
/// 另一种写法(使用隐藏的 main):
///
/// ```
/// fn try_parse() -> Result<(), Box<dyn std::error::Error>> {
///     let num: i32 = "123".parse()?;
///     assert_eq!(num, 123);
///     Ok(())
/// }
/// # try_parse().unwrap();
/// ```
pub fn parse_int(s: &str) -> Result<i32, std::num::ParseIntError> {
    s.parse()
}

fn main() {
    match parse_int("42") {
        Ok(n) => println!("解析成功: {}", n),
        Err(e) => println!("解析失败: {}", e),
    }
}

基本示例 ​

rust
/// 一个带有完整文档测试的栈实现
///
/// # 示例
///
/// ```
/// let mut stack = SimpleStack::new();
///
/// // 压入元素
/// stack.push(1);
/// stack.push(2);
/// stack.push(3);
///
/// // 弹出元素(后进先出)
/// assert_eq!(stack.pop(), Some(3));
/// assert_eq!(stack.pop(), Some(2));
///
/// // 查看栈顶
/// assert_eq!(stack.peek(), Some(&1));
///
/// // 长度和空检查
/// assert_eq!(stack.len(), 1);
/// assert!(!stack.is_empty());
/// ```
///
/// 空栈的行为:
///
/// ```
/// let mut stack: SimpleStack<i32> = SimpleStack::new();
/// assert!(stack.is_empty());
/// assert_eq!(stack.pop(), None);
/// assert_eq!(stack.peek(), None);
/// ```
pub struct SimpleStack<T> {
    data: Vec<T>,
}

impl<T> SimpleStack<T> {
    /// 创建空栈
    pub fn new() -> Self {
        SimpleStack { data: Vec::new() }
    }

    /// 压入元素
    pub fn push(&mut self, item: T) {
        self.data.push(item);
    }

    /// 弹出栈顶元素
    pub fn pop(&mut self) -> Option<T> {
        self.data.pop()
    }

    /// 查看栈顶元素
    pub fn peek(&self) -> Option<&T> {
        self.data.last()
    }

    /// 栈的长度
    pub fn len(&self) -> usize {
        self.data.len()
    }

    /// 是否为空
    pub fn is_empty(&self) -> bool {
        self.data.is_empty()
    }
}

fn main() {
    let mut stack = SimpleStack::new();
    stack.push("hello");
    stack.push("world");
    println!("弹出: {:?}", stack.pop());
    println!("栈顶: {:?}", stack.peek());
}

常见问题 ​

问题一:文档测试是怎么编译的?

每个代码块被编译为一个独立的程序。Cargo 自动添加 extern crate 和 fn main() 包装。以 # 开头的行会被编译但不显示在文档中。

问题二:文档测试可以使用当前 crate 的函数吗?

可以。文档测试会自动导入当前 crate。不需要显式写 use my_crate::*,直接使用公共 API 即可。

问题三:怎么只运行文档测试?

cargo test --doc 只运行文档测试。cargo test --doc -- function_name 运行特定函数的文档测试。

问题四:文档测试的编译比普通测试慢?

是的。每个代码块是独立编译的,如果文档中有很多代码块,编译时间会较长。可以将相关的断言合并到一个代码块中。

适用场景 ​

  • API 使用示例:展示函数的正确用法
  • 行为验证:通过断言确保文档描述的行为正确
  • 教程代码:crate 文档中的入门示例
  • 边界条件说明:展示空输入、错误输入的处理

注意事项 ​

  • 默认代码块会被编译和运行
  • 用 # 开头隐藏辅助代码
  • no_run 用于有副作用的代码
  • ignore 完全跳过测试
  • 每个代码块独立编译,注意导入
  • cargo test --doc 只运行文档测试

总结 ​

文档测试是 Rust 的特色机制,文档注释中的代码块在 cargo test 时自动编译运行,确保文档与实现同步。通过标记控制行为:无标记(编译+运行)、no_run(只编译)、ignore(跳过)、should_panic(预期 panic)、compile_fail(预期编译失败)。用 # 开头隐藏辅助代码行。要使用 ? 运算符,需要隐藏的 fn main() -> Result<...> 包装。cargo test --doc 只运行文档测试。每个代码块独立编译,合并相关断言可以减少编译时间。