local-lib5/man/man3/Test::Builder::Module.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "Test::Builder::Module 3"
 132 .TH Test::Builder::Module 3 "2009-09-02" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Test::Builder::Module \- Base class for test modules
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 2
 138 \&  # Emulates Test::Simple
 139 \&  package Your::Module;
 140 .Ve
 141 .PP
 142 .Vb 1
 143 \&  my $CLASS = __PACKAGE__;
 144 .Ve
 145 .PP
 146 .Vb 2
 147 \&  use base 'Test::Builder::Module';
 148 \&  @EXPORT = qw(ok);
 149 .Ve
 150 .PP
 151 .Vb 4
 152 \&  sub ok ($;$) {
 153 \&      my $tb = $CLASS\->builder;
 154 \&      return $tb\->ok(@_);
 155 \&  }
 156 .Ve
 157 .PP
 158 .Vb 1
 159 \&  1;
 160 .Ve
 161 .SH "DESCRIPTION"
 162 .IX Header "DESCRIPTION"
 163 This is a superclass for Test::Builder\-based modules.  It provides a
 164 handful of common functionality and a method of getting at the underlying
 165 Test::Builder object.
 166 .Sh "Importing"
 167 .IX Subsection "Importing"
 168 Test::Builder::Module is a subclass of Exporter which means your
 169 module is also a subclass of Exporter.  \f(CW@EXPORT\fR, \f(CW@EXPORT_OK\fR, etc...
 170 all act normally.
 171 .PP
 172 A few methods are provided to do the \f(CW\*(C`use Your::Module tests =\*(C'\fR 23> part
 173 for you.
 174 .PP
 175 \fIimport\fR
 176 .IX Subsection "import"
 177 .PP
 178 Test::Builder::Module provides an \fIimport()\fR method which acts in the
 179 same basic way as Test::More's, setting the plan and controling
 180 exporting of functions and variables.  This allows your module to set
 181 the plan independent of Test::More.
 182 .PP
 183 All arguments passed to \fIimport()\fR are passed onto
 184 \&\f(CW\*(C`Your::Module\->builder\->plan()\*(C'\fR with the exception of
 185 \&\f(CW\*(C`import =\*(C'\fR[qw(things to import)]>.
 186 .PP
 187 .Vb 1
 188 \&    use Your::Module import => [qw(this that)], tests => 23;
 189 .Ve
 190 .PP
 191 says to import the functions \fIthis()\fR and \fIthat()\fR as well as set the plan
 192 to be 23 tests.
 193 .PP
 194 \&\fIimport()\fR also sets the \fIexported_to()\fR attribute of your builder to be
 195 the caller of the \fIimport()\fR function.
 196 .PP
 197 Additional behaviors can be added to your \fIimport()\fR method by overriding
 198 \&\fIimport_extra()\fR.
 199 .PP
 200 \fIimport_extra\fR
 201 .IX Subsection "import_extra"
 202 .PP
 203 .Vb 1
 204 \&    Your::Module\->import_extra(\e@import_args);
 205 .Ve
 206 .PP
 207 \&\fIimport_extra()\fR is called by \fIimport()\fR.  It provides an opportunity for you
 208 to add behaviors to your module based on its import list.
 209 .PP
 210 Any extra arguments which shouldn't be passed on to \fIplan()\fR should be
 211 stripped off by this method.
 212 .PP
 213 See Test::More for an example of its use.
 214 .PP
 215 \&\fB\s-1NOTE\s0\fR This mechanism is \fI\s-1VERY\s0 \s-1ALPHA\s0 \s-1AND\s0 \s-1LIKELY\s0 \s-1TO\s0 \s-1CHANGE\s0\fR as it
 216 feels like a bit of an ugly hack in its current form.
 217 .Sh "Builder"
 218 .IX Subsection "Builder"
 219 Test::Builder::Module provides some methods of getting at the underlying
 220 Test::Builder object.
 221 .PP
 222 \fIbuilder\fR
 223 .IX Subsection "builder"
 224 .PP
 225 .Vb 1
 226 \&  my $builder = Your::Class\->builder;
 227 .Ve
 228 .PP
 229 This method returns the Test::Builder object associated with Your::Class.
 230 It is not a constructor so you can call it as often as you like.
 231 .PP
 232 This is the preferred way to get the Test::Builder object.  You should
 233 \&\fInot\fR get it via \f(CW\*(C`Test::Builder\->new\*(C'\fR as was previously
 234 recommended.
 235 .PP
 236 The object returned by \fIbuilder()\fR may change at runtime so you should
 237 call \fIbuilder()\fR inside each function rather than store it in a global.
 238 .PP
 239 .Vb 2
 240 \&  sub ok {
 241 \&      my $builder = Your::Class\->builder;
 242 .Ve
 243 .PP
 244 .Vb 2
 245 \&      return $builder\->ok(@_);
 246 \&  }
 247 .Ve