local-lib5/man/man3/TAP::Parser::Aggregator.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 "TAP::Parser::Aggregator 3"
 132 .TH TAP::Parser::Aggregator 3 "2009-05-05" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 TAP::Parser::Aggregator \- Aggregate TAP::Parser results
 135 .SH "VERSION"
 136 .IX Header "VERSION"
 137 Version 3.17
 138 .SH "SYNOPSIS"
 139 .IX Header "SYNOPSIS"
 140 .Vb 1
 141 \&    use TAP::Parser::Aggregator;
 142 .Ve
 143 .PP
 144 .Vb 3
 145 \&    my $aggregate = TAP::Parser::Aggregator\->new;
 146 \&    $aggregate\->add( 't/00\-load.t', $load_parser );
 147 \&    $aggregate\->add( 't/10\-lex.t',  $lex_parser  );
 148 .Ve
 149 .PP
 150 .Vb 9
 151 \&    my $summary = <<'END_SUMMARY';
 152 \&    Passed:  %s
 153 \&    Failed:  %s
 154 \&    Unexpectedly succeeded: %s
 155 \&    END_SUMMARY
 156 \&    printf $summary,
 157 \&           scalar $aggregate\->passed,
 158 \&           scalar $aggregate\->failed,
 159 \&           scalar $aggregate\->todo_passed;
 160 .Ve
 161 .SH "DESCRIPTION"
 162 .IX Header "DESCRIPTION"
 163 \&\f(CW\*(C`TAP::Parser::Aggregator\*(C'\fR collects parser objects and allows
 164 reporting/querying their aggregate results.
 165 .SH "METHODS"
 166 .IX Header "METHODS"
 167 .Sh "Class Methods"
 168 .IX Subsection "Class Methods"
 169 \fI\f(CI\*(C`new\*(C'\fI\fR
 170 .IX Subsection "new"
 171 .PP
 172 .Vb 1
 173 \& my $aggregate = TAP::Parser::Aggregator\->new;
 174 .Ve
 175 .PP
 176 Returns a new \f(CW\*(C`TAP::Parser::Aggregator\*(C'\fR object.
 177 .Sh "Instance Methods"
 178 .IX Subsection "Instance Methods"
 179 \fI\f(CI\*(C`add\*(C'\fI\fR
 180 .IX Subsection "add"
 181 .PP
 182 .Vb 1
 183 \&  $aggregate\->add( $description => $parser );
 184 .Ve
 185 .PP
 186 The \f(CW$description\fR is usually a test file name (but only by
 187 convention.)  It is used as a unique identifier (see e.g.
 188 \&\*(L"parsers\*(R".)  Reusing a description is a fatal error.
 189 .PP
 190 The \f(CW$parser\fR is a TAP::Parser object.
 191 .PP
 192 \fI\f(CI\*(C`parsers\*(C'\fI\fR
 193 .IX Subsection "parsers"
 194 .PP
 195 .Vb 3
 196 \&  my $count   = $aggregate\->parsers;
 197 \&  my @parsers = $aggregate\->parsers;
 198 \&  my @parsers = $aggregate\->parsers(@descriptions);
 199 .Ve
 200 .PP
 201 In scalar context without arguments, this method returns the number of parsers
 202 aggregated.  In list context without arguments, returns the parsers in the
 203 order they were added.
 204 .PP
 205 If \f(CW@descriptions\fR is given, these correspond to the keys used in each
 206 call to the \fIadd()\fR method.  Returns an array of the requested parsers (in
 207 the requested order) in list context or an array reference in scalar
 208 context.
 209 .PP
 210 Requesting an unknown identifier is a fatal error.
 211 .PP
 212 \fI\f(CI\*(C`descriptions\*(C'\fI\fR
 213 .IX Subsection "descriptions"
 214 .PP
 215 Get an array of descriptions in the order in which they were added to
 216 the aggregator.
 217 .PP
 218 \fI\f(CI\*(C`start\*(C'\fI\fR
 219 .IX Subsection "start"
 220 .PP
 221 Call \f(CW\*(C`start\*(C'\fR immediately before adding any results to the aggregator.
 222 Among other times it records the start time for the test run.
 223 .PP
 224 \fI\f(CI\*(C`stop\*(C'\fI\fR
 225 .IX Subsection "stop"
 226 .PP
 227 Call \f(CW\*(C`stop\*(C'\fR immediately after adding all test results to the aggregator.
 228 .PP
 229 \fI\f(CI\*(C`elapsed\*(C'\fI\fR
 230 .IX Subsection "elapsed"
 231 .PP
 232 Elapsed returns a Benchmark object that represents the running time
 233 of the aggregated tests. In order for \f(CW\*(C`elapsed\*(C'\fR to be valid you must
 234 call \f(CW\*(C`start\*(C'\fR before running the tests and \f(CW\*(C`stop\*(C'\fR immediately
 235 afterwards.
 236 .PP
 237 \fI\f(CI\*(C`elapsed_timestr\*(C'\fI\fR
 238 .IX Subsection "elapsed_timestr"
 239 .PP
 240 Returns a formatted string representing the runtime returned by
 241 \&\f(CW\*(C`elapsed()\*(C'\fR.  This lets the caller not worry about Benchmark.
 242 .PP
 243 \fI\f(CI\*(C`all_passed\*(C'\fI\fR
 244 .IX Subsection "all_passed"
 245 .PP
 246 Return true if all the tests passed and no parse errors were detected.
 247 .PP
 248 \fI\f(CI\*(C`get_status\*(C'\fI\fR
 249 .IX Subsection "get_status"
 250 .PP
 251 Get a single word describing the status of the aggregated tests.
 252 Depending on the outcome of the tests returns '\s-1PASS\s0', '\s-1FAIL\s0' or
 253 \&'\s-1NOTESTS\s0'. This token is understood by CPAN::Reporter.
 254 .Sh "Summary methods"
 255 .IX Subsection "Summary methods"
 256 Each of the following methods will return the total number of corresponding
 257 tests if called in scalar context.  If called in list context, returns the
 258 descriptions of the parsers which contain the corresponding tests (see \f(CW\*(C`add\*(C'\fR
 259 for an explanation of description.
 260 .IP "* failed" 4
 261 .IX Item "failed"
 262 .PD 0
 263 .IP "* parse_errors" 4
 264 .IX Item "parse_errors"
 265 .IP "* passed" 4
 266 .IX Item "passed"
 267 .IP "* planned" 4
 268 .IX Item "planned"
 269 .IP "* skipped" 4
 270 .IX Item "skipped"
 271 .IP "* todo" 4
 272 .IX Item "todo"
 273 .IP "* todo_passed" 4
 274 .IX Item "todo_passed"
 275 .IP "* wait" 4
 276 .IX Item "wait"
 277 .IP "* exit" 4
 278 .IX Item "exit"
 279 .PD
 280 .PP
 281 For example, to find out how many tests unexpectedly succeeded (\s-1TODO\s0 tests
 282 which passed when they shouldn't):
 283 .PP
 284 .Vb 2
 285 \& my $count        = $aggregate\->todo_passed;
 286 \& my @descriptions = $aggregate\->todo_passed;
 287 .Ve
 288 .PP
 289 Note that \f(CW\*(C`wait\*(C'\fR and \f(CW\*(C`exit\*(C'\fR are the totals of the wait and exit
 290 statuses of each of the tests. These values are totalled only to provide
 291 a true value if any of them are non\-zero.
 292 .PP
 293 \fI\f(CI\*(C`total\*(C'\fI\fR
 294 .IX Subsection "total"
 295 .PP
 296 .Vb 1
 297 \&  my $tests_run = $aggregate\->total;
 298 .Ve
 299 .PP
 300 Returns the total number of tests run.
 301 .PP
 302 \fI\f(CI\*(C`has_problems\*(C'\fI\fR
 303 .IX Subsection "has_problems"
 304 .PP
 305 .Vb 3
 306 \&  if ( $parser\->has_problems ) {
 307 \&      ...
 308 \&  }
 309 .Ve
 310 .PP
 311 Identical to \f(CW\*(C`has_errors\*(C'\fR, but also returns true if any \s-1TODO\s0 tests
 312 unexpectedly succeeded.  This is more akin to \*(L"warnings\*(R".
 313 .PP
 314 \fI\f(CI\*(C`has_errors\*(C'\fI\fR
 315 .IX Subsection "has_errors"
 316 .PP
 317 .Vb 3
 318 \&  if ( $parser\->has_errors ) {
 319 \&      ...
 320 \&  }
 321 .Ve
 322 .PP
 323 Returns true if \fIany\fR of the parsers failed.  This includes:
 324 .IP "* Failed tests" 4
 325 .IX Item "Failed tests"
 326 .PD 0
 327 .IP "* Parse errors" 4
 328 .IX Item "Parse errors"
 329 .IP "* Bad exit or wait status" 4
 330 .IX Item "Bad exit or wait status"
 331 .PD
 332 .PP
 333 \fI\f(CI\*(C`todo_failed\*(C'\fI\fR
 334 .IX Subsection "todo_failed"
 335 .PP
 336 .Vb 1
 337 \&  # deprecated in favor of 'todo_passed'.  This method was horribly misnamed.
 338 .Ve
 339 .PP
 340 This was a badly misnamed method.  It indicates which \s-1TODO\s0 tests unexpectedly
 341 succeeded.  Will now issue a warning and call \f(CW\*(C`todo_passed\*(C'\fR.
 342 .SH "See Also"
 343 .IX Header "See Also"
 344 TAP::Parser
 345 .PP
 346 TAP::Harness