.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" ======================================================================== .\" .IX Title "Test::ClassAPI 3pm" .TH Test::ClassAPI 3pm "2017-12-30" "perl v5.26.1" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::ClassAPI \- Provides basic first\-pass API testing for large class trees .SH "VERSION" .IX Header "VERSION" version 1.07 .SH "DESCRIPTION" .IX Header "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. .SS "Using Test::ClassAPI" .IX Subsection "Using Test::ClassAPI" Test::ClassAPI is used with a fairly standard looking test script, with the \&\s-1API\s0 description contained in a _\|_DATA_\|_ section at the end of the script. .PP .Vb 1 \& #!/usr/bin/perl \& \& # Test the API for Foo::Bar \& use strict; \& use Test::More \*(Aqtests\*(Aq => 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 .Ve .PP 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. .PP This is followed by a compulsory _\|_DATA_\|_ section, containing the \s-1API\s0 description. This description is in provided in the general form of a Windows style .ini file and is structured as follows. .SS "Class Manifest" .IX Subsection "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'. .PP 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. .PP 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. .PP 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 \f(CW\*(C`File::Handle=interface\*(C'\fR entry could be added, with the \f(CW\*(C`[File::Handle]\*(C'\fR 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. .SS "Class Sections" .IX Subsection "Class Sections" Every class listed in the class manifest \fB\s-1MUST\s0\fR have an individual section, indicated by \f(CW\*(C`[Class::Name]\*(C'\fR 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. .PP 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. .PP The 'method' test is a simple method existance test, using \f(CW\*(C`UNIVERSAL::can\*(C'\fR to make sure that the method exists in the class. .SH "METHODS" .IX Header "METHODS" .SS "execute" .IX Subsection "execute" The \f(CW\*(C`Test::ClassAPI\*(C'\fR has a single method, \f(CW\*(C`execute\*(C'\fR which is used to start the testing process. It accepts a single option argument, 'complete', which indicates to the testing process that the \s-1API\s0 listed should be considered a complete list of the entire \s-1API.\s0 This enables an additional test for each class to ensure that \fBevery\fR public method in the class is detailed in the \&\s-1API\s0 description, and that nothing has been \*(L"missed\*(R". .SH "SUPPORT" .IX Header "SUPPORT" Bugs may be submitted through the \s-1RT\s0 bug tracker (or bug\-Test\-ClassAPI@rt.cpan.org ). .SH "AUTHOR" .IX Header "AUTHOR" Adam Kennedy .SH "CONTRIBUTORS" .IX Header "CONTRIBUTORS" .IP "\(bu" 4 Adam Kennedy .IP "\(bu" 4 Karen Etheridge .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2003 by Adam Kennedy. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.