tools/regression/README

   1 $FreeBSD$
   2
   3 This directory is for regression test programs.
   4
   5 A regression test program is one that will exercise a particular bit of the
   6 system to check that we have not reintroduced an old bug.
   7
   8 Tests should be implemented in files with a .t extension.  Each .t file
   9 can contain more than one test, and can be implemented in any scripting
  10 language -- /bin/sh, Perl...
  11
  12 The test protocol is quite simple.  At its most basic, each .t file should,
  13 when run, print a line in this format:
  14
  15    1..m
  16
  17 where m is the number of tests that will be run.
  18
  19 Each test should produce a single line of output.  This line should start
  20 with one of
  21
  22    ok n
  23    not ok n
  24
  25 to indicate whether or not the test succeeded.  'n' is the test's number.
  26 Anything after this on the line (up to the first '#' if present) is
  27 considered to be the name of the test.  Naming tests is optional, but
  28 encouraged.
  29
  30 A test may be written which is conditional, and may need to be skipped.
  31 For example, the netatalk tests require 'options NETATALK' in the kernel.
  32 A test may be skipped by printing '# skip Reason for skipping' after the
  33 test name.  For example,
  34
  35     ok 1 - netatalk # skip 'options NETATALK' not compiled in
  36
  37 A test may be flagged as 'todo'.  This indicates that you expect the test
  38 to fail (perhaps because the necessary functionality hasn't been written
  39 yet).  'todo' tests are expected to fail, so when they start working the
  40 test framework can alert you to this happy occurence.  Flag these tests
  41 with a '# TODO' comment after the test name
  42
  43     not ok 1 - infiniteloop # TODO write test for an infinite loop
  44
  45 This is modelled on the protocol followed by the Test::Harness Perl
  46 module (and therefore much of the automated testing carried out by the
  47 Perl community).  More documentation can be found at:
  48
  49     http://search.cpan.org/~petdance/Test-Harness-2.42/lib/Test/Harness.pm
  50
  51 To run the tests and parse their output install the devel/p5-Test-Harness
  52 port.  This includes the prove(1) command which is used to run the tests
  53 and collate the output.
  54
  55     prove geom_concat           # run all the tests in geom_concat
  56     prove -r lib                # run all tests in lib/, and subdirectories
  57     prove -r -v lib             # as above, with verbose output
  58     prove -r                    # run *all* the tests
  59
  60 Tests that are for parts of the base system should go into a directory here
  61 which is the same as their path relative to src/, for example the uuencode(1)
  62 utility resides in src/usr.bin/uuencode so its regression test resides in
  63 src/tools/regression/usr.bin/uuencode.
  64
  65 To avoid the pre-commit check program complaining about the lack of
  66 CVS keywords in test data files, use a .in suffix for input files and
  67 a .out suffix for output files.
  68
  69 To execute individual regression tests for binaries that you are
  70 developing, add their directory in the path before running the tests.
  71 Example:
  72 cd /usr/src/tools/regression/usr.bin
  73 (PATH=/home/user/src/experimental/jot:$PATH ; make SUBDIR=jot)
  74
  75 Please make a subdir per other regression test, and add a brief description to
  76 this file.
  77
  78 acct            Exercise the integer to float conversion used in acct(5)
  79 geom            Some tests and an out-of-kernel simulator for the GEOM code
  80 ia64            ia64 specific regression tests
  81 nfsmmap         Some tests to exercise some tricky cases in NFS and mmap
  82 p1003_1b        Exercise 1003.1B scheduler
  83 pipe            Pipe code regression test
  84 fsx             General filesystem exerciser
  85 sysvmsg         SysV IPC Message Queue Regression Utility
  86 sysvsem         SysV IPC Semaphore Regression Utility
  87 sysvshm         SysV IPC Shared Memory Regression Utility
  88 gaithrstress    General threaded getaddrinfo(3) exerciser
  89 date            Date(1) + format string regression test