NAME¶
Test::ClassAPI - Provides basic first-pass API testing for large class trees
DESCRIPTION¶
For many APIs with large numbers of classes, it can be very useful to be able to
do a quick once-over to make sure that classes, methods, and inheritance is
correct, before doing more comprehensive testing. This module aims to provide
such a capability.
Using Test::ClassAPI¶
Test::ClassAPI is used with a fairly standard looking test script, with the API
description contained in a __DATA__ section at the end of the script.
#!/usr/bin/perl
# Test the API for Foo::Bar
use strict;
use Test::More 'tests' => 123; # Optional
use Test::ClassAPI;
# Load the API to test
use Foo::Bar;
# Execute the tests
Test::ClassAPI->execute;
__DATA__
Foo::Bar::Thing=interface
Foo::Bar::Object=abstract
Foo::Bar::Planet=class
[Foo::Bar::Thing]
foo=method
[Foo::Bar::Object]
bar=method
whatsit=method
[Foo::Bar::Planet]
Foo::Bar::Object=isa
Foo::Bar::Thing=isa
blow_up=method
freeze=method
thaw=method
Looking at the test script, the code itself is fairly simple. We first load
Test::More and Test::ClassAPI. The loading and specification of a test plan is
optional, Test::ClassAPI will provide a plan automatically if needed.
This is followed by a compulsory __DATA__ section, containing the API
description. This description is in provided in the general form of a Windows
style .ini file and is structured as follows.
Class Manifest¶
At the beginning of the file, in the root section of the config file, is a list
of entries where the key represents a class name, and the value is one of
either 'class', 'abstract', or 'interface'.
The 'class' entry indicates a fully fledged class. That is, the class is tested
to ensure it has been loaded, and the existance of every method listed in the
section ( and its superclasses ) is tested for.
The 'abstract' entry indicates an abstract class, one which is part of our class
tree, and needs to exist, but is never instantiated directly, and thus does
not have to itself implement all of the methods listed for it. Generally, many
individual 'class' entries will inherit from an 'abstract', and thus a method
listed in the abstract's section will be tested for in all the subclasses of
it.
The 'interface' entry indicates an external interface that is not part of our
class tree, but is inherited from by one or more of our classes, and thus the
methods listed in the interface's section are tested for in all the classes
that inherit from it. For example, if a class inherits from, and implements,
the File::Handle interface, a "File::Handle=interface" entry could
be added, with the "[File::Handle]" section listing all the methods
in File::Handle that our class tree actually cares about. No tests, for class
or method existance, are done on the interface itself.
Class Sections¶
Every class listed in the class manifest
MUST have an individual section,
indicated by "[Class::Name]" and containing a set of entries where
the key is the name of something to test, and the value is the type of test
for it.
The 'isa' test checks inheritance, to make sure that the class the section is
for is (by some path) a sub-class of something else. This does not have to be
an immediate sub-class. Any class refered to (recursively) in a 'isa' test
will have its 'method' test entries applied to the class as well.
The 'method' test is a simple method existance test, using
"UNIVERSAL::can" to make sure that the method exists in the class.
METHODS¶
execute¶
The "Test::ClassAPI" has a single method, "execute" which is
used to start the testing process. It accepts a single option argument,
'complete', which indicates to the testing process that the API listed should
be considered a complete list of the entire API. This enables an additional
test for each class to ensure that
every public method in the class is
detailed in the API description, and that nothing has been "missed".
SUPPORT¶
Bugs should be submitted via the CPAN bug tracker, located at
<
http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-ClassAPI>
For other issues, or commercial enhancement or support, contact the author.
AUTHOR¶
Adam Kennedy <adamk@cpan.org>
COPYRIGHT¶
Copyright 2002 - 2009 Adam Kennedy.
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.
The full text of the license can be found in the LICENSE file included with this
module.