Re: [Cppunit-devel] include directory clean-up

[Baptiste L. <bl...@cl...>]

Well, onward for the answer to the next part of the mail...
----- Original Message -----
From: "Steve M. Robbins" <ste...@vi...>
To: <cpp...@li...>
Sent: Thursday, June 14, 2001 5:16 PM
Subject: Re: [Cppunit-devel] include directory clean-up


> On Thu, Jun 14, 2001 at 04:39:41PM +0200, Baptiste Lepilleur wrote:
> I'd like to start documenting the classes better.  I don't understand
> it well enough, yet, though.  If we can get some discussion going
> here, I will add the documentation strings.  I expect this process
> will clarify class relationships and groupings will emerge,
> facilitating directory/namespace structuring.
   OK. I'd rather not write doc because my written english is quite strange,
and I fear I would put more confusion in the mind of the user than anything
else.

> For example, we can start with the core classes such as Test,
> TestCase, TestCaller, TestSuite.  The latter three are each a subclass
> of Test, which is pure virtual.  Is it fair to say, then, that
> Test is an "interface" class?  What are the intended semantics
> of its methods: run(), countTestCases(), toString() and getName()?
> We just had some questions on whether the latter two should be
> merged.  I don't think a conclusion was reached.

Well, let's get started. I'll give you my view on this classes.

*** Test: provides a way to run a specified test and tracks the result of
the run.
void run (TestResult *result):
  - Run the test.
  - The test should report each stage of its run to the TestResult
(startTest/addError/addFailure/endTest).
  - Should never ever throw an exception except for the case of fatal errors
(can't allocate memory to add the failure to TestResult...)

int countTestCases () const:
  - predict the number of times the TestCase::runTest() method will be
called if this test is run(). Returning a value lower than 1 doesn't make
sense (what would be the point of running the test if no unit test is run?).

std::string toString () const:
  - My best guess would be describes the test. In Java, and Michael
Feather's original version there is no getName() method, and the toString()
has the role of the getName() method.

std::string getName () const:
  - Identify the test. The returned name should as unique as possible to
identify the test (that why the TestCase name is included by the
TestSuiteBuilder). TestRunners rely on that name to run a specified test (or
suite). Having a name that identify the test without ambiguity help reading
the failures report (you don't have to bother with the filename).

Conclusion: ditch either toString() or getName(). I find that getName() as a
more intention revealing name ;-)

*** TestCase: provides a convenient way to write test with a
setup/test/tearoff stage. Provides track of the test run to the TestResult.

void run(TestResult *result):
  - provides TestResult with progress of the test run.
  - run the actual test with the runTest() method which should be overrided.
Provides runTest() initialization with a setUp() method and clean up
tearOff() method which should be overrided to create/destroy fixtures (note
that creating fixture in the class constructor does not make it possible to
run the test more than 1 time if the fixture is modified by the test).
  - "translate" exception thrown by either setUp(), runTest() or tearOff()
into failure or error report to the TestResult. Exception with
CppUnit::Exception as a base class are "failure" (a failed condition, such
as a failed assertion or an uncaught excepted exception), report to the
TestResult with addFailure() other exception are "error", reported with
addError().

TestResult  *run():
  - a convenient method to run a test in the wild ? It's not used by the
framework itself. Only use I can see is if you want to run a test case
without a test runner.

TestResult *defaultResult():
  - used by the previous run() method. Should be overrided to use a test
result other than TestResult. Can't think of a use for those two...

int countTestCases() const:
  - always returns 1 since run() call runTest() only once. Should not be
overrided.

std::string getName() const (or toString() depending on the survivor ;-) ):
  - identifiy the test. Among all the classes this is the most important
implementation of this method since it is the one use by the TestResult (and
TestRunner) to indicate which test as failed. Should be unique, but it not
always possible (template test case on platform without RTTI support :-( ).

void setUp():
  - called by run() before calling runTest(). Should be override to
initialize the test. If an exception is throw, then runTest() and tearDown()
won't be called and an "error" is reported for that test.

void runTest():
  - you should override this method to do the actual test. Test failure
should be reported by throwing a exception derived from CppUnit::Exception.
This is the place where you use CPPUNIT_ASSERTs macros.

void tearDown():
  - you should override this method to clean up after runTest() is called.
This method is always called if setUp() has been called successfuly (no
exception were thrown).

That about it for those two nasties.

More about the other another day (note that test caller is a specialization
of TestCase).
I'll try to do a short synops when I'll be done with each of classes.

Good night,
Baptiste.

---
Baptiste Lepilleur <gai...@fr...>   http://gaiacrtn.free.fr/index.html
Author of The Text Reformatter, a tool for fanfiction readers and writers.
Language: English, French (Well, I'm French).