Debian Codegraph @

upstream/opensuse-tumbleweed/man3/TAP::Parser::Aggregator.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (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 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "TAP::Parser::Aggregator 3pm"
61 .TH TAP::Parser::Aggregator 3pm 2026-03-09 "perl v5.42.1" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 TAP::Parser::Aggregator \- Aggregate TAP::Parser results
68 .SH VERSION
69 .IX Header "VERSION"
70 Version 3.50
71 .SH SYNOPSIS
72 .IX Header "SYNOPSIS"
73 .Vb 1
74 \& use TAP::Parser::Aggregator;
75 \&
76 \& my $aggregate = TAP::Parser::Aggregator\->new;
77 \& $aggregate\->add( \*(Aqt/00\-load.t\*(Aq, $load_parser );
78 \& $aggregate\->add( \*(Aqt/10\-lex.t\*(Aq, $lex_parser );
79 \&
80 \& my $summary = <<\*(AqEND_SUMMARY\*(Aq;
81 \& Passed: %s
82 \& Failed: %s
83 \& Unexpectedly succeeded: %s
84 \& END_SUMMARY
85 \& printf $summary,
86 \& scalar $aggregate\->passed,
87 \& scalar $aggregate\->failed,
88 \& scalar $aggregate\->todo_passed;
89 .Ve
90 .SH DESCRIPTION
91 .IX Header "DESCRIPTION"
92 \&\f(CW\*(C`TAP::Parser::Aggregator\*(C'\fR collects parser objects and allows
93 reporting/querying their aggregate results.
94 .SH METHODS
95 .IX Header "METHODS"
96 .SS "Class Methods"
97 .IX Subsection "Class Methods"
98 \fR\f(CI\*(C`new\*(C'\fR\fI\fR
99 .IX Subsection "new"
100 .PP
101 .Vb 1
102 \& my $aggregate = TAP::Parser::Aggregator\->new;
103 .Ve
104 .PP
105 Returns a new \f(CW\*(C`TAP::Parser::Aggregator\*(C'\fR object.
106 .SS "Instance Methods"
107 .IX Subsection "Instance Methods"
108 \fR\f(CI\*(C`add\*(C'\fR\fI\fR
109 .IX Subsection "add"
110 .PP
111 .Vb 1
112 \& $aggregate\->add( $description => $parser );
113 .Ve
114 .PP
115 The \f(CW$description\fR is usually a test file name (but only by
116 convention.) It is used as a unique identifier (see e.g.
117 "parsers".) Reusing a description is a fatal error.
118 .PP
119 The \f(CW$parser\fR is a TAP::Parser object.
120 .PP
121 \fR\f(CI\*(C`parsers\*(C'\fR\fI\fR
122 .IX Subsection "parsers"
123 .PP
124 .Vb 3
125 \& my $count = $aggregate\->parsers;
126 \& my @parsers = $aggregate\->parsers;
127 \& my @parsers = $aggregate\->parsers(@descriptions);
128 .Ve
129 .PP
130 In scalar context without arguments, this method returns the number of parsers
131 aggregated. In list context without arguments, returns the parsers in the
132 order they were added.
133 .PP
134 If \f(CW@descriptions\fR is given, these correspond to the keys used in each
135 call to the \fBadd()\fR method. Returns an array of the requested parsers (in
136 the requested order) in list context or an array reference in scalar
137 context.
138 .PP
139 Requesting an unknown identifier is a fatal error.
140 .PP
141 \fR\f(CI\*(C`descriptions\*(C'\fR\fI\fR
142 .IX Subsection "descriptions"
143 .PP
144 Get an array of descriptions in the order in which they were added to
145 the aggregator.
146 .PP
147 \fR\f(CI\*(C`start\*(C'\fR\fI\fR
148 .IX Subsection "start"
149 .PP
150 Call \f(CW\*(C`start\*(C'\fR immediately before adding any results to the aggregator.
151 Among other times it records the start time for the test run.
152 .PP
153 \fR\f(CI\*(C`stop\*(C'\fR\fI\fR
154 .IX Subsection "stop"
155 .PP
156 Call \f(CW\*(C`stop\*(C'\fR immediately after adding all test results to the aggregator.
157 .PP
158 \fR\f(CI\*(C`elapsed\*(C'\fR\fI\fR
159 .IX Subsection "elapsed"
160 .PP
161 Elapsed returns a Benchmark object that represents the running time
162 of the aggregated tests. In order for \f(CW\*(C`elapsed\*(C'\fR to be valid you must
163 call \f(CW\*(C`start\*(C'\fR before running the tests and \f(CW\*(C`stop\*(C'\fR immediately
164 afterwards.
165 .PP
166 \fR\f(CI\*(C`elapsed_timestr\*(C'\fR\fI\fR
167 .IX Subsection "elapsed_timestr"
168 .PP
169 Returns a formatted string representing the runtime returned by
170 \&\f(CWelapsed()\fR. This lets the caller not worry about Benchmark.
171 .PP
172 \fR\f(CI\*(C`all_passed\*(C'\fR\fI\fR
173 .IX Subsection "all_passed"
174 .PP
175 Return true if all the tests passed and no parse errors were detected.
176 .PP
177 \fR\f(CI\*(C`get_status\*(C'\fR\fI\fR
178 .IX Subsection "get_status"
179 .PP
180 Get a single word describing the status of the aggregated tests.
181 Depending on the outcome of the tests returns \*(AqPASS\*(Aq, \*(AqFAIL\*(Aq or
182 \&\*(AqNOTESTS\*(Aq. This token is understood by CPAN::Reporter.
183 .SS "Summary methods"
184 .IX Subsection "Summary methods"
185 Each of the following methods will return the total number of corresponding
186 tests if called in scalar context. If called in list context, returns the
187 descriptions of the parsers which contain the corresponding tests (see \f(CW\*(C`add\*(C'\fR
188 for an explanation of description.
189 .IP \(bu 4
190 failed
191 .IP \(bu 4
192 parse_errors
193 .IP \(bu 4
194 passed
195 .IP \(bu 4
196 planned
197 .IP \(bu 4
198 skipped
199 .IP \(bu 4
200 todo
201 .IP \(bu 4
202 todo_passed
203 .IP \(bu 4
204 wait
205 .IP \(bu 4
206 exit
207 .PP
208 For example, to find out how many tests unexpectedly succeeded (TODO tests
209 which passed when they shouldn\*(Aqt):
210 .PP
211 .Vb 2
212 \& my $count = $aggregate\->todo_passed;
213 \& my @descriptions = $aggregate\->todo_passed;
214 .Ve
215 .PP
216 Note that \f(CW\*(C`wait\*(C'\fR and \f(CW\*(C`exit\*(C'\fR are the totals of the wait and exit
217 statuses of each of the tests. These values are totalled only to provide
218 a true value if any of them are non\-zero.
219 .PP
220 \fR\f(CI\*(C`total\*(C'\fR\fI\fR
221 .IX Subsection "total"
222 .PP
223 .Vb 1
224 \& my $tests_run = $aggregate\->total;
225 .Ve
226 .PP
227 Returns the total number of tests run.
228 .PP
229 \fR\f(CI\*(C`has_problems\*(C'\fR\fI\fR
230 .IX Subsection "has_problems"
231 .PP
232 .Vb 3
233 \& if ( $parser\->has_problems ) {
234 \& ...
235 \& }
236 .Ve
237 .PP
238 Identical to \f(CW\*(C`has_errors\*(C'\fR, but also returns true if any TODO tests
239 unexpectedly succeeded. This is more akin to "warnings".
240 .PP
241 \fR\f(CI\*(C`has_errors\*(C'\fR\fI\fR
242 .IX Subsection "has_errors"
243 .PP
244 .Vb 3
245 \& if ( $parser\->has_errors ) {
246 \& ...
247 \& }
248 .Ve
249 .PP
250 Returns true if \fIany\fR of the parsers failed. This includes:
251 .IP \(bu 4
252 Failed tests
253 .IP \(bu 4
254 Parse errors
255 .IP \(bu 4
256 Bad exit or wait status
257 .PP
258 \fR\f(CI\*(C`todo_failed\*(C'\fR\fI\fR
259 .IX Subsection "todo_failed"
260 .PP
261 .Vb 1
262 \& # deprecated in favor of \*(Aqtodo_passed\*(Aq. This method was horribly misnamed.
263 .Ve
264 .PP
265 This was a badly misnamed method. It indicates which TODO tests unexpectedly
266 succeeded. Will now issue a warning and call \f(CW\*(C`todo_passed\*(C'\fR.
267 .SH "See Also"
268 .IX Header "See Also"
269 TAP::Parser
270 .PP
271 TAP::Harness