TAP::Formatter::HTML(3pm)

1TAP::Formatter::HTML(3)User Contributed Perl DocumentatioTnAP::Formatter::HTML(3)
2
3
4

NAME

6       TAP::Formatter::HTML - TAP Test Harness output delegate for html output
7

SYNOPSIS

9        # cmdline usage:
10        % prove -m -Q --formatter=TAP::Formatter::HTML >output.html
11
12        # currently in alpha:
13        % prove -PHTML=output.html -m -Q --formatter=TAP::Formatter::HTML
14
15        # perl usage:
16        use TAP::Harness;
17
18        my @tests = glob( 't/*.t' );
19        my $harness = TAP::Harness->new({ formatter_class => 'TAP::Formatter::HTML',
20                                          merge => 1 });
21        $harness->runtests( @tests );
22        # prints HTML to STDOUT by default
23
24        # or if you really don't want STDERR merged in:
25        my $harness = TAP::Harness->new({ formatter_class => 'TAP::Formatter::HTML' });
26
27        # to use a custom formatter:
28        my $fmt = TAP::Formatter::HTML->new;
29        $fmt->css_uris([])->inline_css( $my_css )
30            ->js_uris(['http://mysite.com/jquery.js', 'http://mysite.com/custom.js'])
31            ->inline_js( '$(div.summary).hide()' );
32
33        my $harness = TAP::Harness->new({ formatter => $fmt, merge => 1 });
34
35        # to output HTML to a file[handle]:
36        $fmt->output_fh( $fh );
37        $fmt->output_file( '/tmp/foo.html' );
38
39        # you can use your own customized templates too:
40        $fmt->template('custom.tt2')
41            ->template_processor( Template->new )
42            ->force_inline_css(0);
43

DESCRIPTION

