1.\" Copyright 2012 The Kyua Authors. 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 October 13, 2014 29.Dt KYUA-REPORT 1 30.Os 31.Sh NAME 32.Nm "kyua report" 33.Nd Generates reports with the results of a test suite run 34.Sh SYNOPSIS 35.Nm 36.Op Fl -output Ar path 37.Op Fl -results-file Ar file 38.Op Fl -results-filter Ar types 39.Op Fl -verbose 40.Op Ar test_filter1 .. test_filterN 41.Sh DESCRIPTION 42The 43.Nm 44command parses a results file and generates a user-friendly, plaintext 45report for user consumption on the terminal. 46By default, these reports only display a summary of the execution of the full 47test suite to highlight where problems may lie. 48.Pp 49The output of 50.Nm 51can be customized to display full details on all executed test cases. 52Additionally, the optional arguments to 53.Nm 54are used to select which test programs or test cases to display. 55These are filters and are described below in 56.Sx Test filters . 57.Pp 58Reports generated by 59.Nm 60are 61.Em not intended to be machine-parseable . 62.Pp 63The following subcommand options are recognized: 64.Bl -tag -width XX 65.It Fl -output Ar path 66Specifies the path to which the report should be written to. 67The special values 68.Pa /dev/stdout 69and 70.Pa /dev/stderr 71can be used to specify the standard output and the standard error, 72respectively. 73.It Fl -results-file Ar path , Fl s Ar path 74__include__ results-file-flag-read.mdoc 75.It Fl -results-filter Ar types 76Comma-separated list of the test result types to include in the report. 77The ordering of the values is respected so that you can determine how you 78want the list of tests to be shown. 79.Pp 80The valid values are: 81.Sq broken , 82.Sq failed , 83.Sq passed , 84.Sq skipped 85and 86.Sq xfail . 87If the parameter supplied to the option is empty, filtering is suppressed 88and all result types are shown in the report. 89.Pp 90The default value for this flag includes all the test results except the 91passed tests. 92Showing the passed tests by default clutters the report with too much 93information, so only abnormal conditions are included. 94.It Fl -verbose 95Prints a detailed report of the execution. 96In addition to all the information printed by default, verbose reports 97include the runtime context of the test suite run, the metadata of each 98test case, and the verbatim output of the test cases. 99.El 100.Ss Results files 101__include__ results-files.mdoc 102.Ss Test filters 103__include__ test-filters.mdoc 104.Sh EXIT STATUS 105The 106.Nm 107command returns 0 if no filters were specified or if all filters match one 108or more test cases. 109If any filter fails to match any test case, the command returns 1. 110.Pp 111Additional exit codes may be returned as described in 112.Xr kyua 1 . 113.Sh EXAMPLES 114__include__ results-files-report-example.mdoc REPORT_COMMAND=report 115.Sh SEE ALSO 116.Xr kyua 1 , 117.Xr kyua-report-html 1 , 118.Xr kyua-report-junit 1 119