Repository navigation
rustdoc: Emit a lint warning if doctest contains #[test] functions but isn't marked test_harness #157458
Description
I tried this code:
/// ```
/// #[test]
/// fn my_test() {
/// panic!("this test should fail");
/// }
/// ```
const _: () = ();I expected to see this happen: running cargo test would try to run my_test and report it failed.
Instead, this happened: it reports the doctest ran successfully.
I want to be able to use #[test] in a doctest to document things that are intended to only be used inside a #[test] (since they print errors to stdout/stderr and/or panic for better testing ergonomics, instead of returning a Result).
Meta
I tried it on 1.96.0 stable as well as 1.98.0-nightly (2026-06-03 b354133)
Activity
fmease commentedon Jun 5, 2026
While history could've taken a different branch where doctests that don't contain a
mainfunction and don't contain statements other than item statements get compiled under--test, in our reality that didn't happen and it would most likely require an edition to change this behavior (given under--testcfgtestis active); well rustdoc could extend its naive "static analysis" of doctests and look for functions annotated with#[test](which will have false positive like the existing checks) to contain the number of potential regressions.In any case, you can annotate your doctest with code block attribute
test_harnessto make it behave like you want:fmease commentedon Jun 5, 2026
That attribute isn't documented currently, PR #148183 will rectify that.
fmease commentedon Jun 5, 2026
Do you feel code block attribute
test_harnessis sufficient or would you like rustdoc to try to autodetect simple cases (fallibly)? As I said that might only be possible in a new edition depending on the complexity of the heuristic or the amount of crater regressions.programmerjake commentedon Jun 5, 2026
maybe emit a warning if it detects
#[test]functions and you didn't usetest_harness? that should work on all editions.fmease commentedon Jun 5, 2026
That sounds workable 👍
[-]#[test] fn my_test() in doctests should run[/-][+]rustdoc: Emit a lint warning if doctest contains `#[test]` functions but isn't marked `test_harness`[/+]