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

VERSION

10       version 1.07
11

DESCRIPTION

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

METHODS

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

SUPPORT

117       Bugs may be submitted through the RT bug tracker
118       <https://rt.cpan.org/Public/Dist/Display.html?Name=Test-ClassAPI> (or
119       bug-Test-ClassAPI@rt.cpan.org <mailto:bug-Test-ClassAPI@rt.cpan.org>).
120

AUTHOR

122       Adam Kennedy <adamk@cpan.org>
123

CONTRIBUTORS

125       •   Adam Kennedy <adam@ali.as>
126
127       •   Karen Etheridge <ether@cpan.org>
128

130       This software is copyright (c) 2003 by Adam Kennedy.
131
132       This is free software; you can redistribute it and/or modify it under
133       the same terms as the Perl 5 programming language system itself.
134
135
136
137perl v5.32.1                      2021-01-27                 Test::ClassAPI(3)
Impressum