How to opt out of running a doc test?

Question

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?

Answer 1

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.