--- name: "TAP::Formatter::HTML" section: "3pm" platform: "linux" package: "libtap-formatter-html-perl" version: "0.13+dfsg-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/TAP::Formatter::HTML" --- # TAP::Formatter::HTML(3pm) TAP Test Harness output delegate for html output ## 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 \ 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. If you're using Win32, please see "WIN32 URIS". *js\_uris* ``` $fmt->js_uris( [ \@uris ] ) ``` A list of URIs (or strings) to include as external stylesheets in \ tags in the head of the document. Defaults to: ``` ['file:TAP/Formatter/HTML/default_report.js']; ``` You can set this with the `"TAP_FORMATTER_HTML_JS_URIS=/path/to.js:/another/path.js"` environment variable. If you're using Win32, please see "WIN32 URIS". *inline\_css* ``` $fmt->inline_css( [ $css ] ) ``` If set, the formatter will include the CSS code in a \ tag in the head of the document. *inline\_js* ``` $fmt->inline_js( [ $javascript ] ) ``` If set, the formatter will include the JavaScript code in a \ tag in the head of the document. *minify* ``` $fmt->minify( [ $boolean ] ) ``` 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. *abs\_file\_paths* ``` $fmt->abs_file_paths( [ $ boolean ] ) ``` 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*. *force\_inline\_css* ``` $fmt->force_inline_css( [ $boolean ] ) ``` 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. *force\_inline\_js( \[ $boolean \] )* If set, the formatter will attempt to slurp in any *file* javascript URI's listed in "js\_uris", and append them to "inline\_js". This is handy if you'll be sending the output around - that way you don't have to send javascript files too. Note that including jquery inline doesn't work with some browsers, haven't investigated why. Defaults to *0*. You can set this with the `"TAP_FORMATTER_HTML_FORCE_INLINE_JS=0|1"` environment variable. *color* This method is for `"TAP::Harness"` API compatibility only. It does nothing. ### API METHODS *summary* ``` $html = $fmt->summary( $aggregator ) ``` `"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". ## 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_FORCE_INLINE_JS=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. ## WIN32 URIS This module tries to do the right thing when fed Win32 File *paths* as File URIs to both "css\_uris" and "js\_uris", eg: ``` C:\some\path file:///C:\some\path ``` While I could lecture you what a valid file URI is and point you at: http://blogs.msdn.com/ie/archive/2006/12/06/file-uris-in-windows.aspx Which basically says the above are invalid URIs, and you should use: ``` file:///C:/some/path # ie: no backslashes ``` I also realize it's convenient to chuck in a Win32 file path, as you can on Unix. So if you're running under Win32, `"TAP::Formatter::HTML"` will look for a signature `'X:\'`, `'\'` or `'file:'` at the start of each URI to see if you are referring to a file or another type of URI. Note that you must use '`"file:///C:\blah"`' with *3 slashes* otherwise '`"C:"`' will become your *host*, which is probably not what you want. See URI::file for more details. I realize this is a pretty basic algorithm, but it should handle most cases. If it doesn't work for you, you can always construct a valid File URI instead. ## BUGS Please use http://rt.cpan.org to report any issues. Patches are welcome. ## CONTRIBUTING Use github: \ ## AUTHOR Steve Purkis \ ## COPYRIGHT Copyright (c) 2008-2012 Steve Purkis \, S Purkis Consulting Ltd. All rights reserved. This module is released under the same terms as Perl itself. ## SEE ALSO Examples in the `"examples"` directory and here: \, \, \ prove - TAP::Harness's new cmdline utility. It's great, use it! App::Prove::Plugin::HTML - the prove interface for this module. 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