documented unit tests as examples

[Lutger via Digitalmars-d]

On Friday, 13 May 2016 at 21:00:04 UTC, Steven Schveighoffer 
wrote:
> On 5/13/16 4:55 PM, Meta wrote:
>
>> When I was new to D and I first saw the `assert(...)` idiom in 
>> an
>> example in the documentation, it confused me for a minute or 
>> two, but if
>> you know what `assert` does you can quickly wrap your head 
>> around the
>> fact that it's both a test and an example. This would benefit 
>> users that
>> are completely new to programming in general, however.
>
> Given the fact that asserts aren't always run, it's never 
> comforting to me to run a program that tests something and have 
> it give NO feedback. In fact, I frequently find myself 
> triggering the assert to make sure it's actually being run (and 
> I've caught the build not actually running it many times).
>
> This has a negative affect on anyone actually looking to see 
> how a D function works. I can write a program that does nothing 
> easily enough, why such a complicated example?
>
> -Steve

This is a flaw of the simplistic test runner, not of the idea of 
unittests itself. Every other unittest system I worked with, 
including for example unit-threaded in D, reports a summary of 
the amount of tests that are ran. Very simple and just enough 
information that the test you just added has indeed been 
executed. One line is enough.

Honestly I think keeping asserts in examples is better than the 
assert/writeln hybrid approach, because 1) asserts give the 
reader exact information about the expected behavior and 
contracts of a function (this information is lost to the reader 
when the asserts are reduced to print statements) and 2) having 
unittests compile to something very differently depending on 
context sounds like adding too much accidental complexity.

Ideally there would be a way to print the values of all arguments 
given to an assert, that would be the most informative. And 
zooming out just a one liner with the number of tests or asserts 
ran and the number succeeded. I think this should be the domain 
of an external tool or library though, not the compiler itself. 
It is certainly possible to create such a tool and have phobos 
use it, no reason to add more complexity to the language itself.