Linux Certif

Toute la documentation sur la certification Linux LPI

TAP::Formatter::HTML.3pm

NAME

TAP::Formatter::HTML - TAP Test Harness output delegate for html output

SYNOPSIS

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

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:

http://www.spurkis.org/TAP-Formatter-HTML/test-output.html <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:

*

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( \%args )

ACCESSORS

All chaining accessors:

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( [ \*FH ] )

An IO::Handle filehandle for catching standard output. Defaults to "STDOUT".

output_fh( [ \*FH ] )

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").

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( [ $boolean ] )

If set, all output to ``stdout'' is escaped. This is probably only useful if you're testing the formatter. Defaults to 0.

html( [ \$html ] )

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.

tests( [ \@test_files ] )

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

session_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( [ \@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( [ $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 => join(':', @INC),
 
 

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( [ \@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.

js_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/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.

inline_css( [ $css ] )

If set, the formatter will include the CSS code in a <style> tag in the head of the document.

inline_js( [ $javascript ] )

If set, the formatter will include the JavaScript code in a <script> tag in the head of the document.

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( [ $ 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( [ $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.

API METHODS

$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_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.

BUGS

Please use http://rt.cpan.org to report any issues.

AUTHOR

Steve Purkis <spurkis@cpan.org>

COPYRIGHT

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.

SEE ALSO

Examples in the "examples" directory and here:

http://www.spurkis.org/TAP-Formatter-HTML/test-output.html <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/DBD-SQLite-example.html>, http://www.spurkis.org/TAP-Formatter-HTML/Template-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