1Test::ClassAPI(3)     User Contributed Perl Documentation    Test::ClassAPI(3)
2
3
4

NAME

6       Test::ClassAPI - Provides basic first-pass API testing for large class
7       trees
8

DESCRIPTION

10       For many APIs with large numbers of classes, it can be very useful to
11       be able to do a quick once-over to make sure that classes, methods, and
12       inheritance is correct, before doing more comprehensive testing. This
13       module aims to provide such a capability.
14
15   Using Test::ClassAPI
16       Test::ClassAPI is used with a fairly standard looking test script, with
17       the API description contained in a __DATA__ section at the end of the
18       script.
19
20         #!/usr/bin/perl
21
22         # Test the API for Foo::Bar
23         use strict;
24         use Test::More 'tests' => 123; # Optional
25         use Test::ClassAPI;
26
27         # Load the API to test
28         use Foo::Bar;
29
30         # Execute the tests
31         Test::ClassAPI->execute;
32
33         __DATA__
34
35         Foo::Bar::Thing=interface
36         Foo::Bar::Object=abstract
37         Foo::Bar::Planet=class
38
39         [Foo::Bar::Thing]
40         foo=method
41
42         [Foo::Bar::Object]
43         bar=method
44         whatsit=method
45
46         [Foo::Bar::Planet]
47         Foo::Bar::Object=isa
48         Foo::Bar::Thing=isa
49         blow_up=method
50         freeze=method
51         thaw=method
52
53       Looking at the test script, the code itself is fairly simple. We first
54       load Test::More and Test::ClassAPI. The loading and specification of a
55       test plan is optional, Test::ClassAPI will provide a plan automatically
56       if needed.
57
58       This is followed by a compulsory __DATA__ section, containing the API
59       description. This description is in provided in the general form of a
60       Windows style .ini file and is structured as follows.
61
62   Class Manifest
63       At the beginning of the file, in the root section of the config file,
64       is a list of entries where the key represents a class name, and the
65       value is one of either 'class', 'abstract', or 'interface'.
66
67       The 'class' entry indicates a fully fledged class. That is, the class
68       is tested to ensure it has been loaded, and the existance of every
69       method listed in the section ( and its superclasses ) is tested for.
70
71       The 'abstract' entry indicates an abstract class, one which is part of
72       our class tree, and needs to exist, but is never instantiated directly,
73       and thus does not have to itself implement all of the methods listed
74       for it. Generally, many individual 'class' entries will inherit from an
75       'abstract', and thus a method listed in the abstract's section will be
76       tested for in all the subclasses of it.
77
78       The 'interface' entry indicates an external interface that is not part
79       of our class tree, but is inherited from by one or more of our classes,
80       and thus the methods listed in the interface's section are tested for
81       in all the classes that inherit from it. For example, if a class
82       inherits from, and implements, the File::Handle interface, a
83       "File::Handle=interface" entry could be added, with the
84       "[File::Handle]" section listing all the methods in File::Handle that
85       our class tree actually cares about. No tests, for class or method
86       existance, are done on the interface itself.
87
88   Class Sections
89       Every class listed in the class manifest MUST have an individual
90       section, indicated by "[Class::Name]" and containing a set of entries
91       where the key is the name of something to test, and the value is the
92       type of test for it.
93
94       The 'isa' test checks inheritance, to make sure that the class the
95       section is for is (by some path) a sub-class of something else. This
96       does not have to be an immediate sub-class. Any class refered to
97       (recursively) in a 'isa' test will have its 'method' test entries
98       applied to the class as well.
99
100       The 'method' test is a simple method existance test, using
101       "UNIVERSAL::can" to make sure that the method exists in the class.
102

METHODS

104   execute
105       The "Test::ClassAPI" has a single method, "execute" which is used to
106       start the testing process. It accepts a single option argument,
107       'complete', which indicates to the testing process that the API listed
108       should be considered a complete list of the entire API. This enables an
109       additional test for each class to ensure that every public method in
110       the class is detailed in the API description, and that nothing has been
111       "missed".
112

SUPPORT

114       Bugs should be submitted via the CPAN bug tracker, located at
115
116       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test-ClassAPI>
117
118       For other issues, or commercial enhancement or support, contact the
119       author.
120

AUTHOR

122       Adam Kennedy <adamk@cpan.org>
123

125       Copyright 2002 - 2009 Adam Kennedy.
126
127       This program is free software; you can redistribute it and/or modify it
128       under the same terms as Perl itself.
129
130       The full text of the license can be found in the LICENSE file included
131       with this module.
132
133
134
135perl v5.10.1                      2009-07-13                 Test::ClassAPI(3)
Impressum