1TAP::Formatter::HTML(3)User Contributed Perl DocumentatioTnAP::Formatter::HTML(3)
2
3
4
6 TAP::Formatter::HTML - TAP Test Harness output delegate for html output
7
9 ##
10 ## command-line usage (alpha):
11 ##
12 prove -m -Q -P HTML=outfile:out.html,css_uri:style.css,js_uri:foo.js,force_inline_css:0
13
14 # backwards compat usage:
15 prove -m -Q --formatter=TAP::Formatter::HTML >output.html
16
17 # for more detail:
18 perldoc App::Prove::Plugin::HTML
19
20 ##
21 ## perl usage:
22 ##
23 use TAP::Harness;
24
25 my @tests = glob( 't/*.t' );
26 my $harness = TAP::Harness->new({ formatter_class => 'TAP::Formatter::HTML',
27 merge => 1 });
28 $harness->runtests( @tests );
29 # prints HTML to STDOUT by default
30
31 # or if you really don't want STDERR merged in:
32 my $harness = TAP::Harness->new({ formatter_class => 'TAP::Formatter::HTML' });
33
34 # to use a custom formatter:
35 my $fmt = TAP::Formatter::HTML->new;
36 $fmt->css_uris([])->inline_css( $my_css )
37 ->js_uris(['http://mysite.com/jquery.js', 'http://mysite.com/custom.js'])
38 ->inline_js( '$(div.summary).hide()' );
39
40 my $harness = TAP::Harness->new({ formatter => $fmt, merge => 1 });
41
42 # to output HTML to a file[handle]:
43 $fmt->output_fh( $fh );
44 $fmt->output_file( '/tmp/foo.html' );
45
46 # you can use your own customized templates too:
47 $fmt->template('custom.tt2')
48 ->template_processor( Template->new )
49 ->force_inline_css(0)
50 ->force_inline_js(0);
51
53 This module provides HTML output formatting for TAP::Harness (a
54 replacement for Test::Harness. It is largely based on ideas from
55 TAP::Test::HTMLMatrix (which was built on Test::Harness and thus had a
56 few limitations - hence this module). For sample output, see:
57
58 <http://www.spurkis.org/TAP-Formatter-HTML/test-output.html>
59
60 This module is targeted at all users of automated test suites. It's
61 meant to make reading test results easier, giving you a visual summary
62 of your test suite and letting you drill down into individual failures
63 (which will hopefully make testing more likely to happen at your
64 organization ;-).
65
66 The design goals are:
67
68 • easy to use
69
70 Once you've got your test report, it should be obvious how to use
71 it.
72
73 • helpful
74
75 It should be helpful by pointing out where & why your test suite is
76 breaking. If you've written your tests well, it should give you
77 enough info to start tracking down the issue.
78
79 • easy to install
80
81 Eg: should be a clean install from CPAN, and you shouldn't need to
82 modify your existing test suite to get up & running, though you
83 will need to stop using Test::Harness unfortunately.
84
85 • work out of the box
86
87 You shouldn't need to do any custom-coding to get it working - the
88 default configuration & templates should be enough to get started
89 with. Once installed it should be a matter of running:
90
91 % prove -m -Q --formatter=TAP::Formatter::HTML >output.html
92
93 From your project's home dir, and opening the resulting file.
94
95 • easy to configure
96
97 You should be able to configure & customize it to suit your needs.
98 As such, css, javascript and templates are all configurable.
99
101 CONSTRUCTOR
102 new
103
104 my $fmt = $class->new({ %args });
105
106 ACCESSORS
107 All chaining accessors:
108
109 verbosity
110
111 $fmt->verbosity( [ $v ] )
112
113 Verbosity level, as defined in "new" in TAP::Harness:
114
115 1 verbose Print individual test results (and more) to STDOUT.
116 0 normal
117 -1 quiet Suppress some test output (eg: test failures).
118 -2 really quiet Suppress everything to STDOUT but the HTML report.
119 -3 silent Suppress all output to STDOUT, including the HTML report.
120
121 Note that the report is also available via "html". You can also
122 provide a custom "output_fh" (aka "output_file") that will be used
123 instead of "stdout", even if silent is on.
124
125 stdout
126
127 $fmt->stdout( [ \*FH ] );
128
129 An IO::Handle filehandle for catching standard output. Defaults to
130 "STDOUT".
131
132 output_fh
133
134 $fmt->output_fh( [ \*FH ] );
135
136 An IO::Handle filehandle for printing the HTML report to. Defaults to
137 the same object as "stdout".
138
139 Note: If "verbosity" is set to "silent", printing to "output_fh" will
140 still occur. (that is, assuming you've opened a different file, not
141 "STDOUT").
142
143 output_file
144
145 $fmt->output_file( $file_name )
146
147 Not strictly an accessor - this is a shortcut for setting "output_fh",
148 equivalent to:
149
150 $fmt->output_fh( IO::File->new( $file_name, 'w' ) );
151
152 You can set this with the "TAP_FORMATTER_HTML_OUTFILE=/path/to/file"
153 environment variable
154
155 escape_output
156
157 $fmt->escape_output( [ $boolean ] );
158
159 If set, all output to "stdout" is escaped. This is probably only
160 useful if you're testing the formatter. Defaults to 0.
161
162 html
163
164 $fmt->html( [ \$html ] );
165
166 This is a reference to the scalar containing the html generated on the
167 last test run. Useful if you have "verbosity" set to "silent", and
168 have not provided a custom "output_fh" to write the report to.
169
170 tests
171
172 $fmt->tests( [ \@test_files ] )
173
174 A list of test files we're running, set by TAP::Parser.
175
176 session_class
177
178 $fmt->session_class( [ $class ] )
179
180 Class to use for TAP::Parser test sessions. You probably won't need to
181 use this unless you're hacking or sub-classing the formatter. Defaults
182 to TAP::Formatter::HTML::Session.
183
184 sessions
185
186 $fmt->sessions( [ \@sessions ] )
187
188 Test sessions added by TAP::Parser. You probably won't need to use
189 this unless you're hacking or sub-classing the formatter.
190
191 template_processor
192
193 $fmt->template_processor( [ $processor ] )
194
195 The template processor to use. Defaults to a TT2 Template processor
196 with the following config:
197
198 COMPILE_DIR => catdir( tempdir(), 'TAP-Formatter-HTML' ),
199 COMPILE_EXT => '.ttc',
200 INCLUDE_PATH => parent directory TAP::Formatter::HTML was loaded from
201
202 Note: INCLUDE_PATH used to be set to: "join(':', @INC)" but this was
203 causing issues on systems with > 64 dirs in @INC. See RT #74364 for
204 details.
205
206 template
207
208 $fmt->template( [ $file_name ] )
209
210 The template file to load. Defaults to
211 "TAP/Formatter/HTML/default_report.tt2".
212
213 You can set this with the "TAP_FORMATTER_HTML_TEMPLATE=/path/to.tt"
214 environment variable.
215
216 css_uris
217
218 $fmt->css_uris( [ \@uris ] )
219
220 A list of URIs (or strings) to include as external stylesheets in
221 <style> tags in the head of the document. Defaults to:
222
223 ['file:TAP/Formatter/HTML/default_report.css'];
224
225 You can set this with the
226 "TAP_FORMATTER_HTML_CSS_URIS=/path/to.css:/another/path.css"
227 environment variable.
228
229 If you're using Win32, please see "WIN32 URIS".
230
231 js_uris
232
233 $fmt->js_uris( [ \@uris ] )
234
235 A list of URIs (or strings) to include as external stylesheets in
236 <script> tags in the head of the document. Defaults to:
237
238 ['file:TAP/Formatter/HTML/jquery-1.2.6.pack.js'];
239
240 You can set this with the
241 "TAP_FORMATTER_HTML_JS_URIS=/path/to.js:/another/path.js" environment
242 variable.
243
244 If you're using Win32, please see "WIN32 URIS".
245
246 inline_css
247
248 $fmt->inline_css( [ $css ] )
249
250 If set, the formatter will include the CSS code in a <style> tag in the
251 head of the document.
252
253 inline_js
254
255 $fmt->inline_js( [ $javascript ] )
256
257 If set, the formatter will include the JavaScript code in a <script>
258 tag in the head of the document.
259
260 minify
261
262 $fmt->minify( [ $boolean ] )
263
264 If set, the formatter will attempt to reduce the size of the generated
265 report, they can get pretty big if you're not careful! Defaults to 1
266 (true).
267
268 Note: This currently just means... remove tabs at start of a line. It
269 may be extended in the future.
270
271 abs_file_paths
272
273 $fmt->abs_file_paths( [ $ boolean ] )
274
275 If set, the formatter will attempt to convert any relative file JS &
276 css URI's listed in "css_uris" & "js_uris" to absolute paths. This is
277 handy if you'll be sending moving the HTML output around on your
278 harddisk, (but not so handy if you move it to another machine - see
279 "force_inline_css"). Defaults to 1.
280
281 force_inline_css
282
283 $fmt->force_inline_css( [ $boolean ] )
284
285 If set, the formatter will attempt to slurp in any file css URI's
286 listed in "css_uris", and append them to "inline_css". This is handy
287 if you'll be sending the output around - that way you don't have to
288 send a CSS file too. Defaults to 1.
289
290 You can set this with the "TAP_FORMATTER_HTML_FORCE_INLINE_CSS=0|1"
291 environment variable.
292
293 force_inline_js( [ $boolean ] )
294
295 If set, the formatter will attempt to slurp in any file javascript
296 URI's listed in "js_uris", and append them to "inline_js". This is
297 handy if you'll be sending the output around - that way you don't have
298 to send javascript files too.
299
300 Note that including jquery inline doesn't work with some browsers,
301 haven't investigated why. Defaults to 0.
302
303 You can set this with the "TAP_FORMATTER_HTML_FORCE_INLINE_JS=0|1"
304 environment variable.
305
306 color
307
308 This method is for "TAP::Harness" API compatibility only. It does
309 nothing.
310
311 API METHODS
312 summary
313
314 $html = $fmt->summary( $aggregator )
315
316 "summary" produces a summary report after all tests are run.
317 $aggregator should be a TAP::Parser::Aggregator.
318
319 This calls:
320
321 $fmt->template_processor->process( $params )
322
323 Where $params is a data structure containing:
324
325 report => %test_report
326 js_uris => @js_uris
327 css_uris => @js_uris
328 inline_js => $inline_js
329 inline_css => $inline_css
330 formatter => %formatter_info
331
332 The "report" is the most complicated data structure, and will sooner or
333 later be documented in "CUSTOMIZING".
334
336 This section is not yet written. Please look through the code if you
337 want to customize the templates, or sub-class.
338
339 You can use environment variables to customize the behaviour of TFH:
340
341 TAP_FORMATTER_HTML_OUTFILE=/path/to/file
342 TAP_FORMATTER_HTML_FORCE_INLINE_CSS=0|1
343 TAP_FORMATTER_HTML_FORCE_INLINE_JS=0|1
344 TAP_FORMATTER_HTML_CSS_URIS=/path/to.css:/another/path.css
345 TAP_FORMATTER_HTML_JS_URIS=/path/to.js:/another/path.js
346 TAP_FORMATTER_HTML_TEMPLATE=/path/to.tt
347
348 This should save you from having to write custom code for simple cases.
349
351 This module tries to do the right thing when fed Win32 File paths as
352 File URIs to both "css_uris" and "js_uris", eg:
353
354 C:\some\path
355 file:///C:\some\path
356
357 While I could lecture you what a valid file URI is and point you at:
358
359 http://blogs.msdn.com/ie/archive/2006/12/06/file-uris-in-windows.aspx
360
361 Which basically says the above are invalid URIs, and you should use:
362
363 file:///C:/some/path
364 # ie: no backslashes
365
366 I also realize it's convenient to chuck in a Win32 file path, as you
367 can on Unix. So if you're running under Win32, "TAP::Formatter::HTML"
368 will look for a signature 'X:\', '\' or 'file:' at the start of each
369 URI to see if you are referring to a file or another type of URI.
370
371 Note that you must use '"file:///C:\blah"' with 3 slashes otherwie
372 '"C:"' will become your host, which is probably not what you want. See
373 URI::file for more details.
374
375 I realize this is a pretty basic algorithm, but it should handle most
376 cases. If it doesn't work for you, you can always construct a valid
377 File URI instead.
378
380 Please use http://rt.cpan.org to report any issues. Patches are
381 welcome.
382
384 Use github:
385
386 <https://github.com/spurkis/TAP-Formatter-HTML>
387
389 Steve Purkis <spurkis@cpan.org>
390
392 Copyright (c) 2008-2012 Steve Purkis <spurkis@cpan.org>, S Purkis
393 Consulting Ltd. All rights reserved.
394
395 This module is released under the same terms as Perl itself.
396
398 Examples in the "examples" directory and here:
399
400 <http://www.spurkis.org/TAP-Formatter-HTML/test-output.html>,
401 <http://www.spurkis.org/TAP-Formatter-HTML/DBD-SQLite-example.html>,
402 <http://www.spurkis.org/TAP-Formatter-HTML/Template-example.html>
403
404 prove - TAP::Harness's new cmdline utility. It's great, use it!
405
406 App::Prove::Plugin::HTML - the prove interface for this module.
407
408 Test::TAP::HTMLMatrix - the inspiration for this module. Many good
409 ideas were borrowed from it.
410
411 TAP::Formatter::Console - the default TAP formatter used by
412 TAP::Harness
413
414
415
416perl v5.36.0 2022-07-22 TAP::Formatter::HTML(3)