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 .Op Fl o Ar output_plist
  41 .Op Fl t Ar testcase_dir
  42 .Op Fl p Ar prepost_dir
  43 .Ar runlist_file
  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.
  56 If this argument is not specified, the default is assumed to be the
  57 same directory as that of the runlist.
  58 For example if the used runlist ist
  59 .Pa /usr/src/test/testcases/sample.run
  60 the default testcase directory, unless otherwise specified, will be
  61 .Pa /usr/src/test/testcases .
  62 .Pp
  63 Similarly the path to the pre- and post commands is
  64 specified via
  65 .Ar prepost_dir .
  66 The
  67 .Ar prepost_dir
  68 only needs to be specified if the runlist contains custom pre or
  69 post commands.
  70 .Pp
  71 The output is saved in plist format to the
  72 .Ar output_plist
  73 file, or if none is specified, to a file with the same base name as
  74 the runlist, but in the current working directory and with a
  75 .Pa .plist
  76 extension.
  77 For example if the used runlist is
  78 .Pa /usr/src/test/testcases/sample.run
  79 the default output, unless otherwise specified, will be
  80 .Pa ./sample.plist .
  81 Other tools, known as frontends, can parse the plist output into
  82 an easier to read form.
  83 .Pp
  84 The following is a summary of the optional parameters:
  85 .Bl -tag -width indent
  86 .It Fl o Ar output_plist
  87 Specifies the file to which to write the results.
  88 The resulting file,
  89 .Ar output_plist ,
  90 will be in plist format.
  91 .It Fl t Ar testcase_dir
  92 Specifies the directory in which to find the testcases specified in the runlist.
  93 .It Fl p Ar prepost_dir
  94 Specifies the directory in which to find the pre- and post commands used
  95 in the runlist.
  96 This argument is only required when the runlist uses custom pre- or post
  97 commands.
  98 .It Fl h
  99 Prints a short synopsis.
 100 .El
 101 .Sh RUNLIST SYNTAX
 102 Testcases are specified one testcase per line, with whitespace separated
 103 values.
 104 Empty lines and lines beginning with a
 105 .Dq #
 106 are ignored.
 107 .Pp
 108 Runlist lines are of the following format:
 109 .Bd -literal -offset indent
 110 .Ic testcase type options Cm arguments ...
 111 .Ed
 112 .Pp
 113 The
 114 .Ic testcase
 115 part needs to be a relative path from the testcase base directory specified
 116 by the
 117 .Fl t
 118 argument to the resulting (after building the testcase) testcase executable.
 119 The testcase will be executed with the
 120 .Cm arguments
 121 passed as command line arguments to it.
 122 .Pp
 123 Valid types are
 124 .Ic userland ,
 125 .Ic kernel
 126 and
 127 .Ic buildonly :
 128 .Bl -tag -width indent -offset indent
 129 .It Ic userland
 130 A userland testcase is a normal userland executable that returns a non-zero
 131 exit value on test failure.
 132 .It Ic kernel
 133 A kernel testcase is run with the kernel test bridge inside the kernel.
 134 .It Ic buildonly
 135 A buildonly test passes when the build for the given testcase succeeds.
 136 .El
 137 .Pp
 138 Valid options are
 139 .Ic defaults ,
 140 .Ic make ,
 141 .Ic timeout ,
 142 .Ic nobuild ,
 143 .Ic runas ,
 144 .Ic intpre ,
 145 .Ic intpost ,
 146 .Ic pre ,
 147 and
 148 .Ic post :
 149 .Bl -tag -width indent -offset indent
 150 .It Ic defaults
 151 This option does nothing.
 152 All default options are applied.
 153 .It Ic make Ar make_command
 154 Uses
 155 .Ar make_command
 156 instead of
 157 .Xr make 1
 158 to build the testcase.
 159 .It Ic timeout Ar timeout
 160 Sets the timeout for the testcase after which the testcase will be aborted to
 161 .Ar timeout
 162 seconds.
 163 .It Ic nobuild
 164 If this option is set, the build stage and cleanup stage of the test case
 165 are not run.
 166 .It Ic runas Ar uid
 167 Runs the testcase as the user identified by the given
 168 .Ar uid .
 169 .It Ic intpre
 170 Executes the testcase command with the argument
 171 .Dq pre
 172 during the pre-run command stage.
 173 .It Ic intpost
 174 Executes the testcase command with the argument
 175 .Dq post
 176 during the post-run command stage.
 177 .It Ic pre Ar precmd
 178 Executes the command specified by
 179 .Ar precmd
 180 during the pre-run command stage.
 181 .It Ic pre Ar postcmd
 182 Executes the command specified by
 183 .Ar postcmd
 184 during the post-run command stage.
 185 .El
 186 .Sh TESTCASE EXECUTION
 187 .Bl -enum -width 3n -offset indent
 188 .It
 189 .Tn "CHDIR"
 190 to the testcase directory.
 191 If it fails, the result will be set to
 192 .Dv RESULT_PREFAIL
 193 and the
 194 .Ar sysbuf
 195 buffer will provide further details.
 196 .It
 197 .Tn "BUILD"
 198 the testcase using the command specified by the
 199 .Ic make
 200 option or, if not specified,
 201 .Xr make 1 ,
 202 unless the
 203 .Ic nobuild
 204 option was specified.
 205 If there is an internal driver error, the result will be set to
 206 .Dv RESULT_PREFAIL ,
 207 the next step to be performed will be
 208 .Tn "CLEANUP"
 209 and the
 210 .Ar sysbuf
 211 buffer will provide further details.
 212 If no internal error occurs, the
 213 .Ar buildbuf
 214 will contain the build log.
 215 .It
 216 .Tn "RUN PRE COMMAND"
 217 if
 218 .Ic intpre
 219 or
 220 .Ic pre
 221 are set.
 222 If there is an internal driver error, the result will be set to
 223 .Dv RESULT_PREFAIL ,
 224 the next step to be performed will be
 225 .Tn "CLEANUP"
 226 and the
 227 .Ar sysbuf
 228 buffer will provide further details.
 229 If the pre command has a non-zero exit value, the result will be set to
 230 .Dv RESULT_PREFAIL
 231 and the
 232 next step to be performed will be
 233 .Tn "CLEANUP" .
 234 In this case and in the case where the command succeeds, the
 235 .Ar precmd_buf
 236 will contain the execution log.
 237 .It
 238 .Tn "RUN TESTCASE"
 239 depending on type:
 240 .Bl -tag -width 2n -compact
 241 .It "buildonly"
 242 testcases will get their result set to
 243 .Dv RESULT_PASS at this point, since the build must have succeeded already.
 244 .It "userland"
 245 testcases will get executed in a separate child process, possibly as a
 246 different user, depending on whether the
 247 .Ic runas
 248 option was specified.
 249 The result will be set to
 250 .Dv RESULT_TIMEOUT
 251 if the timeout is reached before the testcase finishes,
 252 .Dv RESULT_SIGNALLED
 253 if the testcase dies because of an unhandled signal (often due to crashing),
 254 .Dv RESULT_NOTRUN
 255 if the testcase could not be executed,
 256 .Dv RESULT_FAIL
 257 if the testcase completes but returns failure or
 258 .Dv RESULT_PASS
 259 if the testcase completes and returns success.
 260 .It "kernel"
 261 testcases will be executed in kernel space by loading a given module and
 262 running the testcase entry point function.
 263 The result will be set to
 264 .Dv RESULT_NOTRUN
 265 if the testcase could not be executed.
 266 Otherwise the result will be set according to the kernel test case to
 267 one of
 268 .Dv RESULT_TIMEOUT ,
 269 .Dv RESULT_FAIL ,
 270 or
 271 .Dv RESULT_PASS .
 272 .El
 273 The output will be logged separately for stdout and stderr to the
 274 .Ar stdout_buf
 275 and
 276 .Ar stderr_buf
 277 respectively.
 278 If the result was
 279 .Dv RESULT_NOTRUN
 280 the
 281 .Ar sysbuf
 282 will contain more information.
 283 .It
 284 .Tn "RUN POST COMMAND"
 285 if
 286 .Ic intpost
 287 or
 288 .Ic post
 289 are set.
 290 If there is an internal driver error, the result will be set to
 291 .Dv RESULT_POSTFAIL ,
 292 the next step to be performed will be
 293 .Tn "CLEANUP"
 294 and the
 295 .Ar sysbuf
 296 buffer will provide further details.
 297 If the post command has a non-zero exit value, the result will be set to
 298 .Dv RESULT_POSTFAIL
 299 and the
 300 next step to be performed will be
 301 .Tn "CLEANUP" .
 302 In this case and in the case where the command succeeds, the
 303 .Ar postcmd_buf
 304 will contain the execution log.
 305 .It
 306 .Tn "CLEANUP"
 307 the testcase execution using the command specified by the
 308 .Ic make
 309 option or, if not specified,
 310 .Xr make 1
 311 with the parameter
 312 .Dq clean ,
 313 unless the
 314 .Ic nobuild
 315 option was specified.
 316 If there is an internal driver error the
 317 .Ar sysbuf
 318 buffer will contain more information.
 319 If no internal error occurs, the
 320 .Ar cleanu_pbuf
 321 will contain the cleanup log.
 322 .El
 323 .Sh FRONTENDS
 324 The output of
 325 .Nm
 326 is in the Apple plist serialized object format.
 327 This format can be easily parsed by using
 328 .Xr proplib 3
 329 when using C.
 330 Ruby and Python also have parsers for the plist format.
 331 .Pp
 332 A frontend for
 333 .Nm
 334 parses the intermediate output plist into a more easily readable format
 335 such as plain text or websites.
 336 .Pp
 337 By default
 338 .Nm
 339 ships only with the
 340 .Xr dfr2text 8
 341 text-based frontend.
 342 .Sh HOW TO WRITE A TESTCASE
 343 A userland testcase is a simple program that prints some relevant
 344 information to stdout and stderr, both of which are captured by the test
 345 driver, and returns an exit value of 0 if the test passed, or any other
 346 non-zero exit value to signal a failure.
 347 The exact exit value is recorded by
 348 .Nm .
 349 All signals/exceptions not explicitly caught by the testcase will abort
 350 the execution of the testcase and the result will be set appropriately and
 351 the signal number will be recorded.
 352 .Pp
 353 A kernel testcase is a simple kernel module that defines two methods:
 354 a
 355 .Fn run
 356 method as well as an optional
 357 .Fn abort
 358 method.
 359 The
 360 .Fn run
 361 method will be run from a separate kernel thread.
 362 The testcase will need to call
 363 .Xr tbridge 9
 364 functions to record output and to notify of testcase completion.
 365 Refer to the
 366 .Xr tbridge 9
 367 manual page for more details.
 368 .Pp
 369 For all testcase types the build stage is common.
 370 Every testcase should either have the
 371 .Ic nobuild
 372 option set, or have a Makefile or similar in its directory.
 373 By default
 374 .Nm
 375 assumes it is a standard
 376 .Xr make 1
 377 Makefile.
 378 If that is not the case, the
 379 .Ic build
 380 option needs to be adjusted accordingly.
 381 .Sh GENERAL ADVICE ON WRITING TESTCASES
 382 Test only one thing at a time, it is not good practice to test multiple
 383 things in the same testcase as it makes it less obvious what's going on.
 384 .Pp
 385 Keep it short, simple and well documented on what the requirements are,
 386 what the preconditions need to be, what exactly is being tested, ideally
 387 with a reference to a particular bug if that exists, and most importantly
 388 what the expected outcomes are.
 389 .Pp
 390 Make sure your testcase doesn't depend on any other being run previously
 391 as well as that it won't hinder any other testcase from running.
 392 This effectively means that your testcase should make no assumptions as
 393 to what has been run previously unless it has a registered pre-command
 394 and that the system should be left as found before your testcase.
 395 .Sh EXAMPLES
 396 An example runlist can be found under
 397 .Pa test/testcases/sample.run .
 398 .Pp
 399 Several example testcases for both userland and kernel are under
 400 .Pa test/testcases/sample .
 401 .Sh SEE ALSO
 402 .Xr dfr2text 8 ,
 403 .Xr tbridge 9
 404 .Sh HISTORY
 405 The
 406 .Nm
 407 utility appeared in
 408 .Dx 2.13 .
 409 .Sh AUTHORS
 410 .An Alex Hornung