TAP::Formatter::HTML - TAP Test Harness output delegate for html output
# cmdline usage:
% prove -m -Q --formatter=TAP::Formatter::HTML >output.html
# currently in alpha:
% prove -PHTML=output.html -m -Q --formatter=TAP::Formatter::HTML
# perl usage:
use TAP::Harness;
my @tests = glob( 't/*.t' );
my $harness = TAP::Harness->new({ formatter_class => 'TAP::Formatter::HTML',
merge => 1 });
$harness->runtests( @tests );
# prints HTML to STDOUT by default
# or if you really don't want STDERR merged in:
my $harness = TAP::Harness->new({ formatter_class => 'TAP::Formatter::HTML' });
# to use a custom formatter:
my $fmt = TAP::Formatter::HTML->new;
$fmt->css_uris([])->inline_css( $my_css )
->js_uris(['http://mysite.com/jquery.js', 'http://mysite.com/custom.js'])
->inline_js( '$(div.summary).hide()' );
my $harness = TAP::Harness->new({ formatter => $fmt, merge => 1 });
# to output HTML to a file[handle]:
$fmt->output_fh( $fh );
$fmt->output_file( '/tmp/foo.html' );
# you can use your own customized templates too:
$fmt->template('custom.tt2')
->template_processor( Template->new )
->force_inline_css(0);
This module provides HTML output formatting for TAP::Harness (a replacement for Test::Harness. It is largely based on ideas from TAP::Test::HTMLMatrix (which was built on Test::Harness and thus had a few limitations - hence this module). For sample output, see:
http://www.spurkis.org/TAP-Formatter-HTML/test-output.html
This module is targeted at all users of automated test suites. It's meant to make reading test results easier, giving you a visual summary of your test suite and letting you drill down into individual failures (which will hopefully make testing more likely to happen at your organization ;-).
The design goals are:
Once you've got your test report, it should be obvious how to use it.
It should be helpful by pointing out where & why your test suite is breaking. If you've written your tests well, it should give you enough info to start tracking down the issue.
Eg: should be a clean install from CPAN, and you shouldn't need to modify your existing test suite to get up & running, though you will need to stop using Test::Harness unfortunately.
You shouldn't need to do any custom-coding to get it working - the default configuration & templates should be enough to get started with. Once installed it should be a matter of running:
% prove -m -Q --formatter=TAP::Formatter::HTML >output.html
From your project's home dir, and opening the resulting file.
You should be able to configure & customize it to suit your needs. As such, css, javascript and templates are all configurable.
All chaining accessors:
Verbosity level, as defined in "new" in TAP::Harness:
1 verbose Print individual test results (and more) to STDOUT.
0 normal
-1 quiet Suppress some test output (eg: test failures).
-2 really quiet Suppress everything to STDOUT but the HTML report.
-3 silent Suppress all output to STDOUT, including the HTML report.
Note that the report is also available via "html". You can also provide a custom "output_fh" (aka "output_file") that will be used instead of "stdout", even if silent is on.
An IO::Handle filehandle for catching standard output. Defaults to STDOUT.
An IO::Handle filehandle for printing the HTML report to. Defaults to the same object as "stdout".
Note: If "silent" is on, printing to output_fh will still occur. (that is, assuming you've opened a different file, not STDOUT).
Not strictly an accessor - this is a shortcut for setting "output_fh", equivalent to:
$fmt->output_fh( IO::File->new( $file_name, 'w' ) );
You can set this with the TAP_FORMATTER_HTML_OUTFILE=/path/to/file environment variable
If set, all output to "stdout" is escaped. This is probably only useful if you're testing the formatter. Defaults to 0.
This is a reference to the scalar containing the html generated on the last test run. Useful if you have "silent" on, and have not provided a custom "output_fh" to write the report to.
A list of test files we're running, set by TAP::Parser.
Class to use for TAP::Parser test sessions. You probably won't need to use this unless you're hacking or sub-classing the formatter. Defaults to TAP::Formatter::HTML::Session.
Test sessions added by TAP::Parser. You probably won't need to use this unless you're hacking or sub-classing the formatter.
The template processor to use. Defaults to a TT2 Template processor with the following config:
COMPILE_DIR => catdir( tempdir(), 'TAP-Formatter-HTML' ),
COMPILE_EXT => '.ttc',
INCLUDE_PATH => join(':', @INC),
The template file to load. Defaults to TAP/Formatter/HTML/default_report.tt2.
You can set this with the TAP_FORMATTER_HTML_TEMPLATE=/path/to.tt environment variable.
A list of URIs (or strings) to include as external stylesheets in <style> tags in the head of the document. Defaults to:
['file:TAP/Formatter/HTML/default_report.css'];
You can set this with the TAP_FORMATTER_HTML_CSS_URIS=/path/to.css:/another/path.css environment variable.
A list of URIs (or strings) to include as external stylesheets in <style> tags in the head of the document. Defaults to:
['file:TAP/Formatter/HTML/jquery-1.2.6.pack.js'];
You can set this with the TAP_FORMATTER_HTML_JS_URIS=/path/to.js:/another/path.js environment variable.
If set, the formatter will include the CSS code in a <style> tag in the head of the document.
If set, the formatter will include the JavaScript code in a <script> tag in the head of the document.
If set, the formatter will attempt to reduce the size of the generated report, they can get pretty big if you're not careful! Defaults to 1 (true).
Note: This currently just means... remove tabs at start of a line. It may be extended in the future.
If set, the formatter will attempt to convert any relative file JS & css URI's listed in "css_uris" & "js_uris" to absolute paths. This is handy if you'll be sending moving the HTML output around on your harddisk, (but not so handy if you move it to another machine - see "force_inline_css"). Defaults to 1.
If set, the formatter will attempt to slurp in any file css URI's listed in "css_uris", and append them to "inline_css". This is handy if you'll be sending the output around - that way you don't have to send a CSS file too. Defaults to 1.
You can set this with the TAP_FORMATTER_HTML_FORCE_INLINE_CSS=0|1 environment variable.
summary produces a summary report after all tests are run. $aggregator should be a TAP::Parser::Aggregator.
This calls:
$fmt->template_processor->process( $params )
Where $params is a data structure containing:
report => %test_report js_uris => @js_uris css_uris => @js_uris inline_js => $inline_js inline_css => $inline_css formatter => %formatter_info
The report is the most complicated data structure, and will sooner or later be documented in "CUSTOMIZING".
This section is not yet written. Please look through the code if you want to customize the templates, or sub-class.
You can use environment variables to customize the behaviour of TFH:
TAP_FORMATTER_HTML_OUTFILE=/path/to/file TAP_FORMATTER_HTML_FORCE_INLINE_CSS=0|1 TAP_FORMATTER_HTML_CSS_URIS=/path/to.css:/another/path.css TAP_FORMATTER_HTML_JS_URIS=/path/to.js:/another/path.js TAP_FORMATTER_HTML_TEMPLATE=/path/to.tt
This should save you from having to write custom code for simple cases.
Please use http://rt.cpan.org to report any issues.
Steve Purkis <spurkis@cpan.org>
Copyright (c) 2008 Steve Purkis <spurkis@cpan.org>, S Purkis Consulting Ltd. All rights reserved.
This module is released under the same terms as Perl itself.
Examples in the examples directory and here:
http://www.spurkis.org/TAP-Formatter-HTML/test-output.html, http://www.spurkis.org/TAP-Formatter-HTML/DBD-SQLite-example.html, http://www.spurkis.org/TAP-Formatter-HTML/Template-example.html
prove - TAP::Harness's new cmdline utility. It's great, use it!
Test::TAP::HTMLMatrix - the inspiration for this module. Many good ideas were borrowed from it.
TAP::Formatter::Console - the default TAP formatter used by TAP::Harness
