Re: [boost] What Should we do About Boost.Test?

Subject: Re: [boost] What Should we do About Boost.Test?
From: Alexander Lamaison (awl03_at_[hidden])
Date: 2012-10-06 12:32:53

Dave Abrahams <dave_at_[hidden]> writes:

> on Fri Oct 05 2012, Andrey Semashev <andrey.semashev-AT-gmail.com> wrote:
>
>> On Thursday 04 October 2012 13:20:00 Dave Abrahams wrote:
>>> 
>>> The question remains: "how do I learn/teach this library?"  If I can't
>>> answer those questions, I also can't answer the question
>>> 
>>>        How do I use this library?
>>> 
>>> I don't understand how other people have arrived at answers for
>>> themselves.
>>
>> [snip]
>>
>>> Look, I teach classes on Boost.  If Boost.Test is not learnable and
>>> teachable, I have to tell my students to stay away from it.  That's
>>> embarrassing for me, and bad for Boost.
>>
>> Although I'm not teaching students, I can understand the difficulties
>> you're talking about. However, you have to admit by the answers in
>> this thread that many people managed to learn the library and use it
>> extensively.
>
> Yes.  How did they do it?

I'm a bit puzzled why you're having problems.  The info is all there in
the docs.  My theory is that you've gotten lost amongst the bloat; the
docs certainly don't cut to the chase and go on about execution
monitors, usage variants, test runners and manual test registration when
all you want to know is how to write a test case.

So, cutting to the chase, here is how you write a test case:
http://www.boost.org/doc/libs/1_51_0/libs/test/doc/html/utf/user-guide/test-organization/auto-nullary-test-case.html.
So simple.

Here is a more advanced test case with a test fixture:
http://www.boost.org/doc/libs/1_51_0/libs/test/doc/html/utf/user-guide/fixture/test-suite-shared.html

And here are the tests you use in your test cases:
http://www.boost.org/doc/libs/1_51_0/libs/test/doc/html/utf/testing-tools/reference.html

IMHO, the docs should start with these and the rest should be removed or
moved later.  Almost all the docs should stick to the automatic
registration versions as describing the manual versions first gives the
misleading impression that you might want to use them.  You don't.  Or
at least I never have in all the years I've been Boost.Testing.

Also, a doc bug report: the Unary Function link navigates to the wrong
page on this page:
http://www.boost.org/doc/libs/1_51_0/libs/test/doc/html/utf/user-guide/test-organization.html

Alex