local-lib5/man/man3/Test::ClassAPI.3pm

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "Test::ClassAPI 3"
 127 .TH Test::ClassAPI 3 "2009-07-13" "perl v5.8.7" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 Test::ClassAPI \- Provides basic first\-pass API testing for large class trees
 134 .SH "DESCRIPTION"
 135 .IX Header "DESCRIPTION"
 136 For many APIs with large numbers of classes, it can be very useful to be able
 137 to do a quick once-over to make sure that classes, methods, and inheritance
 138 is correct, before doing more comprehensive testing. This module aims to
 139 provide such a capability.
 140 .SS "Using Test::ClassAPI"
 141 .IX Subsection "Using Test::ClassAPI"
 142 Test::ClassAPI is used with a fairly standard looking test script, with the
 143 \&\s-1API\s0 description contained in a _\|_DATA_\|_ section at the end of the script.
 144 .PP
 145 .Vb 1
 146 \&  #!/usr/bin/perl
 147 \&
 148 \&  # Test the API for Foo::Bar
 149 \&  use strict;
 150 \&  use Test::More \*(Aqtests\*(Aq => 123; # Optional
 151 \&  use Test::ClassAPI;
 152 \&
 153 \&  # Load the API to test
 154 \&  use Foo::Bar;
 155 \&
 156 \&  # Execute the tests
 157 \&  Test::ClassAPI\->execute;
 158 \&
 159 \&  _\|_DATA_\|_
 160 \&
 161 \&  Foo::Bar::Thing=interface
 162 \&  Foo::Bar::Object=abstract
 163 \&  Foo::Bar::Planet=class
 164 \&
 165 \&  [Foo::Bar::Thing]
 166 \&  foo=method
 167 \&
 168 \&  [Foo::Bar::Object]
 169 \&  bar=method
 170 \&  whatsit=method
 171 \&
 172 \&  [Foo::Bar::Planet]
 173 \&  Foo::Bar::Object=isa
 174 \&  Foo::Bar::Thing=isa
 175 \&  blow_up=method
 176 \&  freeze=method
 177 \&  thaw=method
 178 .Ve
 179 .PP
 180 Looking at the test script, the code itself is fairly simple. We first load
 181 Test::More and Test::ClassAPI. The loading and specification of a test plan
 182 is optional, Test::ClassAPI will provide a plan automatically if needed.
 183 .PP
 184 This is followed by a compulsory _\|_DATA_\|_ section, containing the \s-1API\s0
 185 description. This description is in provided in the general form of a Windows
 186 style .ini file and is structured as follows.
 187 .SS "Class Manifest"
 188 .IX Subsection "Class Manifest"
 189 At the beginning of the file, in the root section of the config file, is a
 190 list of entries where the key represents a class name, and the value is one
 191 of either 'class', 'abstract', or 'interface'.
 192 .PP
 193 The 'class' entry indicates a fully fledged class. That is, the class is
 194 tested to ensure it has been loaded, and the existance of every method listed
 195 in the section ( and its superclasses ) is tested for.
 196 .PP
 197 The 'abstract' entry indicates an abstract class, one which is part of our
 198 class tree, and needs to exist, but is never instantiated directly, and thus
 199 does not have to itself implement all of the methods listed for it. Generally,
 200 many individual 'class' entries will inherit from an 'abstract', and thus a
 201 method listed in the abstract's section will be tested for in all the
 202 subclasses of it.
 203 .PP
 204 The 'interface' entry indicates an external interface that is not part of
 205 our class tree, but is inherited from by one or more of our classes, and thus
 206 the methods listed in the interface's section are tested for in all the
 207 classes that inherit from it. For example, if a class inherits from, and
 208 implements, the File::Handle interface, a \f(CW\*(C`File::Handle=interface\*(C'\fR entry
 209 could be added, with the \f(CW\*(C`[File::Handle]\*(C'\fR section listing all the methods
 210 in File::Handle that our class tree actually cares about. No tests, for class
 211 or method existance, are done on the interface itself.
 212 .SS "Class Sections"
 213 .IX Subsection "Class Sections"
 214 Every class listed in the class manifest \fB\s-1MUST\s0\fR have an individual section,
 215 indicated by \f(CW\*(C`[Class::Name]\*(C'\fR and containing a set of entries where the key
 216 is the name of something to test, and the value is the type of test for it.
 217 .PP
 218 The 'isa' test checks inheritance, to make sure that the class the section is
 219 for is (by some path) a sub-class of something else. This does not have to be
 220 an immediate sub-class. Any class refered to (recursively) in a 'isa' test
 221 will have its 'method' test entries applied to the class as well.
 222 .PP
 223 The 'method' test is a simple method existance test, using \f(CW\*(C`UNIVERSAL::can\*(C'\fR
 224 to make sure that the method exists in the class.
 225 .SH "METHODS"
 226 .IX Header "METHODS"
 227 .SS "execute"
 228 .IX Subsection "execute"
 229 The \f(CW\*(C`Test::ClassAPI\*(C'\fR has a single method, \f(CW\*(C`execute\*(C'\fR which is used to start
 230 the testing process. It accepts a single option argument, 'complete', which
 231 indicates to the testing process that the \s-1API\s0 listed should be considered a
 232 complete list of the entire \s-1API\s0. This enables an additional test for each
 233 class to ensure that \fBevery\fR public method in the class is detailed in the
 234 \&\s-1API\s0 description, and that nothing has been \*(L"missed\*(R".
 235 .SH "SUPPORT"
 236 .IX Header "SUPPORT"
 237 Bugs should be submitted via the \s-1CPAN\s0 bug tracker, located at
 238 .PP
 239 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test\-ClassAPI>
 240 .PP
 241 For other issues, or commercial enhancement or support, contact the author.
 242 .SH "AUTHOR"
 243 .IX Header "AUTHOR"
 244 Adam Kennedy <adamk@cpan.org>
 245 .SH "COPYRIGHT"
 246 .IX Header "COPYRIGHT"
 247 Copyright 2002 \- 2009 Adam Kennedy.
 248 .PP
 249 This program is free software; you can redistribute
 250 it and/or modify it under the same terms as Perl itself.
 251 .PP
 252 The full text of the license can be found in the
 253 \&\s-1LICENSE\s0 file included with this module.