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

METHODS

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

SUPPORT

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

AUTHOR

126       Adam Kennedy <adamk@cpan.org>
127

129       Copyright 2002 - 2007 Adam Kennedy.
130
131       This program is free software; you can redistribute it and/or modify it
132       under the same terms as Perl itself.
133
134       The full text of the license can be found in the LICENSE file included
135       with this module.
136
137
138
139perl v5.8.8                       2007-03-11                 Test::ClassAPI(3)
Impressum