NAME
TAP::Formatter::HTML - TAP Test Harness output delegate for html output
SYNOPSIS
##
## command-line usage (alpha):
##
prove -m -Q -P HTML=outfile:out.html,css_uri:style.css,js_uri:foo.js,force_inline_css:0
# backwards compat usage:
prove -m -Q --formatter=TAP::Formatter::HTML >output.html
# for more detail:
perldoc App::Prove::Plugin::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)
->force_inline_js(0);
DESCRIPTION
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:
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:
* *easy to use*
Once you've got your test report, it should be obvious how to use
it.
* *helpful*
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.
* *easy to install*
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*.
* *work out of the box*
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.
* *easy to configure*
You should be able to configure & customize it to suit your needs.
As such, css, javascript and templates are all configurable.
METHODS
CONSTRUCTOR
new
my $fmt = $class->new({ %args });
ACCESSORS
All chaining accessors:
verbosity
$fmt->verbosity( [ $v ] )
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.
stdout
$fmt->stdout( [ \*FH ] );
An IO::Handle filehandle for catching standard output. Defaults to
"STDOUT".
output_fh
$fmt->output_fh( [ \*FH ] );
An IO::Handle filehandle for printing the HTML report to. Defaults to
the same object as "stdout".
Note: If "verbosity" is set to "silent", printing to "output_fh" will
still occur. (that is, assuming you've opened a different file, not
"STDOUT").
output_file
$fmt->output_file( $file_name )
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
escape_output
$fmt->escape_output( [ $boolean ] );
If set, all output to "stdout" is escaped. This is probably only useful
if you're testing the formatter. Defaults to 0.
html
$fmt->html( [ \$html ] );
This is a reference to the scalar containing the html generated on the
last test run. Useful if you have "verbosity" set to "silent", and have
not provided a custom "output_fh" to write the report to.
tests
$fmt->tests( [ \@test_files ] )
A list of test files we're running, set by TAP::Parser.
session_class
$fmt->session_class( [ $class ] )
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.
sessions
$fmt->sessions( [ \@sessions ] )
Test sessions added by TAP::Parser. You probably won't need to use this
unless you're hacking or sub-classing the formatter.
template_processor
$fmt->template_processor( [ $processor ] )
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 => parent directory TAP::Formatter::HTML was loaded from
Note: INCLUDE_PATH used to be set to: "join(':', @INC)" but this was
causing issues on systems with > 64 dirs in @INC. See RT #74364 for
details.
template
$fmt->template( [ $file_name ] )
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.
css_uris
$fmt->css_uris( [ \@uris ] )
A list of URIs (or strings) to include as external stylesheets in