minix/external/bsd/atf/dist/atf-report/atf-report.1

.\"
.\" Automated Testing Framework (atf)
.\"
.\" Copyright (c) 2007 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND
.\" CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS BE LIABLE FOR ANY
.\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
.\" GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
.\" IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
.\" IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd December 16, 2011
.Dt ATF-REPORT 1
.Os
.Sh NAME
.Nm atf-report
.Nd transforms the output of atf-run to different formats
.Sh SYNOPSIS
.Nm
.Op Fl o Ar fmt1:path1 Op .. Fl o Ar fmtN:pathN
.Nm
.Fl h
.Sh DESCRIPTION
.Nm
reads the output of
.Nm atf-run
and transforms it to different formats.
Some of these are user-friendly and others are machine-parseable, which
opens a wide range of possibilities to analyze the results of a test
suite's execution.
See
.Sx Output formats
below for more details on which these formats are.
.Pp
In the first synopsis form,
.Nm
reads the output of
.Nm atf-run
through its standard input and, if no
.Fl o
options are given, prints a user-friendly report on its standard
output using the
.Sq ticker
format.
If
.Fl o
options are provided (more than one are allowed), they specify the complete
list of reports to generate.
They are all generated simultaneously, and for obvious reasons, two reports
cannot be written to the same file.
Note that the default output is suppressed when
.Fl o
is provided.
.Pp
In the second synopsis form,
.Nm
will print information about all supported options and their purpose.
.Pp
The following options are available:
.Bl -tag -width XoXfmtXpathXX
.It Fl h
Shows a short summary of all available options and their purpose.
.It Fl o Ar fmt:path
Adds a new output format.
.Ar fmt
is one of the formats described later on in
.Sx Output formats .
.Ar path
specifies where the report will be written to.
Depending on the chosen format, this may refer to a single file or to
a directory.
For those formats that write to a single file, specifying a
.Sq -
as the path will redirect the report to the standard output.
.El
.Ss Output formats
The following output formats are allowed:
.Bl -tag -width tickerXX
.It csv
A machine-parseable Comma-Separated Values (CSV) file.
This file contains the results for all test cases and test programs.
Test cases are logged using the following syntax:
.Bd -literal -offset indent
tc, duration, test-program, test-case, result[, reason]
.Ed
.Pp
The
.Sq result
field for test cases is always one of
.Sq passed ,
.Sq skipped
or
.Sq failed .
The last two are always followed by a reason.
.Pp
Test programs are logged with the following syntax:
.Bd -literal -offset indent
tp, duration, test-program, result[, reason]
.Ed
.Pp
In this case, the
.Sq result
can be one of:
.Sq passed ,
which denotes test programs that ran without any failure;
.Sq failed ,
which refers to test programs in which one or more test cases failed;
or
.Sq bogus ,
which mentions those test programs that failed to execute by some reason.
The reason field is only available in the last case.
.Pp
The time required to execute each test case and test program is
also provided.
You should not rely on the order of the entries in the resulting output.
.It ticker
A user-friendly report that shows the progress of the test suite's
execution as it operates.
This type of report should always be redirected to a virtual terminal,
not a file, as it may use control sequences that will make the output
unreadable in regular files.
.It xml
A report contained in a single XML file.
Ideal for later processing with
.Xr xsltproc 1
to generate nice HTML reports.
.El
.Sh EXAMPLES
The most simple way of running a test suite is to pipe the output of
.Nm atf-run
through
.Nm
without any additional flags.
This will use the default output format, which is suitable to most users:
.Bd -literal -offset indent
atf-run | atf-report
.Ed
.Pp
In some situations, it may be interesting to get a machine-parseable file
aside from the standard report.
This can be done as follows:
.Bd -literal -offset indent
atf-run | atf-report -o csv:testsuite.csv -o ticker:-
.Ed
.Pp
Or if the standard report is not desired, thus achieving completely silent
operation:
atf-run | atf-report -o csv:testsuite.csv
.Sh SEE ALSO
.Xr atf-run 1 ,
.Xr atf 7