如何选择不运行文档测试? [英] How to opt out of running a doc test?

问题描述

我正在编写一个 Rust 库，我想在我的文档中提供示例

1. 作为运行cargo test
的一部分进行编译
2. 不要跑.

这可能吗?

我正在编写一个数据库客户端库，这些示例使用了一个假设的、不存在的数据库服务器.因此，示例在运行时总是失败，但示例在语法上有效很重要.因此，我的要求如上.

如果没有办法做我想做的事，那么如何选择不让 cargo test 运行特定的文档测试?即，让 cargo run 编译并运行一些 doc 测试，但完全忽略其他一些测试?

解决方案

这记录在 rustdoc 书，特别是关于属性的章节.

您的起始代码块分隔符应如下所示:

///```no_run

来自书中:

<块引用>

///```no_run///环形 {///println!("Hello, world");///}///```

no_run 属性将编译您的代码，但不会运行它.这是对于诸如这是检索网页的方法"等示例很重要，您希望确保编译，但可能会在测试中运行没有网络访问权限的环境.

要完全省略构建，请使用 ignore 而不是 no_run.

I'm writing a Rust library and I want to provide examples in my documentation that

1. compile as part of running cargo test
2. do not run.

Is this possible?

I'm writing a database client library, and the examples make use of a hypothetical, non-existing database server. As such, the examples always fail when run, but it's important that the examples be valid syntactically. Hence my requirements above.

If there's no way to do what I want, then how does one opt out of having cargo test run a specific doc test? I.e., have cargo run compile-and-run some doc tests but completely ignore some others?

解决方案

This is documented in The rustdoc book, specifically the chapter about attributes.

Your opening codeblock delimiter should look like:

/// ```no_run

From the book:

/// ```no_run
/// loop {
///     println!("Hello, world");
/// }
/// ```

The no_run attribute will compile your code, but not run it. This is important for examples such as "Here's how to retrieve a web page," which you would want to ensure compiles, but might be run in a test environment that has no network access.

To omit build completely use ignore instead of no_run.

这篇关于如何选择不运行文档测试?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！