Showing unittest in documentation (Was Re: std.unittests [updated] for review)

[spir]

On 01/24/2011 10:03 PM, Andrei Alexandrescu wrote:
>> One other thing, using writefln is considered bad form in unit tests
>> (you want *no* output if the unit test works). But many examples might
>> want to demonstrate how e.g. an object interacts with writefln. Any
>> suggestions? The assert line above is not very pretty for example...
>
> Yah, that is an issue. For examples that do non-unittesty stuff (e.g. writeln,
> use sockets etc.) we can still use the old-style documentation. By the way, for
> all examples that don't explicitly describe writeln, we shouldn't use writeln
> anyway. Instead, we should use assert to clearly describe what happens:
>
> // BAD: example of concatenation
> string s1 = "Hello, ";
> string s2 = "world!";
> writeln(s1 ~ s2);  // writes Hello, world!
>
>
> // GOOD: example of concatenation
> string s1 = "Hello, ";
> string s2 = "world!";
> assert(s1 ~ s2 == "Hello, world!"); // no need for comment

This is a very good example.
It seems that in the D style, and in Phobos use, unittests are only considered 
for maintenance. (What is sometimes called regression test suites: 
http://en.wikipedia.org/wiki/Regression_testing).
Many programmers instead use test funcs to provide feedback on how pieces of 
code work during development. Even when it does not bug. I for one constantly 
run tests. Using the example above, my initial test func would be eg:

string s1 = "Hello, ";
string s2 = "world!";
writefln("%s ~ %s --> %s", s1,s2, s1 ~ s2);

This goes well with "exploratory programming". To setup things correctly, I 
need much information on all aspects of the part of code I'm currently dealing 
with, including object internal state, for instance (toString is vital, often 
defined before anything else). Data on what works fine also helps in fixing 
what doesn't.
Then, when all work fine, I would comment out writelfn and replace it with an 
assert. But I keep it so that in case of later bug introduced by changes, code 
is still there to provide all necessary information to diagnose. (Hope I'm clear.)
Such verbose test suite, when done right, is also a 'show' of all kinds of 
functionality a module is able to provide, at best with self-explaining output.

Now, for sure assert and write* are somewhat redondant for testing. What I 
dream of is a testing func similar to assert() but that writes info out even on 
success; then a silent mode would switch that off and write only on failure. 
Would be easier if this func takes 2 params, eg:
	check(expression, expectation);
writes out on success:
	expression --> to!string(expectation)
writes out on failure:
****** test error **************************
expression	: (expression)
expectation	: to!string(expectation)
outcome		: to!string(outcome)
********************************************
This would also avoid having a separate testing func for cases where 
expectation is an exception.


Denis
-- 
_________________
vita es estrany
spir.wikidot.com