contrib/kyua/doc/kyua-report-html.1.in

   1 .\" Copyright 2012 The Kyua Authors.
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions are
   6 .\" met:
   7 .\"
   8 .\" * Redistributions of source code must retain the above copyright
   9 .\"   notice, this list of conditions and the following disclaimer.
  10 .\" * Redistributions in binary form must reproduce the above copyright
  11 .\"   notice, this list of conditions and the following disclaimer in the
  12 .\"   documentation and/or other materials provided with the distribution.
  13 .\" * Neither the name of Google Inc. nor the names of its contributors
  14 .\"   may be used to endorse or promote products derived from this software
  15 .\"   without specific prior written permission.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  18 .\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  19 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  20 .\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  21 .\" OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  22 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  23 .\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  24 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  25 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  26 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  27 .\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  28 .Dd October 13, 2014
  29 .Dt KYUA-REPORT-HTML 1
  30 .Os
  31 .Sh NAME
  32 .Nm "kyua report-html"
  33 .Nd Generates an HTML report with the results of a test suite run
  34 .Sh SYNOPSIS
  35 .Nm
  36 .Op Fl -force
  37 .Op Fl -output Ar path
  38 .Op Fl -results-file Ar file
  39 .Op Fl -results-filter Ar types
  40 .Sh DESCRIPTION
  41 The
  42 .Nm
  43 command provides a simple mechanism to generate HTML reports of the
  44 execution of a test suite.
  45 The command processes a results file and then populates a directory with
  46 multiple HTML and supporting files to describe the results recorded in that
  47 results file.
  48 .Pp
  49 The HTML output is static and self-contained, so it can easily be served by
  50 any simple web server.
  51 The command expects the target directory to not exist, because it would
  52 overwrite any contents if not careful.
  53 .Pp
  54 The following subcommand options are recognized:
  55 .Bl -tag -width XX
  56 .It Fl -force
  57 Forces the deletion of the output directory if it exists.
  58 Use care, as this effectively means a
  59 .Sq rm -rf .
  60 .It Fl -output Ar directory
  61 Specifies the target directory into which to generate the HTML files.
  62 The directory must not exist unless the
  63 .Fl -force
  64 option is provided.
  65 The default is
  66 .Pa ./html .
  67 .It Fl -results-file Ar path , Fl s Ar path
  68 __include__ results-file-flag-read.mdoc
  69 .It Fl -results-filter Ar types
  70 Comma-separated list of the test result types to include in the report.
  71 The ordering of the values is respected so that you can determine how you
  72 want the list of tests to be shown.
  73 .Pp
  74 The valid values are:
  75 .Sq broken ,
  76 .Sq failed ,
  77 .Sq passed ,
  78 .Sq skipped
  79 and
  80 .Sq xfail .
  81 If the parameter supplied to the option is empty, filtering is suppressed
  82 and all result types are shown in the report.
  83 .Pp
  84 The default value for this flag includes all the test results except the
  85 passed tests.
  86 Showing the passed tests by default clutters the report with too much
  87 information, so only abnormal conditions are included.
  88 .El
  89 .Ss Results files
  90 __include__ results-files.mdoc
  91 .Sh EXIT STATUS
  92 The
  93 .Nm
  94 command always returns 0.
  95 .Pp
  96 Additional exit codes may be returned as described in
  97 .Xr kyua 1 .
  98 .Sh EXAMPLES
  99 __include__ results-files-report-example.mdoc REPORT_COMMAND=report-html
 100 .Sh SEE ALSO
 101 .Xr kyua 1 ,
 102 .Xr kyua-report 1 ,
 103 .Xr kyua-report-junit 1