local-lib5/man/man3/Test::Object.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::Object 3"
 127 .TH Test::Object 3 "2006-09-07" "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::Object \- Thoroughly testing objects via registered handlers
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 .Vb 3
 137 \&  ###################################################################
 138 \&  # In your test module, register test handlers again class names   #
 139 \&  ###################################################################
 140 \&
 141 \&  package My::ModuleTester;
 142 \&
 143 \&  use Test::More;
 144 \&  use Test::Object;
 145 \&
 146 \&  # Foo::Bar is a subclass of Foo
 147 \&  Test::Object\->register(
 148 \&        class => \*(AqFoo\*(Aq,
 149 \&        tests => 5,
 150 \&        code  => \e&foo_ok,
 151 \&        );
 152 \&  Test::Object\->register(
 153 \&        class => \*(AqFoo::Bar\*(Aq,
 154 \&        # No fixed number of tests
 155 \&        code  => \e&foobar_ok,
 156 \&        );
 157 \&
 158 \&  sub foo_ok {
 159 \&        my $object = shift;
 160 \&        ok( $object\->foo, \*(Aq\->foo returns true\*(Aq );
 161 \&  }
 162 \&
 163 \&  sub foobar_ok {
 164 \&        my $object = shift;
 165 \&        is( $object\->foo, \*(Aqbar\*(Aq, \*(Aq\->foo returns "bar"\*(Aq );
 166 \&  }
 167 \&
 168 \&  1;
 169 \&
 170 \&
 171 \&
 172 \&  ###################################################################
 173 \&  # In test script, test object against all registered classes      #
 174 \&  ###################################################################
 175 \&
 176 \&  #!/usr/bin/perl \-w
 177 \&
 178 \&  use Test::More \*(Aqno_plan\*(Aq;
 179 \&  use Test::Object;
 180 \&  use My::ModuleTester;
 181 \&
 182 \&  my $object = Foo::Bar\->new;
 183 \&  isa_ok( $object, \*(AqFoo::Bar\*(Aq );
 184 \&  object_ok( $object );
 185 .Ve
 186 .SH "DESCRIPTION"
 187 .IX Header "DESCRIPTION"
 188 In situations where you have deep trees of classes, there is a common
 189 situation in which you test a module 4 or 5 subclasses down, which should
 190 follow the correct behaviour of not just the subclass, but of all the
 191 parent classes.
 192 .PP
 193 This should be done to ensure that the implementation of a subclass has
 194 not somehow \*(L"broken\*(R" the object's behaviour in a more general sense.
 195 .PP
 196 \&\f(CW\*(C`Test::Object\*(C'\fR is a testing package designed to allow you to easily test
 197 what you believe is a valid object against the expected behaviour of \fBall\fR
 198 of the classes in its inheritance tree in one single call.
 199 .PP
 200 To do this, you \*(L"register\*(R" tests (in the form of \s-1CODE\s0 or function
 201 references) with \f(CW\*(C`Test::Object\*(C'\fR, with each test associated with a
 202 particular class.
 203 .PP
 204 When you call \f(CW\*(C`object_ok\*(C'\fR in your test script, \f(CW\*(C`Test::Object\*(C'\fR will check
 205 the object against all registered tests. For each class that your object
 206 responds to \f(CW\*(C`$object\->isa($class)\*(C'\fR for, the appropriate testing
 207 function will be called.
 208 .PP
 209 Doing it this way allows adapter objects and other things that respond
 210 to \f(CW\*(C`isa\*(C'\fR differently that the default to still be tested against the
 211 classes that it is advertising itself as correctly.
 212 .PP
 213 This also means that more than one test might be \*(L"counted\*(R" for each call
 214 to \f(CW\*(C`object_ok\*(C'\fR. You should account for this correctly in your expected
 215 test count.
 216 .SH "SUPPORT"
 217 .IX Header "SUPPORT"
 218 Bugs should be submitted via the \s-1CPAN\s0 bug tracker, located at
 219 .PP
 220 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Test\-Object>
 221 .PP
 222 For other issues, contact the author.
 223 .SH "AUTHOR"
 224 .IX Header "AUTHOR"
 225 Adam Kennedy <cpan@ali.as>
 226 .SH "SEE ALSO"
 227 .IX Header "SEE ALSO"
 228 <http://ali.as/>, Test::More, Test::Builder::Tester, Test::Class
 229 .SH "COPYRIGHT"
 230 .IX Header "COPYRIGHT"
 231 Copyright 2005, 2006 Adam Kennedy. All rights reserved.
 232 .PP
 233 This program is free software; you can redistribute
 234 it and/or modify it under the same terms as Perl itself.
 235 .PP
 236 The full text of the license can be found in the
 237 \&\s-1LICENSE\s0 file included with this module.