usr.bin/dfregress/dfregress.8

   1 .\"
   2 .\" Copyright (c) 2011
   3 .\"     The DragonFly Project.  All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\"
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in
  13 .\"    the documentation and/or other materials provided with the
  14 .\"    distribution.
  15 .\" 3. Neither the name of The DragonFly Project nor the names of its
  16 .\"    contributors may be used to endorse or promote products derived
  17 .\"    from this software without specific, prior written permission.
  18 .\"
  19 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  20 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  21 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  22 .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
  23 .\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  24 .\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
  25 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  26 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
  27 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  28 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  29 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .Dd November 17, 2011
  33 .Dt DFREGRESS 8
  34 .Os
  35 .Sh NAME
  36 .Nm dfregress
  37 .Nd an automation test driver and framework
  38 .Sh SYNOPSIS
  39 .Nm
  40 .Fl o Ar output_plist
  41 .Fl t Ar testcase_dir
  42 .Fl r Ar runlist_file
  43 .Op Fl p Ar prepost_dir
  44 .Nm
  45 .Fl h
  46 .Sh DESCRIPTION
  47 .Nm
  48 is a regression test framework and automation driver.
  49 It executes a series of testcases as specified in the
  50 .Ar runlist_file
  51 and collects the results.
  52 .Pp
  53 The path to the testcase collection is specified via the
  54 .Ar testcase_dir
  55 argument, and similarly the path to the pre- and post commands is
  56 specified via
  57 .Ar prepost_dir .
  58 The
  59 .Ar prepost_dir
  60 only needs to be specified if the runlist contains custom pre or
  61 post commands.
  62 .Pp
  63 The output is saved in plist format to the
  64 .Ar output_plist
  65 file.
  66 Other tools, known as frontends, can parse the plist output into
  67 an easier to read form.
  68 .Pp
  69 The following is a summary of the arguments:
  70 .Bl -tag -width indent
  71 .It Fl o Ar output_plist
  72 Specifies the file to which to write the results.
  73 The resulting file,
  74 .Ar output_plist ,
  75 will be in plist format.
  76 .It Fl t Ar testcase_dir
  77 Specifies the directory in which to find the testcases specified in the runlist.
  78 .It Fl r Ar runlist_file
  79 Specifies the file containing the runlist to use for the test execution.
  80 .It Fl p Ar prepost_dir
  81 Specifies the directory in which to find the pre- and post commands used
  82 in the runlist.
  83 This argument is only required when the runlist uses custom pre- or post
  84 commands.
  85 .It Fl h
  86 Prints a short synopsys.
  87 .El
  88 .Sh RUNLIST SYNTAX
  89 Testcases are specified one testcase per line, with whitespace separated
  90 values.
  91 Empty lines and lines beginning with a
  92 .Dq #
  93 are ignored.
  94 .Pp
  95 Runlist lines are of the following format:
  96 .Bd -literal -offset indent
  97 .Ic testcase type options Cm arguments ...
  98 .Ed
  99 .Pp
 100 The
 101 .Ic testcase
 102 part needs to be a relative path from the testcase base directory specified
 103 by the
 104 .Fl t
 105 argument to the resulting (after building the testcase) testcase executable.
 106 The testcase will be executed with the
 107 .Ic Cm arguments
 108 passed as command line arguments to it.
 109 .Pp
 110 Valid types are
 111 .Ic userland ,
 112 .Ic kernel
 113 and
 114 .Ic buildonly :
 115 .Bl -tag -width indent -offset indent
 116 .It Ic userland
 117 A userland testcase is a normal userland executable that returns a non-zero
 118 exit value on test failure.
 119 .It Ic kernel
 120 A kernel testcase is run with the kernel test bridge inside the kernel.
 121 .It Ic buildonly
 122 A buildonly test passes when the build for the given testcase succeeds.
 123 .El
 124 .Pp
 125 Valid options are
 126 .Ic defaults ,
 127 .Ic make ,
 128 .Ic timeout ,
 129 .Ic nobuild ,
 130 .Ic runas ,
 131 .Ic intpre ,
 132 .Ic intpost ,
 133 .Ic pre ,
 134 and
 135 .Ic post :
 136 .Bl -tag -width indent -offset indent
 137 .It Ic defaults
 138 This option does nothing.
 139 All default options are applied.
 140 .It Ic make Ar make_command
 141 Uses
 142 .Ar make_command
 143 instead of
 144 .Xr make 1
 145 to build the testcase.
 146 .It Ic timeout Ar timeout
 147 Sets the timeout for the testcase after which the testcase will be aborted to
 148 .Ar timeout
 149 seconds.
 150 .It Ic nobuild
 151 If this option is set, the build stage and cleanup stage of the test case
 152 are not run.
 153 .It Ic runas Ar uid
 154 Runs the testcase as the user identified by the given
 155 .Ar uid .
 156 .It Ic intpre
 157 Executes the testcase command with the argument
 158 .Dq pre
 159 during the pre-run command stage.
 160 .It Ic intpost
 161 Executes the testcase command with the argument
 162 .Dq post
 163 during the post-run command stage.
 164 .It Ic pre Ar precmd
 165 Executes the command specified by
 166 .Ar precmd
 167 during the pre-run command stage.
 168 .It Ic pre Ar postcmd
 169 Executes the command specified by
 170 .Ar postcmd
 171 during the post-run command stage.
 172 .El
 173 .Sh TESTCASE EXECUTION
 174 .Bl -enum -width 3n -offset indent
 175 .It
 176 .Tn "CHDIR"
 177 to the testcase directory.
 178 If it fails, the result will be set to
 179 .Dv RESULT_PREFAIL
 180 and the
 181 .Ar sysbuf
 182 buffer will provide further details.
 183 .It
 184 .Tn "BUILD"
 185 the testcase using the command specified by the
 186 .Ic make
 187 option or, if not specified,
 188 .Xr make 1 ,
 189 unless the
 190 .Ic nobuild
 191 option was specified.
 192 If there is an internal driver error, the result will be set to
 193 .Dv RESULT_PREFAIL ,
 194 the next step to be performed will be
 195 .Tn "CLEANUP"
 196 and the
 197 .Ar sysbuf
 198 buffer will provide further details.
 199 If no internal error occurs, the
 200 .Ar buildbuf
 201 will contain the build log.
 202 .It
 203 .Tn "RUN PRE COMMAND"
 204 if
 205 .Ic intpre
 206 or
 207 .Ic pre
 208 are set.
 209 If there is an internal driver error, the result will be set to
 210 .Dv RESULT_PREFAIL ,
 211 the next step to be performed will be
 212 .Tn "CLEANUP"
 213 and the
 214 .Ar sysbuf
 215 buffer will provide further details.
 216 If the pre command has a non-zero exit value, the result will be set to
 217 .Dv RESULT_PREFAIL
 218 and the
 219 next step to be performed will be
 220 .Tn "CLEANUP" .
 221 In this case and in the case where the command succeeds, the
 222 .Ar precmd_buf
 223 will contain the execution log.
 224 .It
 225 .Tn "RUN TESTCASE"
 226 depending on type:
 227 .Bl -tag -width 2n -compact
 228 .It "buildonly"
 229 testcases will get their result set to
 230 .Dv RESULT_PASS at this point, since the build must have succeeded already.
 231 .It "userland"
 232 testcases will get executed in a separate child process, possibly as a
 233 different user, depending on whether the
 234 .Ic runas
 235 option was specified.
 236 The result will be set to
 237 .Dv RESULT_TIMEOUT
 238 if the timeout is reached before the testcase finishes,
 239 .Dv RESULT_SIGNALLED
 240 if the testcase dies because of an unhandled signal (often due to crashing),
 241 .Dv RESULT_NOTRUN
 242 if the testcase could not be executed,
 243 .Dv RESULT_FAIL
 244 if the testcase completes but returns failure or
 245 .Dv RESULT_PASS
 246 if the testcase completes and returns success.
 247 .It "kernel"
 248 testcases will be executed in kernel space by loading a given module and
 249 running the testcase entry point function.
 250 The result will be set to
 251 .Dv RESULT_NOTRUN
 252 if the testcase could not be executed.
 253 Otherwise the result will be set according to the kernel test case to
 254 one of
 255 .Dv RESULT_TIMEOUT ,
 256 .Dv RESULT_FAIL ,
 257 or
 258 .Dv RESULT_PASS .
 259 .El
 260 The output will be logged separately for stdout and stderr to the
 261 .Ar stdout_buf
 262 and
 263 .Ar stderr_buf
 264 respectively.
 265 If the result was
 266 .Dv RESULT_NOTRUN
 267 the
 268 .Ar sysbuf
 269 will contain more information.
 270 .It
 271 .Tn "RUN POST COMMAND"
 272 if
 273 .Ic intpost
 274 or
 275 .Ic post
 276 are set.
 277 If there is an internal driver error, the result will be set to
 278 .Dv RESULT_POSTFAIL ,
 279 the next step to be performed will be
 280 .Tn "CLEANUP"
 281 and the
 282 .Ar sysbuf
 283 buffer will provide further details.
 284 If the post command has a non-zero exit value, the result will be set to
 285 .Dv RESULT_POSTFAIL
 286 and the
 287 next step to be performed will be
 288 .Tn "CLEANUP" .
 289 In this case and in the case where the command succeeds, the
 290 .Ar postcmd_buf
 291 will contain the execution log.
 292 .It
 293 .Tn "CLEANUP"
 294 the testcase execution using the command specified by the
 295 .Ic make
 296 option or, if not specified,
 297 .Xr make 1
 298 with the parameter
 299 .Dq clean ,
 300 unless the
 301 .Ic nobuild
 302 option was specified.
 303 If there is an internal driver error the
 304 .Ar sysbuf
 305 buffer will contain more information.
 306 If no internal error occurs, the
 307 .Ar cleanu_pbuf
 308 will contain the cleanup log.
 309 .El
 310 .Sh FRONTENDS
 311 The output of
 312 .Nm
 313 is in the Apple plist serialized object format.
 314 This format can be easily parsed by using
 315 .Xr proplib 3
 316 when using C.
 317 Ruby and Python also have parsers for the plist format.
 318 .Pp
 319 A frontend for
 320 .Nm
 321 parses the intermediate output plist into a more easily readable format
 322 such as plain text or websites.
 323 .Pp
 324 By default
 325 .Nm
 326 ships only with the
 327 .Xr dfr2text 8
 328 text-based frontend.
 329 .Sh EXAMPLES
 330 An example runlist can be found under
 331 .Pa test/testcases/sample.run .
 332 .Sh SEE ALSO
 333 .Xr dfr2text 8
 334 .Sh HISTORY
 335 The
 336 .Nm
 337 utility appeared in
 338 .Dx 2.13 .
 339 .Sh AUTHORS
 340 .An Alex Hornung