documentation/lisp-unit.html

   1 <?xml version="1.0" encoding="utf-8"?>
   2 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
   3                       "http://www.w3.org/TR/html4/loose.dtd">
   4
   5 <html xmlns="http://www.w3.org/1999/xhtml">
   6
   7 <head>
   8   <meta http-equiv="content-type" content="text/html; charset=UTF-8"></meta>
   9   <title>LISP-UNIT</title>
  10   <link href="lisp-unit.css" rel="stylesheet" type="text/css"></link>
  11 </head>
  12
  13 <body>
  14
  15 <div id="banner">LISP-UNIT</div>
  16
  17 <p>
  18   <strong>lisp-unit</strong> is a Common Lisp library that supports
  19   unit testing. It is an extension of the
  20   <a href="http://www.cs.northwestern.edu/academics/courses/325/readings/lisp-unit.html">
  21   library written by Chris Riesbeck </a>. There is a long history of
  22   testing packages in Lisp, usually called "regression" testers. More
  23   recent packages in Lisp and other languages have been inspired by
  24   JUnit for Java. For more information on both unit testing and JUnit,
  25   visit <a href="http://www.junit.org/" target="_blank">www.junit.org</a>.
  26 </p>
  27
  28 <p>This page has two parts:</p>
  29
  30 <ul>
  31   <li><a href="#overview">An overview with examples</a></li>
  32   <li><a href="#reference">A reference section with all forms and functions</a></li>
  33 </ul>
  34
  35 <a name="overview"></a>
  36 <h1>Overview</h1>
  37
  38 <p>
  39   The main goal for <strong>lisp-unit</strong> was to make it simple
  40   to use. The advantages of <strong>lisp-unit</strong> are:
  41 </p>
  42
  43 <ul>
  44   <li>Written in portable Common Lisp.</li>
  45   <li>Loadable with ASDF.</li>
  46   <li>Dead-simple to define and run tests. See <a href="#example">example</a>.</li>
  47   <li>Supports redefining functions and even macros without reloading tests.</li>
  48   <li>Supports <a href="http://www.extremeprogramming.org/rules/testfirst.html">
  49       test-first programming</a>.</li>
  50   <li>Supports testing return values, printed output, macro
  51       expansions, and error conditions.</li>
  52   <li>Produces short readable output with a reasonable level of detail.</li>
  53   <li>Groups tests by package for modularity.</li>
  54 </ul>
  55
  56 <h2>How to Use lisp-unit</h2>
  57
  58 <ol>
  59   <li>Load (or compile and load) <code>(asdf:operate 'asdf:load-op :lisp-unit)</code>.</li>
  60   <li>Evaluate <code>(in-package :lisp-unit)</code>.</li>
  61   <li>Load a file of tests.  See below for how to define tests.</li>
  62   <li>Run the tests with <code>run-tests</code>.</li>
  63 </ol>
  64
  65 <p>
  66   Any test failures will be printed, along with a summary of how many
  67   tests were run, how many passed, and how many failed.
  68 </p>
  69
  70 <p>You define a test with <code>define-test</code>:</p>
  71
  72 <pre class="code-syntax">(define-test <em>name exp<sub>1</sub> exp<sub>2</sub></em> ...)</pre>
  73
  74 <p>
  75   This defines a test called <em>name</em>. The expressions can be
  76   anything, but typically most will be <a href="#assertions">
  77   assertion forms</a>.
  78 </p>
  79
  80 <p>
  81   Tests can be defined before the code they test, even if they're
  82   testing macros. This is to support
  83   <a href="http://www.extremeprogramming.org/rules/testfirst.html">
  84   test-first programming</a>.
  85 </p>
  86
  87 <p>
  88   After defining your tests and the code they test, run the tests with
  89 </p>
  90
  91 <pre>(run-tests)</pre>
  92
  93 <p>
  94   This runs every test defined in the current package. To run just
  95   certain specific tests, use
  96 </p>
  97
  98 <pre class="code-syntax">(run-tests <em>name<sub>1</sub> name<sub>2</sub></em> ...)</pre>
  99
 100 <p>e.g., <code>(run-tests greater summit)</code>.</p>
 101
 102 <a name="example"></a>
 103 <p>The following example</p>
 104 <ul>
 105   <li>defines some tests to see if <code>my-max</code> returns the
 106       larger of two arguments</li>
 107   <li>defines a deliberately broken version of <code>my-max</code></li>
 108   <li>runs the tests</li>
 109 </ul>
 110
 111 <p>First, we define some tests.</p>
 112
 113 <pre>
 114 &gt; <b>(in-package :example)</b>
 115 #&lt;PACKAGE EXAMPLE&gt;
 116 &gt; <b>(define-test test-my-max
 117    (assert-equal 5 (my-max 2 5))
 118    (assert-equal 5 (my-max 5 2))
 119    (assert-equal 10 (my-max 10 10))
 120    (assert-equal 0 (my-max -5 0)))</b>
 121 TEST-MY-MAX
 122 </pre>
 123
 124 <p>
 125   Following good test-first programming practice, we run these tests
 126   <b>before</b> writing any code.
 127 </p>
 128
 129 <pre>
 130 &gt; <b>(run-tests test-my-max)</b>
 131 TEST-MY-MAX: Undefined function MY-MAX called with arguments (2 5).
 132 </pre>
 133
 134 <p>
 135   This shows that we need to do some work. So we define our broken
 136   version of <code>my-max</code>.
 137 </p>
 138
 139 <pre>
 140 &gt; <b>(defun my-max (x y) x)</b>  ;; <em>deliberately wrong</em>
 141 MY-MAX
 142 </pre>
 143
 144 <p>Now we run the tests again:</p>
 145
 146 <pre>
 147 &gt; <b>(run-tests my-max)</b>
 148 MY-MAX: (MY-MAX 2 5) failed: Expected 5 but saw 2
 149 MY-MAX: (MY-MAX -5 0) failed: Expected 0 but saw -5
 150 MY-MAX: 2 assertions passed, 2 failed.
 151 </pre>
 152
 153 <p>
 154   This shows two failures. In both cases, the equality test returned
 155   NIL. In the first case it was because <code>(my-max 2 5)</code>
 156   returned 2 when 5 was expected, and in the second case, it was
 157   because <code>(my-max -5 0)</code> returned -5 when 0 was expected.
 158 </p>
 159
 160 <a name="assertions"></a>
 161 <h2>Assertion Forms</h2>
 162
 163 <p>The most commonly used assertion form is </p>
 164
 165 <pre class="code-syntax">(assert-equal <em>value form</em>)</pre>
 166
 167 <p>
 168   This tallies a failure if <em>form</em> returns a value not
 169   <code>equal</code> to <em>value</em>. Both <em>value</em> and
 170   <em>test</em> are evaluated in the local lexical environment. This
 171   means that you can use local variables in tests. In particular, you
 172   can write loops that run many tests at once:
 173 </p>
 174
 175 <pre>
 176 &gt; <b>(define-test my-sqrt
 177   (dotimes (i 5)
 178     (assert-equal i (my-sqrt (* i i)))))</b>
 179 MY-SQRT
 180
 181 &gt; <b>(defun my-sqrt (n) (/ n 2))</b>   <em>;; wrong!!</em>
 182
 183 &gt; <b>(run-tests my-sqrt)</b>
 184 MY-SQRT: (MY-SQRT (* I I)) failed: Expected 1 but saw 1/2
 185 MY-SQRT: (MY-SQRT (* I I)) failed: Expected 3 but saw 9/2
 186 MY-SQRT: (MY-SQRT (* I I)) failed: Expected 4 but saw 8
 187 MY-SQRT: 2 assertions passed, 3 failed.
 188 </pre>
 189
 190 <p>
 191   However, the above output doesn't tell us for which values of
 192   <code>i</code> the code failed. Fortunately, you can fix this by
 193   adding expressions at the end of the <code>assert-equal</code>.
 194   These expression and their values will be printed on failure.
 195 </p>
 196
 197 <pre>
 198 &gt; <b>(define-test my-sqrt
 199   (dotimes (i 5)
 200     (assert-equal i (my-sqrt (* i i)) i)))</b>  <em>;; added i at the end</em>
 201 MY-SQRT
 202 &gt; <b>(run-tests my-sqrt)</b>
 203 MY-SQRT: (MY-SQRT (* I I)) failed: Expected 1 but saw 1/2
 204    I =&gt; 1
 205 MY-SQRT: (MY-SQRT (* I I)) failed: Expected 3 but saw 9/2
 206    I =&gt; 3
 207 MY-SQRT: (MY-SQRT (* I I)) failed: Expected 4 but saw 8
 208    I =&gt; 4
 209 MY-SQRT: 2 assertions passed, 3 failed.
 210 </pre>
 211
 212 <p>The next most useful assertion form is</p>
 213
 214 <pre class="code-syntax">(assert-true <em>test</em>)</pre>
 215
 216 <p>
 217   This tallies a failure if <em>test</em> returns false. Again, if you
 218   need to print out extra information, just add expressions after
 219   <em>test</em>.
 220 </p>
 221
 222 <p>
 223   There are also assertion forms to test what code prints, what errors
 224   code returns, or what a macro expands into.  A complete list of
 225   assertion forms is in <a href="#ref-assertion">the reference
 226   section</a>.
 227 </p>
 228
 229 <p class="quote">
 230   Do not confuse <code>assert-true</code> with Common Lisp's
 231   <code>assert</code> macro. <code>assert</code> is used in code to
 232   guarantee that some condition is true. If it isn't, the code
 233   halts. <code>assert</code> has options you can use to let a user fix
 234   what's wrong and resume execution. A similar collision of names
 235   exists in JUnit and Java.
 236 </p>
 237
 238 <h2>How to Organize Tests with Packages</h2>
 239
 240 <p>
 241   Tests are grouped internally by the current package, so that a set
 242   of tests can be defined for one package of code without interfering
 243   with tests for other packages.
 244 </p>
 245
 246 <p>
 247   If your code is being defined in <code>cl-user</code>, which is
 248   common when learning Common Lisp, but not for production-level code,
 249   then you should define your tests in <code>cl-user</code> as well.
 250 </p>
 251
 252 <p>
 253   If your code is being defined in its own package, you should define
 254   your tests either in that same package, or in another package for
 255   test code. The latter approach has the advantage of making sure that
 256   your tests have access to only the exported symbols of your code
 257   package.
 258 </p>
 259
 260 <p>
 261   For example, if you were defining a date package, your
 262   <code>date.lisp</code> file would look like this:
 263 </p>
 264
 265 <blockquote><pre>
 266 (defpackage :date
 267   (:use :common-lisp)
 268   (:export #:date-&gt;string #:string-&gt;date))
 269
 270 (in-package :date)
 271
 272 (defun date-&gt;string (date) ...)
 273 (defun string-&gt;date (string) ...)
 274 </pre></blockquote>
 275
 276 <p>Your <code>date-tests.lisp</code> file would look like this:</p>
 277
 278 <blockquote><pre>
 279 (defpackage :date-tests
 280   (:use :common-lisp :lisp-unit :date))
 281
 282 (in-package :date-tests)
 283
 284 (define-test date-&gt;string
 285   (assert-true (string= ... (date-&gt;string ...)))
 286   ...)
 287 ...
 288 </pre></blockquote>
 289
 290 <p>You could then run all your date tests in the test package:</p>
 291
 292 <blockquote><pre>
 293 (in-package :date-tests)
 294
 295 (run-tests)
 296 </pre></blockquote>
 297
 298 <p>
 299   Alternately, you could run all your date tests from any package
 300   with:
 301 </p>
 302
 303 <blockquote><pre>(lisp-unit:run-all-tests :date-tests)</pre></blockquote>
 304
 305 <a name="reference"></a>
 306 <h1>Reference Section</h1>
 307
 308 <p>
 309   Here is a list of the functions and macros exported by
 310   <strong>lisp-unit</strong>.
 311 </p>
 312
 313 <a name="ref-tests"></a>
 314 <h3>Functions for managing tests</h3>
 315
 316 <dl>
 317   <dt class="code-syntax">
 318     (define-test <em>name exp<sub>1</sub> exp<sub>2</sub></em> ...)
 319   </dt>
 320   <dd>
 321     This macro defines a test called <em>name</em> with the
 322     expressions specified, in the package specified by the value of
 323     <code>*package*</code> in effect when <code>define-test</code> is
 324     <u>executed</u>.  The expresssions are assembled into runnable
 325     code whenever needed by <code>run-tests</code>. Hence you can
 326     define or redefine macros without reloading tests using those
 327     macros.
 328   </dd>
 329
 330   <dt class="code-syntax">
 331     (get-tests [<em>package</em>)
 332   </dt>
 333   <dd>
 334     This function returns the names of all the tests that have been
 335     defined for the <em>package</em>. If no package is given, the
 336     value of <code>*package*</code> is used.
 337   </dd>
 338
 339   <dt class="code-syntax">
 340     (get-test-code <em>name</em> [<em>package</em>)
 341   </dt>
 342   <dd>
 343     This function returns the body of the code stored for the test
 344     <em>name</em> under <em>package</em>. If no package is given, the
 345     value of <code>*package*</code> is used.
 346   </dd>
 347
 348   <dt class="code-syntax">
 349     (remove-tests <em>names</em> [<em>package</em>])
 350   </dt>
 351   <dd>
 352     This function removes the tests named for the given package. If no
 353     package is given, the value of <code>*package*</code> is used.
 354   </dd>
 355
 356   <dt class="code-syntax">
 357     (remove-all-tests [<em>package</em>])
 358   </dt>
 359   <dd>
 360     This function removes the tests for the given package.  If no
 361     package is given, it removes all tests for the current package.
 362     If <code>nil</code> is given, it removes all tests for all
 363     packages.
 364   </dd>
 365
 366   <dt class="code-syntax">
 367     (run-all-tests <em>package</em>)
 368   </dt>
 369   <dd>
 370     This macro runs all the tests defined in the specified package and
 371     reports the results.
 372   </dd>
 373
 374   <dt class="code-syntax">
 375     (run-tests <em>name<sub>1</sub> name<sub>2</sub></em> ...)
 376   </dt>
 377   <dd>
 378     This macro runs the tests named and reports the results.  The
 379     package used is the value of <code>*package*</code> in effect when
 380     the macro is <u>expanded</u>. If no names are given, all tests for
 381     that package are run.
 382   </dd>
 383
 384   <dt class="code-syntax">
 385     (use-debugger [<em>flag</em>])
 386   </dt>
 387   <dd>
 388     By default, errors that occur while running tests are simply
 389     counted and ignored. You can change this behavior by calling
 390     <tt>use-debugger</tt> with one of three possible flag values:
 391     <tt>t</tt> (the default) means your Lisp's normal error handling
 392     routines will be invoked when errors occur; <tt>:ask</tt> means
 393     you will be asked what to do when an error occurs, and
 394     <tt>nil</tt> means errors are counted and ignored, i.e., the
 395     standard behavior.
 396   </dd>
 397 </dl>
 398
 399 <a name="ref-assertion"></a>
 400 <h3>Forms for assertions</h3>
 401
 402 <p>
 403   All of the assertion forms are macros.  They tally a failure if the
 404   associated predication returns false. Assertions can be made about
 405   return values, printed output, macro expansions, and even expected
 406   errors. Assertion form arguments are evaluated in the local lexical
 407   environment.
 408 </p>
 409
 410 <p>
 411   All assertion forms allow you to include additional expressions at
 412   the end of the form. These expressions and their values will be
 413   printed only when the test fails.
 414 </p>
 415
 416 <p>Return values are unspecified for all assertion forms.</p>
 417
 418 <dl>
 419   <dt class="code-syntax">
 420     (assert-eq <em>value</em> <em>form</em> [<em>form</em><sub>1</sub> <em>form</em><sub>2</sub> ...])
 421   </dt>
 422   <dt class="code-syntax">
 423     (assert-eql <em>value</em> <em>form</em> [<em>form</em><sub>1</sub> <em>form</em><sub>2</sub> ...])
 424   </dt>
 425   <dt class="code-syntax">
 426     (assert-equal <em>value</em> <em>form</em> [<em>form</em><sub>1</sub> <em>form</em><sub>2</sub> ...])
 427   </dt>
 428   <dt class="code-syntax">
 429     (assert-equalp <em>value</em> <em>form</em> [<em>form</em><sub>1</sub> <em>form</em><sub>2</sub> ...])
 430   </dt>
 431   <dt class="code-syntax">
 432     (assert-equality <em>predicate</em> <em>value</em> <em>form</em> [<em>form</em><sub>1</sub> <em>form</em><sub>2</sub> ...])
 433   </dt>
 434   <dd>
 435     These macros tally a failure if <em>value</em> is not equal to the
 436     result returned by <em>form</em>, using the specified equality
 437     predicate. In general, <code>assert-equal</code> is used for most
 438     tests.  Example use of <code>assert-equality</code>:
 439     <pre style="margin-left: 2%;">
 440       (assert-equality #'set-equal '(a b c) (unique-atoms '((b c) a ((b a) c))))
 441     </pre>
 442   </dd>
 443
 444   <dt class="code-syntax">
 445     (assert-true <em>test</em> [<em>form</em><sub>1</sub> <em>form</em><sub>2</sub> ...])
 446   </dt>
 447   <dt class="code-syntax">
 448     (assert-false <em>test</em> [<em>form</em><sub>1</sub> <em>form</em><sub>2</sub> ...])
 449   </dt>
 450   <dd>
 451     <code>assert-true</code> tallies a failure if <em>test</em>
 452     returns false.  <code>assert-false</code> tallies a failure if
 453     <em>test</em> returns true.
 454   </dd>
 455
 456   <dt class="code-syntax">
 457     (assert-prints "<em>output</em>" <em>form</em> [<em>form</em><sub>1</sub> <em>form</em><sub>2</sub> ...])
 458   </dt>
 459   <dd>
 460     This macro tallies a failure if form does not print to standard
 461     output stream output equal to the given string, ignoring
 462     differences in beginning and ending newlines.
 463   </dd>
 464
 465   <dt class="code-syntax">
 466     (assert-expands <em>expansion</em> <em>form</em> [<em>form</em><sub>1</sub> <em>form</em><sub>2</sub> ...])
 467   </dt>
 468   <dd>
 469     This macro tallies a failure if <code>(macroexpand-1
 470     <em>form</em>)</code> does not produce a value equal to
 471     <em>expansion</em>.
 472   </dd>
 473
 474   <dt class="code-syntax">
 475     (assert-error <em>condition-type</em> <em>form</em> [<em>form</em><sub>1</sub> <em>form</em><sub>2</sub> ...])
 476   </dt>
 477   <dd>
 478     This macro tallies a failure if <em>form</em> does not signal an
 479     error that is equal to or a subtype of
 480     <em>condition-type</em>. Use <code>error</code> to refer to any
 481     kind of error. See <a
 482     href="http://www.lisp.org/HyperSpec/Body/sec_9-1-1.html">condition
 483     types in the Common Lisp Hyperspec</a> for other possible
 484     names. For example,
 485
 486     <pre>(assert-error 'arithmetic-error (foo 0))</pre>
 487
 488     would assert that <code>foo</code> is supposed to signal an
 489     arithmetic error when passed zero.
 490   </dd>
 491 </dl>
 492
 493 <a name="ref-predicates"></a>
 494 <h3>Utility predicates</h3>
 495
 496 <p>
 497   Several predicate functions are exported that are often useful in
 498   writing tests with <code>assert-equality</code>.
 499 </p>
 500
 501 <dl>
 502   <dt class="code-syntax">
 503     (logically-equal <em>value</em><sub>1</sub> <em>value</em><sub>2</sub>)
 504   </dt>
 505   <dd>
 506     This predicate returns true of the two values are either both
 507     true, i.e., non-NIL, or both false.
 508   </dd>
 509
 510   <dt class="code-syntax">
 511     (set-equal <em>list</em><sub>1</sub> <em>list</em><sub>2</sub> [:test])
 512   </dt>
 513   <dd>
 514     This predicate returns true the first list is a subset of the
 515     second and vice versa. <code>:test</code> can be used to specify
 516     an equality predicate. The default is <code>eql</code>.
 517   </dd>
 518 </dl>
 519
 520 <h3>Floating point predicates and tests</h3>
 521
 522 <p>
 523   The original list unit has been extended with several floating point
 524   predicate functions and tests. The predicates can be used with
 525   <code>assert-equality</code> or the corresponding tests can be
 526   directly applied. All of the floating point comparisons are
 527   considered equal if the relative error between the values is less
 528   than some epsilon. The internal default value of
 529   <code>epsilon</code> is is twice the appropriate float epsilon
 530   (i.e. <code>2*single-float-epsilon</code> or
 531   <code>2*double-float-epsilon</code>). Epsilon can be controlled at a
 532   lexical level using the package variable <code>*epsilon*</code>. If
 533   <code>*epsilon*</code> is set to <code>nil</code>, the internal
 534   epsilon values are used. This is the default value of
 535   <code>epsilon</code>.
 536 </p>
 537
 538 <dl>
 539   <dt class="code-syntax">
 540     (float-equal <em>float</em><sub>1</sub> <em>float</em><sub>2</sub> [epsilon])
 541   </dt>
 542   <dt class="code-syntax">
 543     (assert-float-equal <em>value</em> <em>form</em>
 544      [<em>form</em><sub>1</sub> <em>form</em><sub>2</sub> ...])
 545   </dt>
 546   <dd>
 547     Return true if the relative error between
 548     <code>float<sub>1</sub></code> and <code>float<sub>2</sub></code>
 549     is less than <code>epsilon</code>. The test tallies the failure if
 550     <code>value</code> is not equal to the result returned from
 551     <code>form</code>, using <code>float-equal</code>.
 552   </dd>
 553
 554   <dt class="code-syntax">
 555     (complex-equal <em>complex</em><sub>1</sub> <em>complex</em><sub>2</sub> [epsilon])
 556   </dt>
 557   <dt class="code-syntax">
 558     (assert-complex-equal <em>value</em> <em>form</em>
 559      [<em>form</em><sub>1</sub> <em>form</em><sub>2</sub> ...])
 560   </dt>
 561   <dd>
 562     Return true if the relative error between
 563     Real(<code>complex<sub>1</sub></code>),
 564     Real(<code>complex<sub>2</sub></code>) and
 565     Imaginary(<code>complex<sub>1</sub></code>),
 566     Imaginary(<code>complex<sub>2</sub></code>) are each less than
 567     <code>epsilon</code>. The test tallies the failure if
 568     <code>value</code> is not equal to the result returned from
 569     <code>form</code>, using <code>complex-equal</code>.
 570   </dd>
 571   <dt class="code-syntax">
 572     (number-equal <em>number</em><sub>1</sub> <em>number</em><sub>2</sub> [epsilon])
 573   </dt>
 574
 575   <dt class="code-syntax">
 576     (assert-number-equal <em>value</em> <em>form</em>
 577      [<em>form</em><sub>1</sub> <em>form</em><sub>2</sub> ...])
 578   </dt>
 579   <dd>
 580     Return true if the error between <code>number<sub>1</sub></code>
 581     and <code>number<sub>2</sub></code> is less than
 582     <code>epsilon</code> for floating point numbers. If the numbers
 583     are integers, return true if the numbers are equal.  The test
 584     tallies the failure if <code>value</code> is not equal to the
 585     result returned from <code>form</code>, using
 586     <code>number-equal</code>.
 587   </dd>
 588
 589   <dt class="code-syntax">
 590     (sigfig-equal <em>float</em><sub>1</sub> <em>float</em><sub>2</sub> [significant-figures])
 591   </dt>
 592   <dt class="code-syntax">
 593     (assert-sigfig-equal <em>value</em> <em>form</em>
 594     [<em>form</em><sub>1</sub> <em>form</em><sub>2</sub> ...])
 595   </dt>
 596   <dd>
 597     Return true if <code>float<sub>1</sub></code> and
 598     <code>float<sub>2</sub></code> are equal to the specified
 599     <code>significant-figures</code>. The default value of significant
 600     figures is 4, set by the global variable
 601     <code>*significant-figures</code>.  The test tallies the failure
 602     if <code>value</code> is not equal to the result returned from
 603     <code>form</code>, using <code>sigfig-equal</code>.
 604   </dd>
 605
 606   <dt class="code-syntax">
 607     (array-equal <em>array</em><sub>1</sub> <em>array</em><sub>2</sub> [:test])
 608   </dt>
 609   <dt class="code-syntax">
 610     (assert-array-equal <em>test</em> <em>value</em> <em>form</em>
 611     [<em>form</em><sub>1</sub> <em>form</em><sub>2</sub> ...])
 612   </dt>
 613   <dd>
 614     Return true if each element of <code>array<sub>1</sub></code> and
 615     <code>array<sub>2</sub></code> is equal according to
 616     <code>:test</code> which defaults to <code>number-equal</code>.
 617     The test tallies the failure if <code>value</code> is not equal to
 618     the result returned from <code>form</code>, using
 619     <code>numerical-equal</code>. In general, <code>test</code> must
 620     be a function that accepts 2 arguments and returns <em>true</em>
 621     or <em>false</em>.
 622   </dd>
 623
 624   <dt class="code-syntax">
 625     (numerical-equal <em>result</em><sub>1</sub> <em>result</em><sub>2</sub> [:test])
 626   </dt>
 627   <dt class="code-syntax">
 628     (assert-numerical-equal <em>value</em> <em>form</em>
 629     [<em>form</em><sub>1</sub> <em>form</em><sub>2</sub> ...])
 630   </dt>
 631   <dd>
 632     Return true if the numerical <code>result<sub>1</sub></code> is
 633     equal to <code>result<sub>2</sub></code> as defined by
 634     <code>:test</code>. The results can be numbers, sequences, nested
 635     sequences and arrays.  The test tallies the failure if
 636     <code>value</code> is not equal to the result returned from
 637     <code>form</code>, using <code>numerical-equal</code>. In general,
 638     <code>test</code> must be a function that accepts 2 arguments and
 639     returns <em>true</em> or <em>false</em>.
 640   </dd>
 641 </dl>
 642
 643 <a name="ref-diagnostic"></a>
 644 <h3>Floating point diagnostic functions</h3>
 645
 646 <p>
 647   Failing a unit test is only half of the problem. The other half is
 648   understanding why the test failed and what is required to fix
 649   it. The default values of <em>epsilon</em> will only be applicable
 650   in a few situations. In many situations, the acceptable value of
 651   <em>epsilon</em> is dependent on the routine being examined. When
 652   testing large sequences or arrays, it is not enough to know that
 653   each element is not equal. It is usually necessary to know which
 654   specific elements are not equal. The functions presented in this
 655   section facilitate diagnosis test failures for floating point
 656   numbers, sequences and arrays. For tests that compare the relative
 657   error against epsilon, the value of epsilon can be controlled by
 658   setting <code>*epsilon*</code>. Similarly, if
 659   <code>sigfig-equal</code> is used as the test, the number of
 660   significant figures can be set by setting
 661   <code>*significant-figures*</code>.
 662 </p>
 663
 664 <dl>
 665   <dt class="code-syntax">
 666     (float-error <em>float</em><sub>1</sub> <em>float</em><sub>2</sub>)
 667   </dt>
 668   <dd>
 669     Return the relative error between <code>float<sub>1</sub></code>
 670     and <code>float<sub>2</sub></code>.
 671   </dd>
 672
 673   <dt class="code-syntax">
 674     (float-error-epsilon <em>float</em><sub>1</sub> <em>float</em><sub>2</sub> [epsilon])
 675   </dt>
 676   <dd>
 677     Return the error expressed as a multiple of epsilon.
 678     <em>(relative error)/epsilon</em>
 679   </dd>
 680
 681   <dt class="code-syntax">
 682     (complex-epsilon <em>complex</em><sub>1</sub> <em>complex</em><sub>2</sub>)
 683   </dt>
 684   <dd>
 685     Return a complex value with each component equal to the relative
 686     error between the components of <code>complex<sub>1</sub></code>
 687     and <code>complex<sub>2</sub></code>, respectively.
 688   </dd>
 689
 690   <dt class="code-syntax">
 691     (complex-error-epsilon <em>complex</em><sub>1</sub> <em>complex</em><sub>2</sub> [epsilon])
 692   </dt>
 693   <dd>
 694     Return a complex value with each component equal to the the error
 695     expressed as a multiple of epsilon.
 696     <p>
 697       <code>#C(<em>(real relative error)/epsilon</em> <em>(imaginary
 698       relative error)/epsilon</em>)</code>
 699     </p>
 700   </dd>
 701
 702   <dt class="code-syntax">
 703     (number-epsilon <em>number</em><sub>1</sub> <em>number</em><sub>2</sub>)
 704   </dt>
 705   <dd>
 706     Return the error between <code>number<sub>1</sub></code> and
 707     <code>number<sub>2</sub></code>. For float and complex numbers,
 708     the result is equivalent to <code>float-equal</code> and
 709     <code>complex-equal</code>, respectively. If the numbers are
 710     integers, the absolute difference between them is returned.
 711   </dd>
 712
 713   <dt class="code-syntax">
 714     (number-error-epsilon <em>number</em><sub>1</sub> <em>number</em><sub>2</sub> [epsilon])
 715   </dt>
 716   <dd>
 717     Return the error expressed as amultiple of epsilon. For floating
 718     point numbers, this is equivalent to
 719     <code>float-error-epsilon</code>. Similarly, for complex numbers
 720     this is equivalent to <code>complex-error-epsilon</code>. This
 721     function is not applicable to integers.
 722   </dd>
 723
 724   <dt class="code-syntax">
 725     (sequence-error <em>sequence</em><sub>1</sub> <em>sequence</em><sub>2</sub>
 726     [:test] [:error-function])
 727   </dt>
 728   <dd>
 729     Return a nested list of the elements that are not equal according
 730     <code>:test</code> with the associated index and error data
 731     reported by <code>:error-function</code>.
 732     <p>
 733       <code>(index number1 number2 <em>(error-function n1 n2)</em>)</code>
 734     </p>
 735   </dd>
 736
 737   <dt class="code-syntax">
 738     (array-error <em>array</em><sub>1</sub> <em>array</em><sub>2</sub>
 739     [:test] [:error-function])
 740   </dt>
 741   <dd>
 742     Return a nested list of the elements that are not equal according
 743     <code>:test</code> with the associated indices and error data
 744     reported by <code>:error-function</code>.
 745     <p>
 746       <code>(indices number1 number2 <em>(error-function n1 n2)</em>)</code>
 747     </p>
 748   </dd>
 749
 750 </dl>
 751
 752 <hr></hr>
 753
 754 <p id="closing">
 755   <a href="mailto:tmh.public@gmail.com">Comments or suggestions?</a>
 756 </p>
 757
 758 </body>
 759 </html>