[merge] doc how to use new test features

[Andrew Bennetts]

John Arbash Meinel wrote:
> Martin Pool wrote:
> > On 5/2/07, Aaron Bentley <aaron.bentley at utoronto.ca> wrote:
> >> Martin Pool wrote:
> >> > silently return - this test just doesn't make sense in this case
> >>
> >> I don't like silent returns at all.  The test should not report that it
> >> passed unless it ran to completion.
> > 
> > Yes, that was my point in my later post -- and that this is commonly
> > how TestSkipped is currently used.  I don't mind if we have a
> > different status meaning "test not implemented" or "test prerequisite
> > not implemented yet."
> 
> Well, one specific example is "test_put()" for readonly transports.
> There are several put tests, and *one* of them should test that the
> right error is raised, but the rest of the test isn't worth doing.
> 
> It seems like a good case for "silent return", because readonly
> transports act differently for something like put().
> 
> 
> And what about Branch format 0.0.4. We don't support creating these from
> scratch (and don't really plan on ever allowing it).

I also don't like silent returns.

I do agree there's a valid reason to be able to say "this test does not apply"
for cases such as the ones John just listed, but I think "return" is a terrible
way to spell it.  I would much rather something like a TestNotApplicable
exception, so that:

  * it is explicit why we're exiting the test early;
  * we can use it inside helper functions, not just the test_ method; and
  * so that we can update the test reporter to report how many of our tests
    are actually non-tests.

-Andrew.