Boost.Test Documentation

newer
Passing user defined visitor for...

James Hamlin

31 Jul 2007 31 Jul '07

7:46 p.m.

Hi, I've begun using Boost.Test to construct test suites for a project, and it looks like it does a great job and is full of nice features (I really like the auto unit tests). But I have a big complaint: the documentation is pretty poor. I had a hard time getting a simple example off the ground, because it wasn't clear that I had to link to parts of the library. This was a surprise since most of Boost is templated and so is available entirely through the headers. I had to dig a bit to find the comment about the header that includes the main() code and other concrete functions. In addition, many of the examples are missing, and some of those that are available require the linking I mentioned but fail to note this, adding to my initial confusion. Lastly, the English grammar is very rough in parts, and while I understand that English may not be the primary language of the author, it can be a big hurdle to get started using the library when one has to grapple with the documentation to understand the intentions of the author. I don't mean to rant - the library is great, and I've already found it useful - but I'd love to get more out of it, and clean, clear, and thorough documentation will get me and others started with much less head scratching and frustration. Sincerely, James Hamlin Postscript: This is Boost-users, but I assume Gennadiy Rozental or somebody else with the knowledge and ability to update the documentation will see this message.

Attachments:

attachment.html (text/html — 1.6 KB)

Show replies by date

Richard Dingwall

2 Aug 2 Aug

5:02 a.m.

On 8/1/07, James Hamlin wrote:

...

Hi,

I've begun using Boost.Test to construct test suites for a project, and it looks like it does a great job and is full of nice features (I really like the auto unit tests). But I have a big complaint: the documentation is pretty poor. I had a hard time getting a simple example off the ground, because it wasn't clear that I had to link to parts of the library. This was a surprise since most of Boost is templated and so is available entirely through the headers. I had to dig a bit to find the comment about the header that includes the main() code and other concrete functions. In addition, many of the examples are missing, and some of those that are available require the linking I mentioned but fail to note this, adding to my initial confusion. Lastly, the English grammar is very rough in parts, and while I understand that English may not be the primary language of the author, it can be a big hurdle to get started using the library when one has to grapple with the documentation to understand the intentions of the author. I don't mean to rant - the library is great, and I've already found it useful - but I'd love to get more out of it, and clean, clear, and thorough documentation will get me and others started with much less head scratching and frustration.

I have also found problems with Boost.Test's documentation. For example, 5 out of the 8 complete examples ( http://boost.org/libs/test/doc/examples/index.html) are dead links, and there are serious spelling mistakes in the NYE resolution example (( http://boost.org/libs/test/doc/tutorials/new_year_resolution.html). BOOST_AUTO_EST_CASE will never compile; it should be BOOST_AUTO_TEST_CASE. This had me scratching my head for a while, I thought it might've been short for 'establish' which made sense at the time... I had to hunt through a few headers to find the declaration before I could get my tests working. Once I got past this though, it was all good :) Richard Sincerely,

...

James Hamlin

Postscript: This is Boost-users, but I assume Gennadiy Rozental or somebody else with the knowledge and ability to update the documentation will see this message.

_______________________________________________ Boost-users mailing list Boost-users@lists.boost.org http://lists.boost.org/mailman/listinfo.cgi/boost-users

David Abrahams

2:12 p.m.

on Tue Jul 31 2007, "James Hamlin" wrote:

...

I've begun using Boost.Test to construct test suites for a project, and it looks like it does a great job and is full of nice features (I really like the auto unit tests). But I have a big complaint: the documentation is pretty poor. I had a hard time getting a simple example off the ground, because it wasn't clear that I had to link to parts of the library. This was a surprise since most of Boost is templated and so is available entirely through the headers.

http://boost.org/more/getting_started indicates that you can use the library in "header-only" mode. I don't know any of the details though. -- Dave Abrahams Boost Consulting http://www.boost-consulting.com The Astoria Seminar ==> http://www.astoriaseminar.com

James Hamlin

2:31 p.m.

...

http://boost.org/more/getting_started indicates that you can use the library in "header-only" mode. I don't know any of the details though.

