怀疑者

在 Markdown 文件中测试 Rust 代码块。

概述

该库通过将代码块嵌入 Rust 源代码并构建为一个 crate 来执行 Markdown 文件中的代码块。这种方法的优势在于依赖项解析由 cargo 完成。这意味着与更新 Rust 工具链相关的依赖项问题不会发生。

入门

doubter 将目标 Markdown 文件嵌入 Rust 代码作为 公共 文档注释。因此，有必要为测试代码块单独创建一个新的 crate，而不是从发布的 crates 中创建。这些 crate 通常在 [workspace.members] 中注册。

使用过程宏

将 doubter 的依赖项添加到 Cargo.toml。如果代码块中需要某些外部 crates，指定它们作为 [dev-dependencies] 的成员。

[dependencies]
doubter = "0.1.0"

[dev-dependencies]
rand = "0.5"

然后，修改 src/lib.rs 以指定目标 Markdown 文件的路径。

#[macro_use]
extern crate doubter;

generate_doc_tests! {
    include = "README.md",
    include = "docs/**/*.md",
}

宏 generate_doc_tests!(...) 接受一个以逗号分隔的字段列表。当前支持的以下字段键

• include - 字符串
  A glob pattern that points to the path to the Markdown file(s) to be tested. Required to be a relative path from cargo's manifest directory.
• mode - 字符串，可选
  The mode to convert Markdown files to doctest. Supported values are as follows
  • "raw" (default) : embeds the Markdown files in Rust source as it is.
  • "extract" : extracts code blocks and emit as doctest per blocks.
• use_external_doc - 字符串或布尔值，可选
  指定是否使用 #[doc(include = "...")] 来嵌入 Markdown 文件。当此字段启用时，mode 的值将被强制设置为 "raw"。

目前，函数式过程宏的实现正在使用 proc-macro-hack。通过自定义 Derive 的过程宏定义有一些限制，并且 use 风格的导入无法按预期工作。您可以通过禁用功能标志 hack 将实现切换到 Macros 1.2（此功能标志默认启用）。

[dependencies.doubter]
version = "0.1.0"
default-features = false

使用自定义构建脚本（即 build.rs）

过程宏的使用有一些限制（例如，传递给字段的字面量不能通过使用其他宏来计算）。doubter 提供了一个低级 API，可以从 build.rs 生成测试代码。

首先，将 doubter 的依赖项移动到 [build-dependencies]

-[dependencies]
+[build-dependencies]
doubter = "0.1.0"

build.rs 中生成测试用例的代码如下

extern crate doubter;

fn main() {
    let config = doubter::Config {
        includes: vec![...],
        mode: None,
        use_external_doc: false,
    };

    let out_path = std::env::var_os("OUT_DIR")
        .map(std::path::PathBuf::from)
        .unwrap()
        .join("doubter-tests.rs");

    let mut file = std::fs::OpenOptions::new()
        .write(true).create(true).truncate(true)
        .open(out_path)
        .unwrap();

    doubter::generate_doc_tests(config, &mut file).unwrap();
}

最后，如下将生成的源代码包含到 lib.rs 中

include!(concat!(env!("OUT_DIR"), "/doubter-tests.rs"));

示例

请参阅 crates/ 内的测试 crate 内部。

许可协议

doubter 在 MIT 许可协议 下发布。