Showing unittest in documentation (Was Re: std.unittests [updated] for review)
spir
denis.spir at gmail.com
Mon Jan 24 14:54:10 PST 2011
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
More information about the Digitalmars-d
mailing list