rt-doc.txt

   1
   2 #|----------------------------------------------------------------------------|
   3  | Copyright 1990 by the Massachusetts Institute of Technology, Cambridge MA. |
   4  |                                                                            |
   5  | Permission  to  use,  copy, modify, and distribute this software  and  its |
   6  | documentation for any purpose  and without fee is hereby granted, provided |
   7  | that this copyright  and  permission  notice  appear  in  all  copies  and |
   8  | supporting  documentation,  and  that  the  name  of M.I.T. not be used in |
   9  | advertising or  publicity  pertaining  to  distribution  of  the  software |
  10  | without   specific,   written   prior   permission.    M.I.T.   makes   no |
  11  | representations  about  the  suitability of this software for any purpose. |
  12  | It is provided "as is" without express or implied warranty.                |
  13  |                                                                            |
  14  |  M.I.T. DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,  INCLUDING  |
  15  |  ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL  |
  16  |  M.I.T. BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL  DAMAGES  OR  |
  17  |  ANY  DAMAGES  WHATSOEVER  RESULTING  FROM  LOSS OF USE, DATA OR PROFITS,  |
  18  |  WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER  TORTIOUS  ACTION,  |
  19  |  ARISING  OUT  OF  OR  IN  CONNECTION WITH THE USE OR PERFORMANCE OF THIS  |
  20  |  SOFTWARE.                                                                 |
  21  |----------------------------------------------------------------------------|#
  22
  23   (This is the December 19, 1990 version of brief documentation for the
  24    RT regression tester.  A more complete discussion can be found in
  25    the article in Lisp Pointers.)
  26
  27 The functions, macros, and variables that make up the RT regression tester are
  28 in a package called "RT".  The ten exported symbols are documented below.  If
  29 you want to refer to these symbols without a package prefix, you have to `use'
  30 the package.
  31
  32 The basic unit of concern of RT is the test.  Each test has an identifying name
  33 and a body that specifies the action of the test.  Functions are provided for
  34 defining, redefining, removing, and performing individual tests and the test
  35 suite as a whole.  In addition, information is maintained about which tests have
  36 succeeded and which have failed.
  37
  38
  39 <> deftest NAME FORM &rest VALUES
  40
  41 Individual tests are defined using the macro DEFTEST.  The identifying NAME is
  42 typically a number or symbol, but can be any Lisp form.  If the test suite
  43 already contains a test with the same (EQUAL) NAME, then this test is redefined
  44 and a warning message printed.  (This warning is important to alert the user
  45 when a test suite definition file contains two tests with the same name.)  When
  46 the test is a new one, it is added to the end of the suite.  In either case,
  47 NAME is returned as the value of DEFTEST and stored in the variable *TEST*.
  48
  49 (deftest t-1 (floor 15/7) 2 1/7) => t-1
  50
  51 (deftest (t 2) (list 1) (1)) => (t 2)
  52
  53 (deftest bad (1+ 1) 1) => bad
  54
  55 (deftest good (1+ 1) 2) => good
  56
  57 The FORM can be any kind of Lisp form.  The zero or more VALUES can be any kind
  58 of Lisp objects.  The test is performed by evaluating FORM and comparing the
  59 results with the VALUES.  The test succeeds if and only if FORM produces the
  60 correct number of results and each one is EQUAL to the corresponding VALUE.
  61
  62
  63 <> *test* NAME-OF-CURRENT-TEST
  64
  65 The variable *TEST* contains the name of the test most recently defined or
  66 performed.  It is set by DEFTEST and DO-TEST.
  67
  68
  69 <> do-test &optional (NAME *TEST*)
  70
  71 The function DO-TEST performs the test identified by NAME, which defaults to
  72 *TEST*.  Before running the test, DO-TEST stores NAME in the variable *TEST*.
  73 If the test succeeds, DO-TEST returns NAME as its value.  If the test fails,
  74 DO-TEST returns NIL, after printing an error report on *STANDARD-OUTPUT*.  The
  75 following examples show the results of performing two of the tests defined
  76 above.
  77
  78 (do-test '(t 2)) => (t 2)
  79
  80 (do-test 'bad) => nil ; after printing:
  81 Test BAD failed
  82 Form: (1+ 1)
  83 Expected value: 1
  84 Actual value: 2.
  85
  86
  87 <> *do-tests-when-defined*  default value  NIL
  88
  89 If the value of this variable is non-null, each test is performed at the moment
  90 that it is defined.  This is helpful when interactively constructing a suite of
  91 tests.  However, when loading a test suite for later use, performing tests as
  92 they are defined is not liable to be helpful.
  93
  94
  95 <> get-test &optional (NAME *TEST*)
  96
  97 This function returns the NAME, FORM, and VALUES of the specified test.
  98
  99 (get-test '(t 2)) => ((t 2) (list 1) (1))
 100
 101
 102 <> rem-test &optional (NAME *TEST*)
 103
 104 If the indicated test is in the test suite, this function removes it and returns
 105 NAME.  Otherwise, NIL is returned.
 106
 107
 108 <> rem-all-tests
 109
 110 This function reinitializes RT by removing every test from the test suite and
 111 returns NIL.  Generally, it is advisable for the whole test suite to apply to
 112 some one system.  When switching from testing one system to testing another, it
 113 is wise to remove all the old tests before beginning to define new ones.
 114
 115
 116 <> do-tests &optional (OUT *STANDARD-OUTPUT*)
 117
 118 This function uses DO-TEST to run each of the tests in the test suite and prints
 119 a report of the results on OUT, which can either be an output stream or the name
 120 of a file.  If OUT is omitted, it defaults to *STANDARD-OUTPUT*.  DO-TESTS
 121 returns T if every test succeeded and NIL if any test failed.
 122
 123 As illustrated below, the first line of the report produced by DO-TEST shows how
 124 many tests need to be performed.  The last line shows how many tests failed and
 125 lists their names.  While the tests are being performed, DO-TESTS prints the
 126 names of the successful tests and the error reports from the unsuccessful tests.
 127
 128 (do-tests "report.txt") => nil
 129 ; the file "report.txt" contains:
 130 Doing 4 pending tests of 4 tests total.
 131  T-1 (T 2)
 132 Test BAD failed
 133 Form: (1+ 1)
 134 Expected value: 1
 135 Actual value: 2.
 136  GOOD
 137 1 out of 4 total tests failed: BAD.
 138
 139 It is best if the individual tests in the suite are totally independent of each
 140 other.  However, should the need arise for some interdependence, you can rely on
 141 the fact that DO-TESTS will run tests in the order they were originally defined.
 142
 143
 144 <> pending-tests
 145
 146 When a test is defined or redefined, it is marked as pending.  In addition,
 147 DO-TEST marks the test to be run as pending before running it and DO-TESTS marks
 148 every test as pending before running any of them.  The only time a test is
 149 marked as not pending is when it completes successfully.  The function
 150 PENDING-TESTS returns a list of the names of the currently pending tests.
 151
 152 (pending-tests) => (bad)
 153
 154
 155 <> continue-testing
 156
 157 This function is identical to DO-TESTS except that it only runs the tests that
 158 are pending and always writes its output on *STANDARD-OUTPUT*.
 159
 160 (continue-testing) => nil ; after printing:
 161 Doing 1 pending test out of 4 total tests.
 162 Test BAD failed
 163 Form: (1+ 1)
 164 Expected value: 1
 165 Actual value: 2.
 166 1 out of 4 total tests failed: BAD.
 167
 168 CONTINUE-TESTING has a special meaning if called at a breakpoint generated while
 169 a test is being performed.  The failure of a test to return the correct value
 170 does not trigger an error break.  However, there are many kinds of things that
 171 can go wrong while a test is being performed (e.g., dividing by zero) that will
 172 cause breaks.
 173
 174 If CONTINUE-TESTING is evaluated in a break generated during testing, it aborts
 175 the current test (which remains pending) and forces the processing of tests to
 176 continue.  Note that in such a breakpoint, *TEST* is bound to the name of the
 177 test being performed and (GET-TEST) can be used to look at the test.
 178
 179 When building a system, it is advisable to start constructing a test suite for
 180 it as soon as possible.  Since individual tests are rather weak, a comprehensive
 181 test suite requires large numbers of tests.  However, these can be accumulated
 182 over time.  In particular, whenever a bug is found by some means other than
 183 testing, it is wise to add a test that would have found the bug and therefore
 184 will ensure that the bug will not reappear.
 185
 186 Every time the system is changed, the entire test suite should be run to make
 187 sure that no unintended changes have occurred.  Typically, some tests will fail.
 188 Sometimes, this merely means that tests have to be changed to reflect changes in
 189 the system's specification.  Other times, it indicates bugs that have to be
 190 tracked down and fixed.  During this phase, CONTINUE-TESTING is useful for
 191 focusing on the tests that are failing.  However, for safety sake, it is always
 192 wise to reinitialize RT, redefine the entire test suite, and run DO-TESTS one
 193 more time after you think all of the tests are working.
 194