TAP::F...::HTML(3pm)

📦
version 0.13 · 5 versions
, in debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 TAP::Formatter::HTML 💖

welcome to TAP::Formatter::HTML(3pm) bestie, straight outta the User Contributed Perl Documentation, and lemme tell you, this one is iconic 💅

✨ NAME ✨

TAP::Formatter::HTML — the TAP Test Harness output delegate for HTML output 🎀

like, it takes your test results and turns them into a whole cute HTML report. slay.

🦋 SYNOPSIS 🦋

okay so first up, the command-line vibe (and yes it's alpha, we know 🙈):

##
## 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

and then the perl-side usage, which is the real main character energy:

##
## 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);

periodt. that's the whole vibe check right there 💫

🌸 DESCRIPTION 🌸

so this module gives you HTML output formatting for TAP::Harness (it's a replacement for Test::Harness). it's largely based on ideas from TAP::Test::HTMLMatrix, which was built on Test::Harness and therefore had a few limitations — hence this module existing at all, iykyk 😌. wanna see sample output? it lives at:

<http://www.spurkis.org/TAP-Formatter-HTML/test-output.html>

this module is aimed at everybody who runs an automated test suite. the whole point is to make reading test results easier — you get a visual summary of your suite, and you can drill down into individual failures, which will (hopefully 🙏) make testing more likely to actually happen at your organization ;-)

the design goals, bestie, are these:

  • easy to use — once you've got your test report, it should be obvious how to use it. no cryptic nonsense.
  • helpful — it should be helpful by pointing out where & why your test suite is breaking. and if you've written your tests well, it should give you enough info to start tracking down the issue 🔍
  • easy to install — eg: it 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 unfortunately need to stop using Test::Harness 😭
  • 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 just 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. that's it. that's the whole thing 🫶

  • easy to configure — you should be able to configure & customize it to suit your needs. as such, css, javascript and templates are all configurable. the power. the range. 👑

💅 METHODS 💅

🧚 CONSTRUCTOR

  • new
my $fmt = $class->new({ %args });

boom. that's how you make one. 💖

🎀 ACCESSORS

all of these chain, so you can go absolutely feral with method chaining, bestie:

  • verbosity
$fmt->verbosity( [ $v ] )

the verbosity level, exactly 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.

quick note tho: the report is also available via "html". and you can provide a custom "output_fh" (aka "output_file") that'll be used instead of "stdout", even if silent is on. so you're never actually locked out 💫

  • 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 — it's just 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've got "verbosity" set to "silent" and haven't provided a custom "output_fh" to write the report to. your little secret stash of HTML 🙈

  • tests
$fmt->tests( [ \@test_files ] )

a list of test files we're running, set by TAP::Parser.

  • session_class
$fmt->session_class( [ $class ] )

the class to use for TAP::Parser test sessions. you probably won't need 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 this either 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 this 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 <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.

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 <script> 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 <style> tag in the head of the document. inline slay 💅

  • inline_js
$fmt->inline_js( [ $javascript ] )

if set, the formatter will include the JavaScript code in a <script> 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 — those things 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. for now it's doing its little best 🥺
  • 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 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: 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. it's just there. standing in the corner. existing. 🙈

🌈 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". (we're manifesting that documentation bestie ✨)

🦄 CUSTOMIZING 🦄

this section is not yet written. please look through the code if you want to customize the templates, or sub-class. (lowkey it's all in there, iykyk)

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. obsessed tbh 🫶

🪟 WIN32 URIS 🪟

okay so bestie, this module lowkey tries to do the right thing when you feed it Win32 File paths as File URIs — and it does that for both css_uris and js_uris. like, both. it's giving equal opportunity. for example:

C:\some\path
file:///C:\some\path

now, I could lecture you about what a valid file URI actually is and point you at:

<https://blogs.msdn.com/ie/archive/2006/12/06/file-uris-in-windows.aspx>

which basically says the stuff above is invalid URIs, and that you should really be using:

file:///C:/some/path
# ie: no backslashes

and like, true! valid! iconic even. but I also realize it's convenient to just chuck in a Win32 file path, exactly like 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 figure out whether you're referring to a file or another type of URI. vibe check at the door, basically. 🚪✨

⚠️ 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 fully realize this is a pretty basic algorithm, no cap, but it should handle most cases. and if it doesn't work for you? you can always just construct a valid File URI instead. build it yourself, main character style. 👑

🐛 BUGS 🐛

please use <http://rt.cpan.org> to report any issues. patches are welcome!! 🫶

🤝 CONTRIBUTING 🤝

use github:

<https://github.com/spurkis/TAP-Formatter-HTML>

👑 AUTHOR 👑

Steve Purkis <spurkis@cpan.org>

Copyright (c) 2008-2012 Steve Purkis <spurkis@cpan.org>, S Purkis Consulting Ltd. All rights reserved.

This module is released under the same terms as Perl itself.

👀 SEE ALSO 👀

and that's a wrap bestie!! 🎀 this lil page is from perl v5.36.0, dated 2023-08-11, and it's the TAP::F...::HTML(3pm) manpage from the User Contributed Perl Documentation. go forth and format your TAP in HTML, you absolute icon 💅✨

📦 where this page comes from