Testing stdout output in documentation tests

[newpavlov]

Currently there is no standard way to specify what example code example writes to stdout in doctests, thus makinf it impossible to test this output. Borrowing from Python I would like to propose to add something like \\> foo to doctest to specify stdout output of snippets. For example:

println!(); // prints just a newline
//> 
println!("hello there!");
//> hello there!

#[derive(Debug)]
struct Foo { a: u8 }
println!("{:?}", Foo { a: 100} );
//> Foo { a: 100 }

Using it cargo test will be able to test standard output of the program, thus making some testing cases a lot easier. Additionally it will be an incentive for crate authors to use this functionality thus making examples easier to understand for crate users.

Because output will be checked after program execution this example will pass tests:

println!("foo");
println!("bar");
//> foo
//> bar

While it should be considered a bad practice to write doctests in such way, checking relations between code line and output will be technically challenging, so I think it's better to leave it for crate authors to handle.

Unresolved question: should stderr be considered as stdout for testing purposes, or is it better to add similar functionality for stderr as well, e.g. //stderr> foo?

[shingtaklam1324]

So this is similar to what Elixir has for doctests here, except for using stdout instead of iex? This can be very powerful for documenting functions that have IO.

Regarding stderr, I think it should be considered seperate from stdout, as it (should) be used for seperate functions as stdout.