| blob | 0407526ffd01039e1fee9c60f047563be0ef30fc |
1 .\" Copyright 2012 Google Inc.
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 June 16, 2012
29 .Dt ATF-REPORT 1
30 .Os
31 .Sh NAME
32 .Nm atf-report
33 .Nd Kyua-based implementation of the deprecated atf-report
34 .Sh SYNOPSIS
35 .Nm
36 .Op Fl o Ar fmt1:path1 Op .. Fl o Ar fmtN:pathN
37 .Sh DESCRIPTION
38 .Em DISCLAIMER :
39 This version of
40 .Nm
41 provides a reimplementation of ATF's reporting engine built on top of Kyua.
42 This is a transitional script and should only be considered a helper to
43 migrate away from ATF.
44 Therefore, this version of
45 .Nm
46 mimics the
47 .Em behavior
48 of the original
49 .Nm
50 but
51 .Em NOT
52 the specific output of the command.
53 The output of this implementation is significantly different as that of the
54 original one.
55 Please migrate to using
56 .Sq kyua test
57 as soon as feasible.
58 See the
59 .Sx Migration path
60 section below for further details.
61 .Pp
62 .Nm
63 reads the output of
64 .Nm atf-run
65 and transforms it to different formats.
66 Some of these are user-friendly and others are machine-parseable, which
67 opens a wide range of possibilities to analyze the results of a test
68 suite's execution.
69 See
70 .Sx Output formats
71 below for more details on which these formats are.
72 .Pp
73 In the first synopsis form,
74 .Nm
75 reads the output of
76 .Nm atf-run
77 through its standard input and, if no
78 .Fl o
79 option is given, prints a user-friendly report on its standard
80 output using the
81 .Sq ticker
82 format.
83 If the
84 .Fl o
85 option is provided, it specifies the output format to use and its
86 destination.
87 .Pp
88 The following options are available:
89 .Bl -tag -width XoXfmtXpathXX
90 .It Fl o Ar fmt:path
91 Adds a new output format.
92 .Ar fmt
93 is one of the formats described later on in
94 .Sx Output formats .
95 .Ar path
96 specifies where the report will be written to.
97 Depending on the chosen format, this may refer to a single file or to
98 a directory.
99 For those formats that write to a single file, specifying a
100 .Sq -
101 as the path will redirect the report to the standard output.
102 .El
103 .Ss Output formats
104 The following output formats are allowed:
105 .Bl -tag -width tickerXX
106 .It ticker
107 A user-friendly report that shows the progress of the test suite's
108 execution as it operates.
109 This type of report should always be redirected to a virtual terminal,
110 not a file, as it may use control sequences that will make the output
111 unreadable in regular files.
112 .It html
113 A multi-file HTML report.
114 The specified output file will be a symlink into a directory containing
115 all the other support files for the HTML report.
116 .Pp
117 This format was not originally supported by
118 .Nm ,
119 but is the right name for the compatibility
120 .Sq xml
121 support.
122 .It xml
123 A compatibility name for
124 .Sq html .
125 The original
126 .Nm
127 was only able to generate XML reports and relied on tools like
128 .Xr xsltproc 1
129 to convert them to HTML.
130 The process was quite convoluted and inconvenient.
131 Kyua, on the other hand, is only able to create HTML reports at the
132 moment.
133 .El
134 .Pp
135 .Ss Migration path
136 Moving from
137 .Nm
138 to
139 .Sq kyua report
140 is rather simple.
141 .Pp
142 The most important thing to understand during the transition is that
143 .Sq kyua test
144 stores the output of the execution in a database and does not print a
145 machine-parseable log to its stdout.
146 Instead,
147 .Sq kyua report
148 is used as a second step to extract reports from the database for any
149 previously executed test.
150 .Pp
151 The following examples show how to convert some common
152 .Nm
153 invocations to their corresponding
154 .Sq kyua report
155 ones.
156 Because
157 .Nm
158 has always been tied to
159 .Xr atf-run 1 ,
160 these examples also mention the latter.
161 .Bd -literal -offset indent
162 ### Run all tests, with a summary at the end.
163 $ atf-run | atf-report
164 $ kyua test && kyua report
166 ### Generate a HTML report.
167 $ atf-run | atf-report -o xml:report.xml
168 ... plus some complex file manipulation and xsltproc magic ...
169 $ kyua test && kyua report-html -o path/to/report/
170 .Ed
171 .Sh SEE ALSO
172 .Xr kyua 1 ,
173 .Xr atf-run 1