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