Right. I found the header I was looking for. The issue is that the documentation doesn't make a lot of things clear. For example, even after finding a mention of the header and it's purpose, I struggled for a bit before discovering that I had to define BOOST_AUTO_TEST_MAIN before #including header. In fact, I found this out through a resource other than Boost's documentation for Boost.Test. While the library certainly appears to live up to the standard of quality I've come to expect from Boost, the documentation does not. Sincerely, James Hamlin --

...

Dave Abrahams Boost Consulting http://www.boost-consulting.com

The Astoria Seminar ==> http://www.astoriaseminar.com

_______________________________________________ Boost-users mailing list Boost-users@lists.boost.org http://lists.boost.org/mailman/listinfo.cgi/boost-users

Jens Seidel

4:26 p.m.

On Thu, Aug 02, 2007 at 10:31:29AM -0400, James Hamlin wrote:

...

http://boost.org/more/getting_started indicates that you can use the library in "header-only" mode. I don't know any of the details though.

Right. I found the header I was looking for. The issue is that the documentation doesn't make a lot of things clear. For example, even after finding a mention of the header and it's purpose, I struggled for a bit before discovering that I had to define BOOST_AUTO_TEST_MAIN before #including header. In fact, I found this out through a resource other than Boost's documentation for Boost.Test. While the library certainly appears to live up to the standard of quality I've come to expect from Boost, the documentation does not.

Strange, I use Boost.Test a lot but did not used BOOST_AUTO_TEST_MAIN in the past. Will dig into the docu ... James, please fix all these (maybe not so little) issues after obtaining the source from subversion (just search for the bogus strings and fix these) and send a diff. I will do so as well once I spot errors in it. Without sending patches the quality will not improve ... Thanks, Jens

Gennadiy Rozental

5:26 p.m.

...

"James Hamlin" wrote in message news:dd89626a0707311246h7a117da8kd9c392b3b2cb9f2d@mail.gmail.com... Hi,

I've begun using Boost.Test to construct test suites for a project, and it looks like it does a great job and is full of nice features (I really like the auto unit tests). >But I have a big complaint: the documentation is pretty poor.

Just a bit more paitient guys ;)) I should be able to publish an alpha version of new completely reworked BoostBook Based documnetation for the Boost.Test in a couple days. I will really appritiate and read through it and let me know if is there any problems (from any standpoint: english, content, missing link, incorrect link etc) Regards Gennadiy

Gennadiy Rozental

5:44 p.m.

"Gennadiy Rozental" wrote in message news:f8t445$3ho$1@sea.gmane.org...

...

...
"James Hamlin" wrote in message news:dd89626a0707311246h7a117da8kd9c392b3b2cb9f2d@mail.gmail.com... Hi,

I've begun using Boost.Test to construct test suites for a project, and it looks like it does a great job and is full of nice features (I really like the auto unit tests). >But I have a big complaint: the documentation is pretty poor.

Just a bit more paitient guys ;))

I should be able to publish an alpha version of new completely reworked BoostBook Based documnetation for the Boost.Test in a couple days. I will really appritiate read through it and let me know if is there any

I meant to say: "If you" here ^

...

problems (from any standpoint: english, content, missing link, incorrect link etc)

Regards

Gennadiy

James Hamlin

5:48 p.m.

I can be patient :). I just wanted to air my grievances and hope that someone who knows what they're doing would clean things up. I'm glad it's already being worked on. I'd be happy to comment on the alpha version whenever it's published. I couldn't say much about correctness of content, of course, but I can check grammar, links, and clarity. Thanks! James Hamlin On 8/2/07, Gennadiy Rozental wrote:

...

"Gennadiy Rozental" wrote in message news:f8t445$3ho$1@sea.gmane.org...

...
...
"James Hamlin" wrote in message news:dd89626a0707311246h7a117da8kd9c392b3b2cb9f2d@mail.gmail.com... Hi,

I've begun using Boost.Test to construct test suites for a project, and

...
...
looks like it does a great job and is full of nice features (I really

...
...
the auto unit tests). >But I have a big complaint: the documentation is pretty poor.

Just a bit more paitient guys ;))

