std.unittests for (final?) review

[Lars T. Kyllingstad]

On Sun, 02 Jan 2011 20:44:50 -0800, Jonathan M Davis wrote:

> Okay. As some of you are aware, I created a module with unit testing
> functions when I wrote std.datetime, and it really helped with writing
> the unit tests for std.datetime. It has been at least somewhat reviewed
> here previously, and that has definitely improved it. However, it has
> not yet been decided whether it's going to go into Phobos along with
> std.datetime. I'd like it to, but it hasn't been voted on, and I'm not
> sure that it's been reviewed as heavily as it should be. So, I'm posting
> the most up-to-date version in the hopes of getting any necessary
> changes found and made so that it can be voted on. Andrei has yet to
> weigh in on std.unittests at all, so I don't know if we're actually
> going to get a vote on it, but I'm presenting it for (final?) review so
> that it can be voted in if that's what he wants to do.
> 
> The code: http://is.gd/jZEVl
> 
> 
> Both the source file and the ddoc hmtl file are included. And unlike
> std.datetime, it's actually straightforward enough that it makes sense
> for your average program to actually look at it.
> 
> To be clear, this module has 2 purposes:
> 
> 1. Improve error messages on test failure. A good example of this is
> assertEqual, which prints out both of the values being compared so that
> you don't have to add a print statement (or run a debugger) and rerun
> the test to see what the actual values were.
> 
> 2. Reduce boiler-plate code in unit tests. A good example of this is
> assertExThrown. Testing whether a function call actually throws an
> exception like it's supposed to becomes a single line of code instead of
> being around 10 lines.
> 
> This module does _not_ attempt to change how unit testing in D
> fundamentally works. It does not print out on success. It doesn't make
> it so that a unittest block continues after a failure occurs in that
> block. All of the assertXXX functions throw an AssertError upon failure
> - just like assert does, but the message in the AssertError is far more
> informative. While improvements can be made to how unit tests work in D,
> I believe that that should be addressed by actually making those
> improvements to the core language as opposed to using a module in Phobos
> to change things. You shouldn't _need_ std.unittests to write unit
> testing code.
> 
> std.unittests is intended to help you write more informative unit test
> code and save you from writing some of the boilerplate code in unit
> tests, but it is _not_ intended to fundamentally alter how unit tests in
> D function.
> 
> So, please have a look at the code. I've made changes according to
> previous suggestions, and I think that the result is quite a bit better
> than my original proposal. If all goes well, perhaps Andrei will put it
> up for vote soon, and we can actually have it in Phobos.
> 
> - Jonathan M Davis

Sorry for not commenting on earlier iterations of this module.  For the 
most part, I think it looks pretty good, and I also think it will be 
useful.  Often, I find myself writing stuff like

  assert (someVar == someVal,
    text("Wrong value for someVar: ", someVar));

and assertEqual() will be nice to have for those cases. :)  I just have 
some minor comments.

1. I think assertExThrown() and assertExNotThrown() should be named 
assertThrown() and assertNotThrown(), because they can intercept any 
subclass of Throwable, not just Exception, and because you rarely throw 
anything else, so it seems redundant.

2. I think the name getMsg() is too non-specific.  I'd prefer if it was 
renamed to throwableMsg(), thrownMsg(), or something similar.  The 
function should also be moved upwards a bit so its documentation follows 
that of the assert*Thrown() functions.  Then, the various functions will 
be nicely grouped in the documentation -- all the exception handling 
tests come first, followed by the value tests.

-Lars