tester.html

   1 <html><head><title>The Allegro CL Test harness</title></head><body><table border="0" width="100%" cellpadding="1" cellspacing="0"><tr><td colspan="2" bgcolor="#00FFFF"><table border="0" cellpadding="5" cellspacing="3"><tr><td align="left" bgcolor="#00FFFF"><a href="contents.htm"><b>ToC</b></a></td><td align="left" bgcolor="#00FFFF"><a href="introduction.htm"><b>DocOverview</b></a></td><td align="left" bgcolor="#00FFFF"><a href="cgide.htm"><b>CGDoc</b></a></td><td align="left" bgcolor="#00FFFF"><a href="release-notes.htm"><b>RelNotes</b></a></td><td align="left" bgcolor="#00FFFF"><a href="index.htm"><b>Index</b></a></td><td align="left" bgcolor="#00FFFF"><a href="permuted-index.htm"><b>PermutedIndex</b></a></td></tr></table></td><td align="right"><b>Allegro CL version 6.1</b><br><small><a href="introduction.htm#updates-s">Unrevised</a></small></td></tr></table><h1>The Allegro CL Test harness</h1><p>This document contains the following sections:</p><a href="#tester-api-1">1.0 The tester module API</a><br>&nbsp;&nbsp;&nbsp;<a href="#tester-vars-2">1.1 Test Harness Variables</a><br>&nbsp;&nbsp;&nbsp;<a href="#tester-macros-2">1.2 Test Harness Macros</a><br>&nbsp;&nbsp;&nbsp;<a href="#tester-examples-2">1.3 Examples</a><br><p>
   2 ANSI Common Lisp contains no functionality designed specifically for
   3 testing applications. Because testing is an essential part of
   4 application development, Franz Inc.  is making public the test harness
   5 used internally for testing Allegro CL itself. (A test harness is a
   6 collection of macros and variables associated with testing, along with
   7 templates for test forms.)
   8 </p><p>
   9 The test harness facility was added to Allegro CL in release 6.0. (It
  10 was available as a patch for release 5.0.1).
  11 </p><p>
  12 To use the test harness, you must load the
  13 <i>tester.fasl</i> module. Do this by evaluating
  14 </p><pre>
  15 (require :tester)
  16 </pre><hr><hr><h2><a name="tester-api-1">1.0 The tester module API</a></h2>
  17
  18 <p>
  19 All of the following symbols are exported from the
  20 <code>util.test</code> package.
  21 </p>
  22
  23 <hr><h2><a name="tester-vars-2">1.1 Test Harness Variables</a></h2>
  24
  25 <p>
  26 The test harness API includes the following variables, each described
  27 fully on its own page and briefly here.
  28 </p>
  29
  30 <ul>
  31
  32 <li>
  33 <a href="pages/variables/util.test/s_break-on-test-failures_s.htm"><code>*break-on-test-failures*</code></a>:
  34 If true, <a href="../ansicl/dictentr/break.htm"><b>break</b></a> is called when
  35 a test fails.
  36 </li>
  37
  38 <li>
  39 <a href="pages/variables/util.test/s_error-protect-tests_s.htm"><code>*error-protect-tests*</code></a>: If true, errors
  40 (other than in a test-error form) will be considered a failure and
  41 testing continues.
  42 </li>
  43
  44 <li>
  45 <a href="pages/variables/util.test/s_test-errors_s.htm"><code>*test-errors*</code></a>:
  46 The value is the number of test errors which have occurred.
  47 </li>
  48
  49 <li>
  50 <a href="pages/variables/util.test/s_test-successes_s.htm"><code>*test-successes*</code></a>:
  51 The value is the number of test successes which have occurred.
  52 </li>
  53
  54 <li>
  55 <a href="pages/variables/util.test/s_test-unexpected-failures_s.htm"><code>*test-unexpected-failures*</code></a>:
  56 The value is the number of unexpected test failures which have occurred.
  57 </li>
  58
  59 </ul>
  60
  61 <hr><h2><a name="tester-macros-2">1.2 Test Harness Macros</a></h2>
  62
  63 <p>
  64 These macros wrap around a form to be tested and supply the expected
  65 value (for the test macro) or the expected behavior, which is encoded
  66 in the macro name (e.g. test-error). For example:
  67 </p>
  68
  69 <pre>
  70 (test 1 (+ 0 1))   ;; (testing that the result of (+ 0 1) is
  71                    ;; the fixnum 1)
  72 (test-error (+ 1 "2"))  ;; (testing that an error is
  73                                   ;; signaled when a string is
  74                                   ;; passed as an argument to +)
  75 </pre>
  76
  77 <p>
  78 Many more examples are given below.
  79 </p>
  80
  81 <p>
  82 <a href="pages/operators/util.test/with-tests.htm"><b>with-tests</b></a> wraps around
  83 a collection of <strong>test</strong> or <strong>test-*</strong>
  84 forms.
  85 </p>
  86
  87 <p>
  88 Note that many of the macros have <em>fail-info</em> and
  89 <em>known-failure</em> keyword arguments.
  90 </p>
  91
  92 <ul>
  93   <li><em>fail-info</em>, if non-nil, should be a string that will be printed if the test
  94     fails. Typical strings provide information about what is being tested, such as "This
  95     is bug2075".</li>
  96   <li><em>known-failure</em>, if non-nil, affects what is printed when the test fails or
  97     succeeds. Thus a failure is reported as "Test failed: known failure: ..." and a
  98     success as "Expected test failure for [...] did not occur."</li>
  99 </ul>
 100
 101 <p>
 102 Each macro is described briefly here and fully on its documentation page.
 103 </p>
 104
 105 <ul>
 106
 107 <li>
 108 <p>
 109 <a href="pages/operators/util.test/test.htm"><b>test</b></a>
 110 </p>
 111 <p><b>Arguments: </b><i>
 112 expected-value test-form
 113 </i>&key <i></i> (<i>test</i> #'eql)<i> multiple-values fail-info known-failure</i><i>
 114 </i></p>
 115 <p>
 116 Perform a single test and compare <i>expected-value</i>
 117 with the value actually returned by <i>test-form</i>.
 118 </p>
 119 </li>
 120
 121 <li>
 122 <p>
 123 <a href="pages/operators/util.test/test-error.htm"><b>test-error</b></a>
 124 </p>
 125 <p><b>Arguments: </b><i>
 126 form
 127 </i>&key <i>announce catch-breaks fail-info known-failure</i> (<i>condition-type</i> 'simple-error)<i> include-subtypes format-control format-arguments</i><i>
 128 </i></p>
 129 <p>
 130 Perform a single test to see whether
 131 <i>form</i> signals an error.
 132 </p>
 133 </li>
 134
 135 <li>
 136 <p>
 137 <a href="pages/operators/util.test/test-no-error.htm"><b>test-no-error</b></a>
 138 </p>
 139 <p><b>Arguments: </b><i>
 140 form
 141 </i>&key <i>announce catch-breaks fail-info known-failure</i><i>
 142 </i></p>
 143 <p>
 144 Perform a single test to see that
 145 <i>form</i> does not signal an error.
 146 </p>
 147 </li>
 148
 149 <li>
 150 <p>
 151 <a href="pages/operators/util.test/test-warning.htm"><b>test-warning</b></a>
 152 </p>
 153 <p><b>Arguments: </b><i>
 154 form
 155 </i>&key <i>fail-info known-failure</i><i>
 156 </i></p>
 157 <p>
 158 Perform a single test to see that
 159 <i>form</i> signals a warning.
 160 </p>
 161 </li>
 162
 163 <li>
 164 <p>
 165 <a href="pages/operators/util.test/test-no-warning.htm"><b>test-no-warning</b></a>
 166 </p>
 167 <p><b>Arguments: </b><i>
 168 form
 169 </i>&key <i>fail-info known-failure</i><i>
 170 </i></p>
 171 <p>
 172 Perform a single test to see that
 173 <i>form</i> does not signal a warning.
 174 </p>
 175 </li>
 176
 177 <li>
 178 <p>
 179 <a href="pages/operators/util.test/with-tests.htm"><b>with-tests</b></a>
 180 </p>
 181 <p><b>Arguments: </b><i>
 182 (</i>&key <i></i> (<i>name</i> "unnamed")<i>)
 183 </i> &body <i>body</i><i>
 184 </i></p>
 185 <p>
 186 Evaluates
 187 <i>body</i>, which should be a list of test forms,
 188 and reports on the results.
 189 </p>
 190 </li>
 191
 192 </ul>
 193
 194 <hr><h2><a name="tester-examples-2">1.3 Examples</a></h2>
 195
 196 <p>
 197 The following are simple examples using the test harness. The test
 198 forms themselves are trivial, and the purpose is to indicate the
 199 behavior of the test harness macros.
 200 </p>
 201
 202
 203 <pre>
 204 user(1): (require :tester)
 205 ; Fasl loading .../tester.fasl
 206 t
 207 user(2): (use-package :util.test)
 208 t
 209 user(3): (test 1 1)
 210 t
 211 user(4): (test 1 2)
 212  * * * UNEXPECTED TEST FAILURE * * *
 213 Test failed: 2
 214   wanted: 1
 215      got: 2
 216 nil
 217 user(5): (defun foo (x) x)
 218 foo
 219 user(6): (test 1 (foo 1))
 220 t
 221 user(7): (test 1 (foo 2))
 222  * * * UNEXPECTED TEST FAILURE * * *
 223 Test failed: (foo 2)
 224   wanted: 1
 225      got: 2
 226 nil
 227 user(8): (setq *break-on-test-failures* t)
 228 t
 229 user(9): (test 1 (foo 2))
 230  * * * UNEXPECTED TEST FAILURE * * *
 231 Test failed: (foo 2)
 232   wanted: 1
 233      got: 2
 234 Break: *break-on-test-failures* is non-nil.
 235
 236 Restart actions (select using :continue):
 237  0: return from break.
 238  1: Return to Top Level (an &quot;abort&quot; restart)
 239  2: Abort #&lt;process Initial Lisp Listener&gt;
 240 [1c] user(10): :pop
 241 user(11): (setq *break-on-test-failures* nil)
 242 nil
 243 user(12): (test 1 (error &quot;foo&quot;))
 244 Error: foo
 245
 246 Restart actions (select using :continue):
 247  0: Return to Top Level (an &quot;abort&quot; restart)
 248  1: Abort #&lt;process Initial Lisp Listener&gt;
 249 [1] user(13): :pop
 250 user(14): (setq *error-protect-tests* t)
 251 t
 252 user(15): (test 1 (error &quot;foo&quot;))
 253 Condition type: simple-error
 254 Message: foo
 255  * * * UNEXPECTED TEST FAILURE * * *
 256 Test failed: (error &quot;foo&quot;)
 257 Reason: an error (of type `simple-error') was detected.
 258 nil
 259 user(16): (setq *error-protect-tests* nil)
 260 nil
 261 user(17): *test-errors*
 262 4
 263 user(18): *test-successes*
 264 2
 265 user(19): (test 1 2 :known-failure t)
 266 Test failed: known failure: 2
 267   wanted: 1
 268      got: 2
 269 nil
 270 user(20): (test 1 (foo 1) :known-failure t)
 271 Expected test failure for (foo 1) did not occur.
 272 nil
 273 user(21): (test 1 (foo 1) :known-failure t :fail-info &quot;This is bug666.&quot;)
 274 Expected test failure for (foo 1) did not occur.
 275 Additional info: This is bug666.
 276 nil
 277 user(22): (test-error (error &quot;foo&quot;))
 278 t
 279 user(23): (test-no-error (error &quot;foo&quot;))
 280  * * * UNEXPECTED TEST FAILURE * * *
 281 Test failed: (error &quot;foo&quot;)
 282 Reason: detected an unexpected error of type `simple-error'.
 283 nil
 284 user(24): (test-error (car '(10)))
 285  * * * UNEXPECTED TEST FAILURE * * *
 286 Test failed: (car '(10))
 287 Reason: expected but did not detect an error of type `condition'.
 288 nil
 289 user(25): (test-no-error (car '(10)))
 290 t
 291 user(26): (test-warning (warn &quot;foo&quot;))
 292 t
 293 user(27): (test-no-warning (warn &quot;foo&quot;))
 294  * * * UNEXPECTED TEST FAILURE * * *
 295 Test failed: (warn &quot;foo&quot;)
 296   wanted: no warning
 297      got: a warning
 298 nil
 299 user(28): (test-warning (car '(10)))
 300  * * * UNEXPECTED TEST FAILURE * * *
 301 Test failed: (car '(10))
 302   wanted: a warning
 303      got: no warning
 304 nil
 305 user(29): (test-no-warning (car '(10)))
 306 t
 307 user(30): (test-error (error &quot;foo: ~a&quot; 10))
 308 t
 309 user(31): (test-error (error &quot;foo: ~a&quot; 10) :format-control &quot;foo: ~a&quot;)
 310 t
 311 user(32): (test-error (error &quot;foo: ~a&quot; 10) :format-control &quot;foo: ~a&quot;
 312             :format-arguments '(10))
 313 t
 314 user(33): (test-error (error &quot;foo: ~a&quot; 10) :format-control &quot;foo:  ~a&quot;)
 315  * * * UNEXPECTED TEST FAILURE * * *
 316 Test failed: (error &quot;foo: ~a&quot; 10)
 317 Reason: the format-control was incorrect.
 318   wanted: &quot;~1@&lt;foo: ~a~:@&gt;&quot;
 319      got: &quot;~1@&lt;foo:  ~a~:@&gt;&quot;
 320 nil
 321 user(34): (test-error (error &quot;foo: ~a&quot; 10) :format-control &quot;foo: ~a&quot;
 322             :format-arguments '(11))
 323  * * * UNEXPECTED TEST FAILURE * * *
 324 Test failed: (error &quot;foo: ~a&quot; 10)
 325 Reason: the format-arguments were incorrect.
 326   wanted: (10)
 327      got: (11)
 328 nil
 329 user(35): (test-error (error &quot;foo: ~a&quot; 10) :condition-type 'condition
 330             :include-subtypes t)
 331 t
 332 user(36): (test-error (error &quot;foo: ~a&quot; 10) :condition-type 'simple-break
 333             :include-subtypes t)
 334  * * * UNEXPECTED TEST FAILURE * * *
 335 Test failed: (error &quot;foo: ~a&quot; 10)
 336 Reason: detected an incorrect condition type.
 337   wanted: simple-break
 338      got: #&lt;standard-class simple-error&gt;
 339 nil
 340 user(37): (test-error (break &quot;foo: ~a&quot; 10) :condition-type 'simple-break
 341             :include-subtypes t)
 342 Break: foo: 10
 343   [condition type: simple-break]
 344
 345 Restart actions (select using :continue):
 346  0: return from break.
 347  1: Return to Top Level (an &quot;abort&quot; restart)
 348  2: Abort #&lt;process Initial Lisp Listener&gt;
 349 [1c] user(38): :pop
 350 user(39): (test-error (break &quot;foo: ~a&quot; 10) :catch-breaks t
 351                       :condition-type 'simple-break :include-subtypes t)
 352 t
 353 </pre>
 354
 355 </body><hr><p><small>Copyright (c) 1998-2001, Franz Inc. Berkeley, CA., USA. All rights reserved.</small><br><small>Documentation for Allegro CL version 6.1 update # 1. This page was not revised.</small><br><small>Created 2001.12.15.</small></p><table border="0" width="100%" cellpadding="1" cellspacing="0"><tr><td colspan="2" bgcolor="#00FFFF"><table border="0" cellpadding="5" cellspacing="3"><tr><td align="left" bgcolor="#00FFFF"><a href="contents.htm"><b>ToC</b></a></td><td align="left" bgcolor="#00FFFF"><a href="introduction.htm"><b>DocOverview</b></a></td><td align="left" bgcolor="#00FFFF"><a href="cgide.htm"><b>CGDoc</b></a></td><td align="left" bgcolor="#00FFFF"><a href="release-notes.htm"><b>RelNotes</b></a></td><td align="left" bgcolor="#00FFFF"><a href="index.htm"><b>Index</b></a></td><td align="left" bgcolor="#00FFFF"><a href="permuted-index.htm"><b>PermutedIndex</b></a></td></tr></table></td><td align="right"><b>Allegro CL version 6.1</b><br><small><a href="introduction.htm#updates-s">Unrevised</a></small></td></tr></table></html>