成为 Rust 文档怀疑者

通过 Cargo 测试您的 Rust Markdown。

入门

将以下内容放入 Cargo.toml 以添加 skeptic 依赖项

[build-dependencies]
skeptic = "0.13"

[dev-dependencies]
skeptic = "0.13"

同样在 Cargo.toml 中，在 [package] 部分，添加以下内容

build = "build.rs"

这将通过构建脚本添加 Skeptic，您将通过该脚本告诉 Skeptic 从一组 Markdown 文件中构建测试用例。

在 build.rs 中编写以下内容以测试 README.md 中的所有 Rust 代码块

extern crate skeptic;

fn main() {
    // generates doc tests for `README.md`.
    skeptic::generate_doc_tests(&["README.md"]);
}

如果您想测试多个 Markdown 文件，您只需构建一个文件名列表，并将其提供给 generate_doc_tests。为了帮助您，方法 markdown_files_of_directory 将创建此类列表，列出指定目录中的 Markdown 文件。您可以按需添加更多文件到该列表中

extern crate skeptic;

use skeptic::*;

fn main() {
    // Add all markdown files in directory "book/".
    let mut mdbook_files = markdown_files_of_directory("book/");
    // Also add "README.md" to the list of files.
    mdbook_files.push("README.md".into());
    generate_doc_tests(&mdbook_files);
}

最后，在 tests/skeptic.rs 中放置以下宏以将生成的测试用例绑定到 cargo test

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

现在，在 README.md 中的任何 Rust 代码块都将通过 cargo test 进行测试。

用户指南

Rust Skeptic 不是基于 rustdoc 的。它在许多情况下表现相似，但并非所有情况。以下是 Skeptic 系统的简要介绍。

注意：[此README.md文件本身由Rust Skeptic进行测试]。因为它展示了如何使用Markdown语法，所以本文档的标记有点奇怪，下面的输出也是如此，尤其是在展示Markdown的代码块（```rust）时。

您必须显式请求rust代码块以获得Rust测试，使用```rust。这与rustdoc不同，rustdoc默认假设代码块是Rust。这样做的原因是，常见的Markdown解析器，如GitHub上使用的解析器，也默认不假设是Rust：您要么同时获得Rust语法高亮和测试，要么同时没有Rust语法高亮和测试。

所以下面的内容没有经过Skeptic测试。

```
let this_is_not_going_to_be_compiled_and_run = @all;
It doesn't really matter what's in here.
```

要表示Rust代码，代码块被标记为rust

```rust
fn main() {
   println!("Calm your skepticism. This example is verified.");
}
```

Skeptic将解释代码块的“信息字符串”中的其他单词（这些单词应以逗号,分隔，以兼容GitHub）。这些单词会改变测试的解释方式：ignore、no_run和should_panic。

ignore 信息字符串

ignore信息字符串会使测试完全被忽略。在测试期间不会编译或运行。如果示例是用Rust编写的（并且您希望将其突出显示），但已知它是不完整的（因此无法直接编译），这可能会很有用。

```rust,ignore
fn do_amazing_thing() -> i32 {
   // TODO: How do I do this?
   unimplemented! whatever I'm distracted, oh cookies!
```

no_run 信息字符串

no_run信息字符串会使示例代码在测试期间不运行。但标记为no_run的代码仍然会被编译。这对于可能具有副作用或依赖关系的示例/测试很有用，这些副作用或依赖关系在测试情况下是不希望的。

```rust,no_run
fn do_amazing_thing() -> i32 {
   // TODO: How do I do this?
   unimplemented!()
}

fn main() {
   do_amazing_thing();
}
```

should_panic 信息字符串

should_panic会使测试仅在测试由于panic!()终止时通过。

```rust,should_panic
fn main() {
   assert!(1 == 100);
}
```

Skeptic模板

与rustdoc不同，Skeptic默认不修改测试前的示例。Skeptic示例被放置在'.rs'文件中，编译后运行。

这意味着 - 默认情况下 - Skeptic示例需要main函数，如上面所有的示例。示例隐式包装在main中，以及通过模板控制extern crate语句和crate属性的注入。

文档的模板位于一个单独的文件中，该文件位于文件系统中的文档旁边，并且具有与文档文件相同的完整名称，但附加了".skt.md"模板。

例如，此文件README.md将其模板存储在README.md.skt.md中。

此方案允许Markdown通过标准Markdown渲染器自然显示，而不会显示模板本身。奇怪的文件扩展名也是如此，以便模板本身被解释为有效的Markdown。

考虑这个例子

let p = PathBuf::from("foo");
println!("{:?}", p);

此示例在没有定义main和导入PathBuf的情况下无法编译，但示例本身不包含这些样板代码。相反，它被标记为skt-foo，表示Skeptic模板foo，如下所示

```rust,skt-foo
let p = PathBuf::from("foo");
println!("{:?}", p);
```

这告诉Skeptic在模板文件中查找另一个具有相同skt-foo标记的Markdown块，并使用标准的Rust format!宏将它们组合起来。下面是模板的样式

```rust,skt-foo
use std::path::PathBuf;

fn main() {{
    {}
}}
```

模板是 Rust格式说明符，必须接受一个参数（即它们需要包含字符串"{}"）。有关模板的更多信息，请参见（旧版）模板示例。

请注意，在模板中，实际的花括号需要成对出现。

旧式、文档全局模板

在文档中，一个被标记为skeptic-template的rust代码块将被用作文档中所有未明确标记的示例的模板。

```rust,skeptic-template
use std::path::PathBuf;

fn main() {{
    {}
}}
```

Rustdoc风格的未显示行，带有#

与rustdoc一样，skeptic会在编译之前删除任何代码行前面的# 。在显示时隐藏此类行需要自定义的Markdown渲染器支持。

更简单的解决方案

如果您不需要高级功能，只需测试Markdown内容，那么doc-comment crate可能更适合您的需求。它还可以防止重新编译，并可以用作dev-dependency。

许可证

许可协议之一

• Apache许可证，版本2.0（LICENSE-APACHE或https://apache.ac.cn/licenses/LICENSE-2.0）
• MIT许可证（LICENSE-MIT或https://opensource.org/licenses/MIT）

贡献

除非您明确声明，否则根据Apache-2.0许可证定义的，您有意提交给作品包含的贡献，将根据上述条款双许可，没有任何附加条款或条件。