contrib/atf/atf-report/atf-report.1

   1 .\"
   2 .\" Automated Testing Framework (atf)
   3 .\"
   4 .\" Copyright (c) 2007 The NetBSD Foundation, Inc.
   5 .\" All rights reserved.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND
  17 .\" CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
  18 .\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
  19 .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  20 .\" IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS BE LIABLE FOR ANY
  21 .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  22 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
  23 .\" GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  24 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
  25 .\" IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  26 .\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
  27 .\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  28 .\"
  29 .Dd December 16, 2011
  30 .Dt ATF-REPORT 1
  31 .Os
  32 .Sh NAME
  33 .Nm atf-report
  34 .Nd transforms the output of atf-run to different formats
  35 .Sh SYNOPSIS
  36 .Nm
  37 .Op Fl o Ar fmt1:path1 Op .. Fl o Ar fmtN:pathN
  38 .Nm
  39 .Fl h
  40 .Sh DESCRIPTION
  41 .Nm
  42 reads the output of
  43 .Nm atf-run
  44 and transforms it to different formats.
  45 Some of these are user-friendly and others are machine-parseable, which
  46 opens a wide range of possibilities to analyze the results of a test
  47 suite's execution.
  48 See
  49 .Sx Output formats
  50 below for more details on which these formats are.
  51 .Pp
  52 In the first synopsis form,
  53 .Nm
  54 reads the output of
  55 .Nm atf-run
  56 through its standard input and, if no
  57 .Fl o
  58 options are given, prints a user-friendly report on its standard
  59 output using the
  60 .Sq ticker
  61 format.
  62 If
  63 .Fl o
  64 options are provided (more than one are allowed), they specify the complete
  65 list of reports to generate.
  66 They are all generated simultaneously, and for obvious reasons, two reports
  67 cannot be written to the same file.
  68 Note that the default output is suppressed when
  69 .Fl o
  70 is provided.
  71 .Pp
  72 In the second synopsis form,
  73 .Nm
  74 will print information about all supported options and their purpose.
  75 .Pp
  76 The following options are available:
  77 .Bl -tag -width XoXfmtXpathXX
  78 .It Fl h
  79 Shows a short summary of all available options and their purpose.
  80 .It Fl o Ar fmt:path
  81 Adds a new output format.
  82 .Ar fmt
  83 is one of the formats described later on in
  84 .Sx Output formats .
  85 .Ar path
  86 specifies where the report will be written to.
  87 Depending on the chosen format, this may refer to a single file or to
  88 a directory.
  89 For those formats that write to a single file, specifying a
  90 .Sq -
  91 as the path will redirect the report to the standard output.
  92 .El
  93 .Ss Output formats
  94 The following output formats are allowed:
  95 .Bl -tag -width tickerXX
  96 .It csv
  97 A machine-parseable Comma-Separated Values (CSV) file.
  98 This file contains the results for all test cases and test programs.
  99 Test cases are logged using the following syntax:
 100 .Bd -literal -offset indent
 101 tc, duration, test-program, test-case, result[, reason]
 102 .Ed
 103 .Pp
 104 The
 105 .Sq result
 106 field for test cases is always one of
 107 .Sq passed ,
 108 .Sq skipped
 109 or
 110 .Sq failed .
 111 The last two are always followed by a reason.
 112 .Pp
 113 Test programs are logged with the following syntax:
 114 .Bd -literal -offset indent
 115 tp, duration, test-program, result[, reason]
 116 .Ed
 117 .Pp
 118 In this case, the
 119 .Sq result
 120 can be one of:
 121 .Sq passed ,
 122 which denotes test programs that ran without any failure;
 123 .Sq failed ,
 124 which refers to test programs in which one or more test cases failed;
 125 or
 126 .Sq bogus ,
 127 which mentions those test programs that failed to execute by some reason.
 128 The reason field is only available in the last case.
 129 .Pp
 130 The time required to execute each test case and test program is
 131 also provided.
 132 You should not rely on the order of the entries in the resulting output.
 133 .It ticker
 134 A user-friendly report that shows the progress of the test suite's
 135 execution as it operates.
 136 This type of report should always be redirected to a virtual terminal,
 137 not a file, as it may use control sequences that will make the output
 138 unreadable in regular files.
 139 .It xml
 140 A report contained in a single XML file.
 141 Ideal for later processing with
 142 .Xr xsltproc 1
 143 to generate nice HTML reports.
 144 .El
 145 .Sh EXAMPLES
 146 The most simple way of running a test suite is to pipe the output of
 147 .Nm atf-run
 148 through
 149 .Nm
 150 without any additional flags.
 151 This will use the default output format, which is suitable to most users:
 152 .Bd -literal -offset indent
 153 atf-run | atf-report
 154 .Ed
 155 .Pp
 156 In some situations, it may be interesting to get a machine-parseable file
 157 aside from the standard report.
 158 This can be done as follows:
 159 .Bd -literal -offset indent
 160 atf-run | atf-report -o csv:testsuite.csv -o ticker:-
 161 .Ed
 162 .Pp
 163 Or if the standard report is not desired, thus achieving completely silent
 164 operation:
 165 atf-run | atf-report -o csv:testsuite.csv
 166 .Sh SEE ALSO
 167 .Xr atf-run 1 ,
 168 .Xr atf 7