Boost.Test Documentation
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.<boost-test%20at%20emailaccount%20dot%20com%20%28please%20unobscure%29> 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.
On 8/1/07, James Hamlin <jfhamlin@gmail.com> 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
on Tue Jul 31 2007, "James Hamlin" <jfhamlin-AT-gmail.com> 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
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
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
"James Hamlin" <jfhamlin@gmail.com> 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" <rogeeff@gmail.com> wrote in message news:f8t445$3ho$1@sea.gmane.org...
"James Hamlin" <jfhamlin@gmail.com> 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
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 <rogeeff@gmail.com> wrote:
"Gennadiy Rozental" <rogeeff@gmail.com> wrote in message news:f8t445$3ho$1@sea.gmane.org...
"James Hamlin" <jfhamlin@gmail.com> 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
"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
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 <rogeeff@gmail.com> 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
Did you take a look on tutorials? They are somewhere on top and intended as getting started guides. Gennadiy "Richard Dingwall" <rdingwall@gmail.com> 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 <rogeeff@gmail.com > 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
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
"gast128" <gast128@hotmail.com> 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
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 <boost/test/unit_test.hpp> #include <boost/bind.hpp> 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
"Yann Golanski" <yann@kierun.org> 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 <boost/test/unit_test.hpp> #include <boost/bind.hpp> 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
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
-----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" <yann@kierun.org> 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. ***
"Uwe Schuster" <Uwe.Schuster@woodward.com> 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" <yann@kierun.org> 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.
participants (8)
-
David Abrahams -
gast128 -
Gennadiy Rozental -
James Hamlin -
Jens Seidel -
Richard Dingwall -
Uwe Schuster -
Yann Golanski