"Weaver, Quinn BGI SF" <[EMAIL PROTECTED]> writes:
> I recently downloaded Test::Unit from CPAN for use in a project at work.
> I've used the object-oriented API to implement the first draft of a test
> system for a new class library. It works, but I'm a bit confused as to
> which parts of the API are intended to be public and which are intended to
> remain private. In particular, I've done a lot of processing of TestResults
> by hand, since I need a user interface different from that of the
> TestRunner. Naturally, I want to make sure I'm coding to the public API, so
> my code isn't broken by changes in future versions. In various revisions of
> my code, I've directly used the following methods that may or may not be
> intended as public:
In general, at the current time, there is no hard-and-fast "rule"
which methods are public and which not. The only thing I can say is
which methods seem "stable" to me based on the discussions on the
sourceforge mailing list.
To give you some impression, I will label the methods as "Stable",
meaning nobody wanted to change it yet, "Discussion", meaning somebody
wanted to change something, "Questionable", meaning I would not rely
on this feature being available in the time to come. That is the best
I can give you at the current time.
>
> Test::Unit::TestResult::run_count
> Test::Unit::TestResult::failure_count
> Test::Unit::TestResult::error_count
> Test::Unit::TestResult::failures
> Test::Unit::TestResult::errors
Stable - access point for fundamental properties of a TestResult object
> Test::Unit::TestFailure::to_string
Discussion - somebody wanted to change to_string() to overloaded "" operator
> Test::Unit::TestFailure::thrown_exception
Stable - access point for fundamental property of a TestFailure object
> Test::Unit::ExceptionFailure::get_message
> Test::Unit::ExceptionError::get_message
Stable - access point for fundamental property of a Exception objects
(this method is inherited from Test::Unit::Exception)
> Test::Unit::TestCase::name
Stable - can't see why someone would want to change that
> Test::Unit::TestCase::to_string
Discussion - somebody wanted to change to_string() to overloaded "" operator
>
> The only parts of the API I'm sure are public are those used in the
> examples:
>
> Test::Unit::TestSetup::new (TestSuite)
> Test::Unit::TestRunner::new
> Test::Unit::TestRunner::start
> Test::Unit::TestResult::new
> Test::Unit::TestSuite::new
> Test::Unit::TestSuite::add_test (TestSuite)
> Test::Unit::TestSuite::run
You are right, these are "Stable" by virtue of the examples.
> In general, I've noticed there are an awful lot of entry points through
> which one can begin running a set of tests. Depending on how much of the
> test process the client wants to control, any one of them could be useful.
> Which of these are intended to be part of the public API?
>
> TestRunner::start
> TestRunner::do_run (TestSetup)
I'd say do_run is not public. There are start, run, and run_and_wait.
These are intended to be public, and they all use do_run as the
primitive.
> TestSetup::run (TestResult)
Not public, I'd say. TestSetup is intended for overriding set_up()
and tear_down(), not as an entry point.
> TestSuite::run (TestResult)
Public, IMHO. Entry point.
> TestCase::run (TestResult)
Public, too. Unusual entry point, I think, but possible.
> TestResult::run (TestCase)
Not public, IMHO, since a TestResult should be passed to a Test object
to be run and collect the results.
>
> As you can see, I had a lot of trouble figuring out how to use the code.
Sorry for that. Somehow nobody of the developer group wanted to write
more documentation. Maybe you can contribute some now?
> After reading
> the man pages, I ended up running the example code (in particular, perl
> TestRunner.pl fail_example) through the debugger to find out how it worked!
Aarrgh. OK, that is really not how it should be. Sorry again.
> I find the overall design of Test::Unit very appealing, but I think it could
> benefit greatly from more detailed documentation. Some sense of where to
> start--e.g. a tutorial about which classes to use in what order--would be
> very helpful!
Could you give an outline of what you would expect from such a
tutorial? This could serve as a starting point for better docs.
> So would a more explicit division between the public and the
> internal APIs (perhaps by a mechanism as simple as using leading underscores
> for private method names).
There's more to that than a simple distinction between "public" and
"internal", I think. What is needed is documentation on what should
be used for what purpose, and more examples of realistic usage.
>
> Anyway, please enlighten me about the public API. In the meantime, thanks
> for the code! It's certainly proven useful to this project. :)
I hope the comments above are somehow useful to you.
Maybe you can contribute parts of your effort (documentation, code,
examples, custom TestRunners, ...)?
Note that I have copied this message on to the mailing list at sourceforge.
Cheers,
Christian Lemburg
_______________________________________________
Perlunit-devel mailing list
[EMAIL PROTECTED]
http://lists.sourceforge.net/lists/listinfo/perlunit-devel
