ATF-REPORT(1)

NAME
atf-report - Kyua-based implementation of the deprecated atf-report

SYNOPSIS
atf-report [-o fmt1:path1 [.. -o fmtN:pathN]]

DESCRIPTION
DISCLAIMER: This version of atf-report provides a reimplementation of ATF's reporting engine built on top of Kyua. This is a transitional script and should only be considered a helper to migrate away from ATF. Therefore, this version of atf-report mimics the behavior of the original atf-report but NOT the specific output of the command. The output of this implementation is significantly different as that of the original one. Please migrate to using ‘kyua test’ as soon as feasible. See the Migration path section below for further details.

atf-report reads the output of 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 Output formats below for more details on which these formats are.

In the first synopsis form, atf-report reads the output of atf-run through its standard input and, if no -o option is given, prints a user-friendly report on its standard output using the ‘ticker’ format. If the -o option is provided, it specifies the output format to use and its destination.

The following options are available:

-o fmt:path
    Adds a new output format. fmt is one of the formats described later on in Output formats. 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 ‘-’ as the path will redirect the report to the standard output.

  Output formats
The following output formats are allowed:

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.

html
    A multi-file HTML report. The specified output file will be a symlink into a directory containing all the other support files for the HTML report.

    This format was not originally supported by atf-report, but is the right name for the compatibility ‘xml’ support.

xml A compatibility name for ‘html’. The original atf-report was only able to generate XML reports and relied on tools like xsltproc(1) to convert them to HTML. The process was quite convoluted and inconvenient. Kyua, on the other hand, is only able to create HTML reports at the moment.

  Migration path
Moving from atf-report to ‘kyua report’ is rather simple.

The most important thing to understand during the transition is that ‘kyua test’ stores the output of the execution in a database and does not print a machine-parseable log to its stdout. Instead, ‘kyua report’ is used as a second step to extract reports from the database for any previously executed test.

The following examples show how to convert some common atf-report invocations to their corresponding ‘kyua report’ ones. Because atf-report has always been tied to atf-run(1), these examples also mention the latter.

    ### Run all tests, with a summary at the end.
    $ atf-run | atf-report
    $ kyua test && kyua report
    ### Generate a HTML report.
    $ atf-run | atf-report -o xml:report.xml
      ... plus some complex file manipulation and xsltproc magic ...
    $ kyua test && kyua report-html -o path/to/report/

SEE ALSO
kyua(1), atf-run(1)