contrib/kyua/doc/kyua-report.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 1
  30 .Os
  31 .Sh NAME
  32 .Nm "kyua report"
  33 .Nd Generates reports with the results of a test suite run
  34 .Sh SYNOPSIS
  35 .Nm
  36 .Op Fl -output Ar path
  37 .Op Fl -results-file Ar file
  38 .Op Fl -results-filter Ar types
  39 .Op Fl -verbose
  40 .Op Ar test_filter1 .. test_filterN
  41 .Sh DESCRIPTION
  42 The
  43 .Nm
  44 command parses a results file and generates a user-friendly, plaintext
  45 report for user consumption on the terminal.
  46 By default, these reports only display a summary of the execution of the full
  47 test suite to highlight where problems may lie.
  48 .Pp
  49 The output of
  50 .Nm
  51 can be customized to display full details on all executed test cases.
  52 Additionally, the optional arguments to
  53 .Nm
  54 are used to select which test programs or test cases to display.
  55 These are filters and are described below in
  56 .Sx Test filters .
  57 .Pp
  58 Reports generated by
  59 .Nm
  60 are
  61 .Em not intended to be machine-parseable .
  62 .Pp
  63 The following subcommand options are recognized:
  64 .Bl -tag -width XX
  65 .It Fl -output Ar path
  66 Specifies the path to which the report should be written to.
  67 The special values
  68 .Pa /dev/stdout
  69 and
  70 .Pa /dev/stderr
  71 can be used to specify the standard output and the standard error,
  72 respectively.
  73 .It Fl -results-file Ar path , Fl s Ar path
  74 __include__ results-file-flag-read.mdoc
  75 .It Fl -results-filter Ar types
  76 Comma-separated list of the test result types to include in the report.
  77 The ordering of the values is respected so that you can determine how you
  78 want the list of tests to be shown.
  79 .Pp
  80 The valid values are:
  81 .Sq broken ,
  82 .Sq failed ,
  83 .Sq passed ,
  84 .Sq skipped
  85 and
  86 .Sq xfail .
  87 If the parameter supplied to the option is empty, filtering is suppressed
  88 and all result types are shown in the report.
  89 .Pp
  90 The default value for this flag includes all the test results except the
  91 passed tests.
  92 Showing the passed tests by default clutters the report with too much
  93 information, so only abnormal conditions are included.
  94 .It Fl -verbose
  95 Prints a detailed report of the execution.
  96 In addition to all the information printed by default, verbose reports
  97 include the runtime context of the test suite run, the metadata of each
  98 test case, and the verbatim output of the test cases.
  99 .El
 100 .Ss Results files
 101 __include__ results-files.mdoc
 102 .Ss Test filters
 103 __include__ test-filters.mdoc
 104 .Sh EXIT STATUS
 105 The
 106 .Nm
 107 command returns 0 if no filters were specified or if all filters match one
 108 or more test cases.
 109 If any filter fails to match any test case, the command returns 1.
 110 .Pp
 111 Additional exit codes may be returned as described in
 112 .Xr kyua 1 .
 113 .Sh EXAMPLES
 114 __include__ results-files-report-example.mdoc REPORT_COMMAND=report
 115 .Sh SEE ALSO
 116 .Xr kyua 1 ,
 117 .Xr kyua-report-html 1 ,
 118 .Xr kyua-report-junit 1