45       This module provides HTML output formatting for TAP::Harness (a
46       replacement for Test::Harness.  It is largely based on ideas from
47       TAP::Test::HTMLMatrix (which was built on Test::Harness and thus had a
48       few limitations - hence this module).  For sample output, see:
49
50       http://www.spurkis.org/TAP-Formatter-HTML/test-output.html
51       <http://www.spurkis.org/TAP-Formatter-HTML/test-output.html>
52
53       This module is targeted at all users of automated test suites.  It's
54       meant to make reading test results easier, giving you a visual summary
55       of your test suite and letting you drill down into individual failures
56       (which will hopefully make testing more likely to happen at your
57       organization ;-).
58
59       The design goals are:
60
61       ·   easy to use
62
63           Once you've got your test report, it should be obvious how to use
64           it.
65
66       ·   helpful
67
68           It should be helpful by pointing out where & why your test suite is
69           breaking.  If you've written your tests well, it should give you
70           enough info to start tracking down the issue.
71
72       ·   easy to install
73
74           Eg: should be a clean install from CPAN, and you shouldn't need to
75           modify your existing test suite to get up & running, though you
76           will need to stop using Test::Harness unfortunately.
77
78       ·   work out of the box
79
80           You shouldn't need to do any custom-coding to get it working - the
81           default configuration & templates should be enough to get started
82           with.  Once installed it should be a matter of running:
83
84            % prove -m -Q --formatter=TAP::Formatter::HTML >output.html
85
86           From your project's home dir, and opening the resulting file.
87
88       ·   easy to configure
89
90           You should be able to configure & customize it to suit your needs.
91           As such, css, javascript and templates are all configurable.
92

METHODS

94   CONSTRUCTOR
95       new( \%args )
96
97   ACCESSORS
98       All chaining accessors:
99
100       verbosity( [ $v ] )
101
102       Verbosity level, as defined in "new" in TAP::Harness:
103
104            1   verbose        Print individual test results (and more) to STDOUT.
105            0   normal
106           -1   quiet          Suppress some test output (eg: test failures).
107           -2   really quiet   Suppress everything to STDOUT but the HTML report.
108           -3   silent         Suppress all output to STDOUT, including the HTML report.
109
110       Note that the report is also available via "html".  You can also
111       provide a custom "output_fh" (aka "output_file") that will be used
112       instead of "stdout", even if silent is on.
113
114       stdout( [ \*FH ] )
115
116       An IO::Handle filehandle for catching standard output.  Defaults to
117       "STDOUT".
118
119       output_fh( [ \*FH ] )
120
121       An IO::Handle filehandle for printing the HTML report to.  Defaults to
122       the same object as "stdout".
123
124       Note: If "silent" is on, printing to "output_fh" will still occur.
125       (that is, assuming you've opened a different file, not "STDOUT").
126
127       output_file( $file_name )
128
129       Not strictly an accessor - this is a shortcut for setting "output_fh",
130       equivalent to:
131
132         $fmt->output_fh( IO::File->new( $file_name, 'w' ) );
133
134       You can set this with the "TAP_FORMATTER_HTML_OUTFILE=/path/to/file"
135       environment variable
136
137       escape_output( [ $boolean ] )
138
139       If set, all output to "stdout" is escaped.  This is probably only
140       useful if you're testing the formatter.  Defaults to 0.
141
142       html( [ \$html ] )
143
144       This is a reference to the scalar containing the html generated on the
145       last test run.  Useful if you have "silent" on, and have not provided a
146       custom "output_fh" to write the report to.
147
148       tests( [ \@test_files ] )
149
150       A list of test files we're running, set by TAP::Parser.
151
152       session_class( [] )
153
154       Class to use for TAP::Parser test sessions.  You probably won't need to
155       use this unless you're hacking or sub-classing the formatter.  Defaults
156       to TAP::Formatter::HTML::Session.
157
158       sessions( [ \@sessions ] )
159
160       Test sessions added by TAP::Parser.  You probably won't need to use
161       this unless you're hacking or sub-classing the formatter.
162
163       template_processor( [ $processor ] )
164
165       The template processor to use.  Defaults to a TT2 Template processor
166       with the following config:
167
168         COMPILE_DIR  => catdir( tempdir(), 'TAP-Formatter-HTML' ),
169         COMPILE_EXT  => '.ttc',
170         INCLUDE_PATH => join(':', @INC),
171
172       template( [ $file_name ] )
173
174       The template file to load.  Defaults to
175       "TAP/Formatter/HTML/default_report.tt2".
176
177       You can set this with the "TAP_FORMATTER_HTML_TEMPLATE=/path/to.tt"
178       environment variable.
179
180       css_uris( [ \@uris ] )
181
182       A list of URIs (or strings) to include as external stylesheets in
183       <style> tags in the head of the document.  Defaults to:
184
185         ['file:TAP/Formatter/HTML/default_report.css'];
186
187       You can set this with the
188       "TAP_FORMATTER_HTML_CSS_URIS=/path/to.css:/another/path.css"
189       environment variable.
190
191       js_uris( [ \@uris ] )
192
193       A list of URIs (or strings) to include as external stylesheets in
194       <style> tags in the head of the document.  Defaults to:
195
196         ['file:TAP/Formatter/HTML/jquery-1.2.6.pack.js'];
197
198       You can set this with the
199       "TAP_FORMATTER_HTML_JS_URIS=/path/to.js:/another/path.js" environment
200       variable.
201
202       inline_css( [ $css ] )
203
204       If set, the formatter will include the CSS code in a <style> tag in the
205       head of the document.
206
207       inline_js( [ $javascript ] )
208
209       If set, the formatter will include the JavaScript code in a <script>
210       tag in the head of the document.
211
212       minify( [ $boolean ] )
213
214       If set, the formatter will attempt to reduce the size of the generated
215       report, they can get pretty big if you're not careful!  Defaults to 1
216       (true).
217
218       Note: This currently just means... remove tabs at start of a line.  It
219       may be extended in the future.
220
221       abs_file_paths( [ $ boolean ] )
222
223       If set, the formatter will attempt to convert any relative file JS &
224       css URI's listed in "css_uris" & "js_uris" to absolute paths.  This is
225       handy if you'll be sending moving the HTML output around on your
226       harddisk, (but not so handy if you move it to another machine - see
227       "force_inline_css").  Defaults to 1.
228
229       force_inline_css( [ $boolean ] )
230
231       If set, the formatter will attempt to slurp in any file css URI's
232       listed in "css_uris", and append them to "inline_css".  This is handy
233       if you'll be sending the output around - that way you don't have to
234       send a CSS file too.  Defaults to 1.
235
236       You can set this with the "TAP_FORMATTER_HTML_FORCE_INLINE_CSS=0|1"
237       environment variable.
238
239   API METHODS
240       $html = $fmt->summary( $aggregator )
241
242       "summary" produces a summary report after all tests are run.
243       $aggregator should be a TAP::Parser::Aggregator.
244
245       This calls:
246
247         $fmt->template_processor->process( $params )
248
249       Where $params is a data structure containing:
250
251         report      => %test_report
252         js_uris     => @js_uris
253         css_uris    => @js_uris
254         inline_js   => $inline_js
255         inline_css  => $inline_css
256         formatter   => %formatter_info
257
258       The "report" is the most complicated data structure, and will sooner or
259       later be documented in "CUSTOMIZING".
260

CUSTOMIZING

262       This section is not yet written.  Please look through the code if you
263       want to customize the templates, or sub-class.
264
265       You can use environment variables to customize the behaviour of TFH:
266
267         TAP_FORMATTER_HTML_OUTFILE=/path/to/file
268         TAP_FORMATTER_HTML_FORCE_INLINE_CSS=0|1
269         TAP_FORMATTER_HTML_CSS_URIS=/path/to.css:/another/path.css
270         TAP_FORMATTER_HTML_JS_URIS=/path/to.js:/another/path.js
271         TAP_FORMATTER_HTML_TEMPLATE=/path/to.tt
272
273       This should save you from having to write custom code for simple cases.
274

BUGS

276       Please use http://rt.cpan.org to report any issues.
277

AUTHOR

279       Steve Purkis <spurkis@cpan.org>
280

COPYRIGHT

282       Copyright (c) 2008 Steve Purkis <spurkis@cpan.org>, S Purkis Consulting
283       Ltd.  All rights reserved.
284
285       This module is released under the same terms as Perl itself.
286