(the following text was initially published in this issue)
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 questions:
- 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?
- How about testing other IO operations: network, databases, etc.? For example by defining custom handlers.