I should be able to publish an alpha version of new completely reworked BoostBook Based documnetation for the Boost.Test in a couple days. I will really appritiate read through it and let me know if is

it like there

...
any

I meant to say: "If you" here ^

...
problems (from any standpoint: english, content, missing link, incorrect link etc)

Regards

Gennadiy

_______________________________________________ Boost-users mailing list Boost-users@lists.boost.org http://lists.boost.org/mailman/listinfo.cgi/boost-users

Gennadiy Rozental

14 Aug 14 Aug

4:30 a.m.

...

"James Hamlin" wrote in message I'd be happy to comment on the alpha version whenever it's published. I couldn't say much about correctness of content, of course, but I can check grammar, links, and clarity.

Alpha version is here: http://www.patmedia.net/~rogeeff/html/index.html Gennadiy

Richard Dingwall

5:01 a.m.

It still seems a little unfriendly - there is plenty of pages of documentation on the framework itself (registration, test case templates etc) but as an impatient new user, I need to dive quite deep to find AUTO* stuff. Would it be possible to add a "quick guide" section showing how to knock up some test modules for a handful of simple classes with AUTO_TEST_CASE, and tie them together into an executable with AUTO_TEST_MAIN? I believe this is all most users want. Richard P.S. the "BOOST_AUTO_EST_CASE" error is still present on this page: http://www.patmedia.net/~rogeeff/html/tutorials/new-year-resolution.html On 8/14/07, Gennadiy Rozental wrote:

...

...
"James Hamlin" wrote in message I'd be happy to comment on the alpha version whenever it's published. I couldn't say much about correctness of content, of course, but I can check grammar, links, and clarity.

Alpha version is here:

http://www.patmedia.net/~rogeeff/html/index.html

Gennadiy

_______________________________________________ Boost-users mailing list Boost-users@lists.boost.org http://lists.boost.org/mailman/listinfo.cgi/boost-users

Gennadiy Rozental

5:33 a.m.

Did you take a look on tutorials? They are somewhere on top and intended as getting started guides. Gennadiy "Richard Dingwall" wrote in message news:aedf0bab0708132201o72599291sb00fdc21a0332d8a@mail.gmail.com... It still seems a little unfriendly - there is plenty of pages of documentation on the framework itself (registration, test case templates etc) but as an impatient new user, I need to dive quite deep to find AUTO* stuff. Would it be possible to add a "quick guide" section showing how to knock up some test modules for a handful of simple classes with AUTO_TEST_CASE, and tie them together into an executable with AUTO_TEST_MAIN? I believe this is all most users want. Richard P.S. the "BOOST_AUTO_EST_CASE" error is still present on this page: http://www.patmedia.net/~rogeeff/html/tutorials/new-year-resolution.html On 8/14/07, Gennadiy Rozental wrote: > "James Hamlin" < jfhamlin@gmail.com> wrote in message > I'd be happy to comment on the alpha version whenever it's published. I > couldn't say much about correctness of content, of course, but I can check >grammar, links, and clarity. Alpha version is here: http://www.patmedia.net/~rogeeff/html/index.html Gennadiy _______________________________________________ Boost-users mailing list Boost-users@lists.boost.org http://lists.boost.org/mailman/listinfo.cgi/boost-users ------------------------------------------------------------------------------ _______________________________________________ Boost-users mailing list Boost-users@lists.boost.org http://lists.boost.org/mailman/listinfo.cgi/boost-users

gast128

3 Aug 3 Aug

9:38 p.m.

