doc/dejagnu-report-card.1

   1 .\" Copyright (C) 2018  Free Software Foundation, Inc.
   2 .\" You may distribute this file under the terms of the GNU Free
   3 .\" Documentation License.
   4 .Dd December 31, 2018
   5 .Os GNU
   6 .Dt DEJAGNU-REPORT-CARD 1 URM
   7 .Sh NAME
   8 .Nm dejagnu\ report\ card
   9 .Nd summarize results from testing multiple tools
  10 .Sh SYNOPSIS
  11 .Nm dejagnu\ report\ card
  12 .Oo Ao Ar option Ac \*(Ba Ao Ar tool Ac \*(Ba Ao Ar file Ac Oc ...
  13 .Sh DESCRIPTION
  14 The
  15 .Nm
  16 command displays results from testing multiple tools in a tabular format.
  17 The produced table lists, for each tool (and if multiple passes were run,
  18 each pass) the number of tests passed, failed, unsupported, unresolved, and
  19 untested.  Tests that are expected to fail are counted in separate columns
  20 from tests expected to pass, but "known" failures and "expected" failures
  21 are summarized together.  If a test generated warnings or errors, a tag
  22 .Ql !W!
  23 or
  24 .Ql !E!
  25 is appended at the end of the relevant line.
  26 .Pp
  27 Aside from options, the argument list may include tool or file names.  The
  28 .Nm
  29 command prefers to read DejaGnu summary files and will translate names accordingly:
  30 .Bl -tag -width ".Pa *.sum"
  31 .It Pa *.sum
  32 Used as-is.
  33 .It Pa *.log
  34 Rewritten to
  35 .Pa *.sum
  36 with the same stem.
  37 .It Pa *.
  38 The string
  39 .Pa sum
  40 is appended to select a summary file.  This processing is done for
  41 convenience when using Readline file name completion in a shell, which will
  42 complete to the dot.
  43 .It Pa *
  44 Taken as a tool name;
  45 .Pa .sum
  46 is appended.
  47 .El
  48 .Sh OPTIONS
  49 .Bl -tag -width ".Fl v , -verbose"
  50 .It Fl v , -verbose
  51 Emit additional output describing the operation of
  52 .Nm
  53 itself.
  54 .El
  55 .Sh FILES
  56 The
  57 .Nm
  58 command produces its output by reading the summary files produced by
  59 DejaGnu and counting "PASS", "FAIL", etc.
  60 .Pp
  61 If no names are given as arguments, all files matching
  62 .Pa *.sum
  63 in the current directory are read.
  64 .Sh EXAMPLES
  65 .Ss A simple example from DejaGnu's own testsuite
  66 .Bd -literal
  67 $ dejagnu report card
  68 \             __________________________________________________
  69 \            /    PASS   FAIL  ?PASS  ?FAIL  UNSUP  UNRES UNTEST
  70 \            |--------------------------------------------------
  71 \  launcher  |      52      0      0      0      0      0      0
  72 libdejagnu  |       5      0      0      0      0      0      0
  73 \   runtest  |     135      0      0      0      0      0      0
  74 \            |--------------------------------------------------
  75 \            |     192      0      0      0      0      0      0
  76 \            \\__________________________________________________
  77 .Ed
  78 .Pp
  79 Three tools were tested, with a total of 192 tests, all expected to pass.
  80 In this example, all tests did pass, so all other columns are zero.  The
  81 .Ql ?PASS
  82 and
  83 .Ql ?FAIL
  84 columns count tests known or expected to fail that either unexpectedly
  85 passed or failed as expected.  The remaining three columns count the
  86 exceptional results for unsupported tests, unresolved tests and stub tests
  87 that simply declare themselves untested.
  88 .Pp
  89 .ne 16v
  90 .Ss The same example after tests were added for dejagnu-report-card
  91 .Bd -literal
  92 $ dejagnu report-card
  93 \                    __________________________________________________
  94 \                   /    PASS   FAIL  ?PASS  ?FAIL  UNSUP  UNRES UNTEST
  95 \                   |--------------------------------------------------
  96 \   launcher        |      52      0      0      0      0      0      0
  97 \ libdejagnu        |       5      0      0      0      0      0      0
  98 report-card / awk  |      36      0      0      0      0      0      0
  99 report-card / sh   |      36      0      0      0      0      0      0
 100 report-card / tcl  |      36      0      0      0      0      0      0
 101 \    runtest        |     135      0      0      0      0      0      0
 102 \                   |--------------------------------------------------
 103 \              awk  |      36      0      0      0      0      0      0
 104 \              sh   |      36      0      0      0      0      0      0
 105 \              tcl  |      36      0      0      0      0      0      0
 106 \                   |--------------------------------------------------
 107 \                   |     300      0      0      0      0      0      0
 108 \                   \\__________________________________________________
 109 .Ed
 110 .Pp
 111 The
 112 .Ql report-card
 113 tool has been added, with three passes, one for each implementation.  (The
 114 shell and Tcl implementations were later dropped to reduce future
 115 maintenance burden.)  As before, all tests passed as expected.  The
 116 interesting difference from the previous example is the use of DejaGnu's
 117 multipass testing feature and the additional per-pass summary lines added.
 118 For this example, only the
 119 .Ql report-card
 120 tool uses multipass testing, so each pass total is simply the count of
 121 tests for
 122 .Ql report-card
 123 instead of a distinct total.
 124 .Pp
 125 Also note that the command used to invoke
 126 .Nm
 127 is slightly different here.  The
 128 .Xr dejagnu 1
 129 launcher will also accept multiple words joined with dashes into a single
 130 argument.  This allows individual words in a command name to be separated
 131 with either dashes or spaces on the command line interchangeably.
 132 .Sh SEE ALSO
 133 .Xr dejagnu 1
 134 .Xr runtest 1
 135 .Pp
 136 The full documentation for DejaGnu is maintained as a Texinfo manual.  If the
 137 .Nm info
 138 program is properly installed at your site, the command
 139 .Li info dejagnu
 140 should give you access to the complete manual.
 141 .Sh AUTHORS
 142 .An Jacob Bachmeyer
 143 .\".Sh BUGS
 144 .\"  LocalWords:  Dt dejagnu URM Nm Ao Oo Oc DejaGnu Xr runtest DejaGnu's Bd Ql
 145 .\"  LocalWords:  testsuite UNSUP UNRES UNTEST libdejagnu Readline Ss tcl awk
 146 .\"  LocalWords:  ne multipass