Debian Codegraph @

upstream/debian-unstable/man3/TAP::Parser::Aggregator.3perl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "TAP::Parser::Aggregator 3perl"
58 .TH TAP::Parser::Aggregator 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide"
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 TAP::Parser::Aggregator \- Aggregate TAP::Parser results
65 .SH VERSION
66 .IX Header "VERSION"
67 Version 3.48
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& use TAP::Parser::Aggregator;
72 \&
73 \& my $aggregate = TAP::Parser::Aggregator\->new;
74 \& $aggregate\->add( \*(Aqt/00\-load.t\*(Aq, $load_parser );
75 \& $aggregate\->add( \*(Aqt/10\-lex.t\*(Aq, $lex_parser );
76 \&
77 \& my $summary = <<\*(AqEND_SUMMARY\*(Aq;
78 \& Passed: %s
79 \& Failed: %s
80 \& Unexpectedly succeeded: %s
81 \& END_SUMMARY
82 \& printf $summary,
83 \& scalar $aggregate\->passed,
84 \& scalar $aggregate\->failed,
85 \& scalar $aggregate\->todo_passed;
86 .Ve
87 .SH DESCRIPTION
88 .IX Header "DESCRIPTION"
89 \&\f(CW\*(C`TAP::Parser::Aggregator\*(C'\fR collects parser objects and allows
90 reporting/querying their aggregate results.
91 .SH METHODS
92 .IX Header "METHODS"
93 .SS "Class Methods"
94 .IX Subsection "Class Methods"
95 \fR\f(CI\*(C`new\*(C'\fR\fI\fR
96 .IX Subsection "new"
97 .PP
98 .Vb 1
99 \& my $aggregate = TAP::Parser::Aggregator\->new;
100 .Ve
101 .PP
102 Returns a new \f(CW\*(C`TAP::Parser::Aggregator\*(C'\fR object.
103 .SS "Instance Methods"
104 .IX Subsection "Instance Methods"
105 \fR\f(CI\*(C`add\*(C'\fR\fI\fR
106 .IX Subsection "add"
107 .PP
108 .Vb 1
109 \& $aggregate\->add( $description => $parser );
110 .Ve
111 .PP
112 The \f(CW$description\fR is usually a test file name (but only by
113 convention.) It is used as a unique identifier (see e.g.
114 "parsers".) Reusing a description is a fatal error.
115 .PP
116 The \f(CW$parser\fR is a TAP::Parser object.
117 .PP
118 \fR\f(CI\*(C`parsers\*(C'\fR\fI\fR
119 .IX Subsection "parsers"
120 .PP
121 .Vb 3
122 \& my $count = $aggregate\->parsers;
123 \& my @parsers = $aggregate\->parsers;
124 \& my @parsers = $aggregate\->parsers(@descriptions);
125 .Ve
126 .PP
127 In scalar context without arguments, this method returns the number of parsers
128 aggregated. In list context without arguments, returns the parsers in the
129 order they were added.
130 .PP
131 If \f(CW@descriptions\fR is given, these correspond to the keys used in each
132 call to the \fBadd()\fR method. Returns an array of the requested parsers (in
133 the requested order) in list context or an array reference in scalar
134 context.
135 .PP
136 Requesting an unknown identifier is a fatal error.
137 .PP
138 \fR\f(CI\*(C`descriptions\*(C'\fR\fI\fR
139 .IX Subsection "descriptions"
140 .PP
141 Get an array of descriptions in the order in which they were added to
142 the aggregator.
143 .PP
144 \fR\f(CI\*(C`start\*(C'\fR\fI\fR
145 .IX Subsection "start"
146 .PP
147 Call \f(CW\*(C`start\*(C'\fR immediately before adding any results to the aggregator.
148 Among other times it records the start time for the test run.
149 .PP
150 \fR\f(CI\*(C`stop\*(C'\fR\fI\fR
151 .IX Subsection "stop"
152 .PP
153 Call \f(CW\*(C`stop\*(C'\fR immediately after adding all test results to the aggregator.
154 .PP
155 \fR\f(CI\*(C`elapsed\*(C'\fR\fI\fR
156 .IX Subsection "elapsed"
157 .PP
158 Elapsed returns a Benchmark object that represents the running time
159 of the aggregated tests. In order for \f(CW\*(C`elapsed\*(C'\fR to be valid you must
160 call \f(CW\*(C`start\*(C'\fR before running the tests and \f(CW\*(C`stop\*(C'\fR immediately
161 afterwards.
162 .PP
163 \fR\f(CI\*(C`elapsed_timestr\*(C'\fR\fI\fR
164 .IX Subsection "elapsed_timestr"
165 .PP
166 Returns a formatted string representing the runtime returned by
167 \&\f(CWelapsed()\fR. This lets the caller not worry about Benchmark.
168 .PP
169 \fR\f(CI\*(C`all_passed\*(C'\fR\fI\fR
170 .IX Subsection "all_passed"
171 .PP
172 Return true if all the tests passed and no parse errors were detected.
173 .PP
174 \fR\f(CI\*(C`get_status\*(C'\fR\fI\fR
175 .IX Subsection "get_status"
176 .PP
177 Get a single word describing the status of the aggregated tests.
178 Depending on the outcome of the tests returns 'PASS', 'FAIL' or
179 \&'NOTESTS'. This token is understood by CPAN::Reporter.
180 .SS "Summary methods"
181 .IX Subsection "Summary methods"
182 Each of the following methods will return the total number of corresponding
183 tests if called in scalar context. If called in list context, returns the
184 descriptions of the parsers which contain the corresponding tests (see \f(CW\*(C`add\*(C'\fR
185 for an explanation of description.
186 .IP \(bu 4
187 failed
188 .IP \(bu 4
189 parse_errors
190 .IP \(bu 4
191 passed
192 .IP \(bu 4
193 planned
194 .IP \(bu 4
195 skipped
196 .IP \(bu 4
197 todo
198 .IP \(bu 4
199 todo_passed
200 .IP \(bu 4
201 wait
202 .IP \(bu 4
203 exit
204 .PP
205 For example, to find out how many tests unexpectedly succeeded (TODO tests
206 which passed when they shouldn't):
207 .PP
208 .Vb 2
209 \& my $count = $aggregate\->todo_passed;
210 \& my @descriptions = $aggregate\->todo_passed;
211 .Ve
212 .PP
213 Note that \f(CW\*(C`wait\*(C'\fR and \f(CW\*(C`exit\*(C'\fR are the totals of the wait and exit
214 statuses of each of the tests. These values are totalled only to provide
215 a true value if any of them are non-zero.
216 .PP
217 \fR\f(CI\*(C`total\*(C'\fR\fI\fR
218 .IX Subsection "total"
219 .PP
220 .Vb 1
221 \& my $tests_run = $aggregate\->total;
222 .Ve
223 .PP
224 Returns the total number of tests run.
225 .PP
226 \fR\f(CI\*(C`has_problems\*(C'\fR\fI\fR
227 .IX Subsection "has_problems"
228 .PP
229 .Vb 3
230 \& if ( $parser\->has_problems ) {
231 \& ...
232 \& }
233 .Ve
234 .PP
235 Identical to \f(CW\*(C`has_errors\*(C'\fR, but also returns true if any TODO tests
236 unexpectedly succeeded. This is more akin to "warnings".
237 .PP
238 \fR\f(CI\*(C`has_errors\*(C'\fR\fI\fR
239 .IX Subsection "has_errors"
240 .PP
241 .Vb 3
242 \& if ( $parser\->has_errors ) {
243 \& ...
244 \& }
245 .Ve
246 .PP
247 Returns true if \fIany\fR of the parsers failed. This includes:
248 .IP \(bu 4
249 Failed tests
250 .IP \(bu 4
251 Parse errors
252 .IP \(bu 4
253 Bad exit or wait status
254 .PP
255 \fR\f(CI\*(C`todo_failed\*(C'\fR\fI\fR
256 .IX Subsection "todo_failed"
257 .PP
258 .Vb 1
259 \& # deprecated in favor of \*(Aqtodo_passed\*(Aq. This method was horribly misnamed.
260 .Ve
261 .PP
262 This was a badly misnamed method. It indicates which TODO tests unexpectedly
263 succeeded. Will now issue a warning and call \f(CW\*(C`todo_passed\*(C'\fR.
264 .SH "See Also"
265 .IX Header "See Also"
266 TAP::Parser
267 .PP
268 TAP::Harness