At our company we had written quite a few test cases using the old test library, which seems to be broken using the new DLL infra structure instead of the old static libraries. So after some hours (and frustration) I got it finally working again. Good documentation could really have helped here. In case others experience the same problem, here is a workaround. Define your own main function and intialise the libraries there, e.g.: bool Hack() { char** pp = NULL; boost::unit_test::framework::master_test_suite().p_name.value = "test"; boost::unit_test::framework::master_test_suite().add( init_unit_test_suite (0, pp) ); return true; } int main(int argc, char* argv[]) { //Note: this is just a q&&d way to get the 1.33 //tests compilable with the 1.34 UTF. return boost::unit_test::unit_test_main( &Hack, argc, argv ); } This is not very impressive, but if you are not an expert in the test library and just a dumb user, it can really take a while. Wkr, me

Gennadiy Rozental

14 Aug 14 Aug

4:38 a.m.

"gast128" wrote in message news:loom.20070803T232633-408@post.gmane.org...

...

At our company we had written quite a few test cases using the old test library, which seems to be broken using the new DLL infra structure instead of the old static libraries.

So after some hours (and frustration) I got it finally working again. Good documentation could really have helped here. In case others experience the same problem, here is a workaround.

Please read docs at: http://www.patmedia.net/~rogeeff/html/utf/compilation.html and let me know if you still not able to build your test modules successfully. Gennadiy

Yann Golanski

8:44 a.m.

Quoth Gennadiy Rozental on Tue, Aug 14, 2007 at 00:38:02 -0400

...

Please read docs at:

http://www.patmedia.net/~rogeeff/html/utf/compilation.html

and let me know if you still not able to build your test modules successfully.

Many thanks indeed. I have managed to make a test module from the old documentation -- after way too much effort. The new one is a massive improvement. However, there are sections that are not filled in and some spelling mistakes in the text and sometimes more importantly in the options. For example: http://www.patmedia.net/~rogeeff/html/utf/user-guide/runtime-config/referenc... In "report_level", the levels are indicated as no, confirm, short and detaled -- the latter should be details. I am still unclear about the compile flags. I somehow cannot get ride of main in my test code. What would be really useful is an example of use with Makefile/bjam file/Studio files. I can help if you wanted on the *nix side. Here is the code, with Makefile following... ==== c++ code: working ==== #define BOOST_TEST_DYN_LINK //#define BOOST_TEST_MAIN #include #include using namespace boost::unit_test; //! Test assertion, will always return true. void free_test_function( int i, int j ) { BOOST_CHECK( true ); } //! Main test case. bool init_function( ) { framework::master_test_suite().p_name.value = "unit test"; framework::master_test_suite().add(BOOST_TEST_CASE(boost::bind(&free_test_function, 1, 1 ))); return true; } // TODO: How do I get ride of main???... int main( int argc, char* argv[] ) { return ::boost::unit_test::unit_test_main( &init_function, argc, argv ); } ==== Makefile ==== FILES=$(shell find -maxdepth 1 -name '*.cc' -or -name '*.cpp' -or -name '*.h') SRCS=$(shell find -maxdepth 1 -name '*.cc' -or -name '*.cpp') \ OBJS=$(SRCS:.cc=.o) EXE=unit_test CXX=g++ SYSFLAG= INCLUDES=-I/usr/local/include/boost -I/usr/local/include CXXFLAGS=$(SYSFLAG) $(INCLUDES) -Wall -ansi BOOSTFLAGS=-L/usr/local/lib -lboost_unit_test_framework-gcc34-mt-d LDFLAGS=$(BOOSTFLAGS) -llog4cplus all : main main: buildfiles.d $(OBJS) $(CXX) -o $(EXE) $(LDFLAGS) $(CXXFLAGS) $(OBJS) buildfiles.d: $(SRCS) gcc -MM $(SRCS) > buildfiles.d -include buildfiles.d -- yann@kierun.org -= H+ =- www.kierun.org PGP: 009D 7287 C4A7 FD4F 1680 06E4 F751 7006 9DE2 6318

Gennadiy Rozental

15 Aug 15 Aug

3:39 a.m.

"Yann Golanski" wrote in message news:20070814084453.GB60576@kierun.org...

...

For example: http://www.patmedia.net/~rogeeff/html/utf/user-guide/runtime-config/referenc... In "report_level", the levels are indicated as no, confirm, short and detaled -- the latter should be details.

Actually it's "detailed". Fixed anyway

...

I am still unclear about the compile flags. I somehow cannot get ride of main in my test code. What would be really useful is an example of use with Makefile/bjam file/Studio files. I can help if you wanted on the *nix side.

Here is the code, with Makefile following...

==== c++ code: working ====

#define BOOST_TEST_DYN_LINK //#define BOOST_TEST_MAIN

#include #include using namespace boost::unit_test;

//! Test assertion, will always return true. void free_test_function( int i, int j ) { BOOST_CHECK( true ); }

//! Main test case. bool init_function( ) { framework::master_test_suite().p_name.value = "unit test"; framework::master_test_suite().add(BOOST_TEST_CASE(boost::bind> (&free_test_function, 1, 1 ))); return true; }

// TODO: How do I get ride of main???... int main( int argc, char* argv[] ) { return ::boost::unit_test::unit_test_main( &init_function, argc, argv ); }

You can't get rid (;)) of he main function in above setup. If you are desire to define init function you will have to define main() s well. The only way to avoid defining main() is to avoid definingthem both. Use auto registration: BOOST_AUTO_TEST_CASE( param_test ) { free_test_function( 1, 1 ); } Gennadiy

Yann Golanski

7:58 a.m.

Quoth Gennadiy Rozental on Tue, Aug 14, 2007 at 23:39:15 -0400

...

...
In "report_level", the levels are indicated as no, confirm, short and detaled -- the latter should be details.

Actually it's "detailed". Fixed anyway

*grins* Indeed it is.

...

The only way to avoid defining main() is to avoid definingthem both. Use auto registration:

BOOST_AUTO_TEST_CASE( param_test ) { free_test_function( 1, 1 ); }

Okay, that makes more sense. Thanks. -- yann@kierun.org -= H+ =- www.kierun.org PGP: 009D 7287 C4A7 FD4F 1680 06E4 F751 7006 9DE2 6318

Uwe Schuster

9:21 a.m.

...

-----Original Message----- From: boost-users-bounces@lists.boost.org [mailto:boost-users-bounces@lists.boost.org]On Behalf Of Gennadiy Rozental Sent: Wednesday, August 15, 2007 5:39 AM To: boost-users@lists.boost.org Subject: Re: [Boost-users] Boost.Test Documentation

...

"Yann Golanski" wrote in message news:20070814084453.GB60576@kierun.org...

...
For example:

http://www.patmedia.net/~rogeeff/html/utf/user-guide/runtime-config/referenc...

...
In "report_level", the levels are indicated as no, confirm, short and detaled -- the latter should be details.

Actually it's "detailed". Fixed anyway

On this page (report_level) the "Command line argument name" seems to be wrong. Also on the "detect_memory_leak" page. Why the list of parameters on the "Runtime parameters reference page" consists of the command line argument names? Shouldn't it be the full names instead? Uwe. *** The information in this e-mail is confidential and intended solely for the individual or entity to whom it is addressed. If you have received this e-mail in error please notify the sender by return e-mail delete this e-mail and refrain from any disclosure or action based on the information. ***

Gennadiy Rozental

17 Aug 17 Aug

4:31 a.m.

"Uwe Schuster" wrote in message news:BFC1D03DDCEEE34D94D6DBCAF0C46A394CA0F6@KEMPMAIL.woodward.com...

...

...
-----Original Message----- From: boost-users-bounces@lists.boost.org [mailto:boost-users-bounces@lists.boost.org]On Behalf Of Gennadiy Rozental Sent: Wednesday, August 15, 2007 5:39 AM To: boost-users@lists.boost.org Subject: Re: [Boost-users] Boost.Test Documentation

...
"Yann Golanski" wrote in message news:20070814084453.GB60576@kierun.org...

...
For example:

http://www.patmedia.net/~rogeeff/html/utf/user-guide/runtime-config/referenc...

...
In "report_level", the levels are indicated as no, confirm, short and detaled -- the latter should be details.

Actually it's "detailed". Fixed anyway

On this page (report_level) the "Command line argument name" seems to be wrong. Also on the "detect_memory_leak" page.

Fixed.

...

Why the list of parameters on the "Runtime parameters reference page" consists of the command line argument names? Shouldn't it be the full names instead?

These are their names. CLA just happend to coinside with them.

6399

Age (days ago)

6416

Last active (days ago)

List overview

Download

17 comments

8 participants

participants (8)

David Abrahams
gast128
Gennadiy Rozental
James Hamlin
Jens Seidel
Richard Dingwall
Uwe Schuster
Yann Golanski