Rust Doctests
Rust doctests are code examples written inside documentation comments that the compiler extracts, compiles and runs as real tests, so your documentation's example code is guaranteed to keep working instead of silently rotting out of date.
Why it exists
Documentation examples rot. A function's signature changes, someone updates the code but forgets the comment above it, and now new users copy paste an example that no longer compiles. Rust doctests exist to make that impossible to ignore: if an example in your docs is wrong, the test suite fails, not just the documentation.
The mental model
Treat every code block in your doc comments as a tiny unit test that happens to double as a tutorial. You are not writing prose that describes code, you are writing code that also happens to explain itself, and the compiler holds you to both jobs at once.
How it works
Above an item, a doc comment starts with triple slashes, and a fenced code block inside it, marked with three backticks, is treated as Rust source. When you run cargo test, cargo extracts every such block, wraps it in a hidden main function if one is not already present, compiles it as a standalone binary and executes it. A block passes if it compiles and does not panic. You can write assert_eq to check a return value, use the question mark operator on a function that returns Result to propagate errors, or annotate the block with should_panic if failure is the expected behavior. Lines you want to run but hide from the rendered documentation can be prefixed with a leading hash symbol.
When it matters
Doctests matter most for library crates published to crates.io, where the public API documentation on docs.rs is often a user's first and only experience with your crate before they commit to using it. The footgun is doctest cost: each block compiles as a separate binary, so a crate with hundreds of doctests can noticeably slow down cargo test, which is why some teams mark expensive or environment dependent examples as no_run or ignore.
A concrete example
A crate defines a function called parse_duration. Its doc comment includes an example showing parse_duration parsing the string 30s and asserting the result equals thirty seconds. If a later refactor changes the function to return a Result instead of a bare Duration, that example fails to compile the moment cargo test runs, catching the breaking documentation change before it ever reaches a release.
Interview question
A Rust library's cargo test run fails on a doctest inside a doc comment for a public function, even though every regular unit test in the tests folder passes. What does this tell you?
- a.The example code shown in that function's documentation no longer compiles or runs correctly against the current implementationCorrect
- b.Doctests are unrelated to compilation and this failure must be a flaky test runner issue
- c.The compiled binary has a runtime crash unrelated to documentation
- d.The function is missing a doc comment entirely, which cargo test treats as a failure
Why? this is the answer
Doctests compile and execute the exact code shown in the documentation, so a doctest failure means that specific example is now out of sync with the real API, which is precisely the drift doctests are designed to catch. Option D is wrong because a missing doc comment produces no doctest at all rather than a failing one, and there is nothing flaky about a deterministic compile step.
Just read this? Test yourself on what you have been reading.
Read the original → doc.rust-lang.org
- #error
- #missing-source
- #rust
You just looked this up. Could you explain it out loud?
That is the part interviews actually test. Tezvyn takes questions like this one and gives you what the interviewer is really checking, the answer that lands, and the mistake that ends the conversation, in the four minutes before your next meeting.
The iPhone app is on the way
We are building it. Until it lands, nothing here is held back from you: every interview card, your saved cards, streaks and the job board all work in Safari, plus hundreds of free practice quizzes of thirty questions each. Sign in and it all carries over to the app the day it arrives.
Want it as an icon? Tap Share at the bottom of Safari, then Add to Home Screen. It opens full screen and the cards you have read stay available offline.
We are hiring for this. Every open role lists the topics its interview covers, so you can prepare for the real thing rather than guessing.
See open roles