1Test::ClassAPI(3) User Contributed Perl Documentation Test::ClassAPI(3)
2
6 Test::ClassAPI - Provides basic first-pass API testing for large class
7 trees
8
10 version 1.07
11
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 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 #!/usr/bin/perl
24 # Test the API for Foo::Bar
26 use strict;
27 use Test::More 'tests' => 123; # Optional
28 use Test::ClassAPI;
29 # Load the API to test
31 use Foo::Bar;
32 # Execute the tests
34 Test::ClassAPI->execute;
35 __DATA__
37 Foo::Bar::Thing=interface
39 Foo::Bar::Object=abstract
40 Foo::Bar::Planet=class
41 [Foo::Bar::Thing]
43 foo=method
44 [Foo::Bar::Object]
46 bar=method
47 whatsit=method
48 [Foo::Bar::Planet]
50 Foo::Bar::Object=isa
51 Foo::Bar::Thing=isa
52 blow_up=method
53 freeze=method
54 thaw=method
55 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 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 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 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 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 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 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 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 The 'method' test is a simple method existance test, using
104 "UNIVERSAL::can" to make sure that the method exists in the class.
105
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
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
122 Adam Kennedy <adamk@cpan.org>
123
125 · Adam Kennedy <adam@ali.as>
126 · Karen Etheridge <ether@cpan.org>
128
130 This software is copyright (c) 2003 by Adam Kennedy.
131 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.
134perl v5.30.0 2019-07-26 Test::ClassAPI(3)