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