source: project/test-infrastructure/test-infrastructure.html @ 3

Last change on this file since 3 was 3, checked in by felix winkelmann, 14 years ago

udp/test-infrastructure changes; added futures

File size: 49.3 KB
Line 
1<html>
2<head><title>Eggs Unlimited - test-infrastructure</title></head>
3<body>
4
5<center><img src="egg.jpg"></center>
6<center><a href="index.html">back</a></center>
7
8<h2>test-infrastructure</h2>
9
10<h3>Description:</h3>
11Macro based unit-testing facility
12
13<h3>Author:</h3>
14Peter Keller
15
16<h3>Version</h3>
17<ul>
18<lI>1.1
19Added several enhancements [by Kon Lovett]
20<li>1.0
21</ul>
22
23<h3>Usage:</h3> 
24<pre>
25(include "test-infrastructure")
26</pre>
27
28<p>This extension can currently only be used with the <code>syntax-case</code>
29(highlevel) macro system.
30
31<h3>Download:</h3>
32<a href="test-infrastructure.egg">test-infrastructure.egg</a>
33
34<h3>Documentation:</h3>
35
36This extension provides a macro based unit testing facility based upon
37expectations concerning evaluations of expressions. These functions return
38tagged lists which contain the results of the test package, test case,
39or expectations evaluated(there are a few other types of results dealing
40with the gloss, todo, and skip macros detailed below). These result
41lists are wired together during evaluation to form a large hierarchical
42tree in memory.  This result tree is then passed to either user defined
43functions which traverse the tree manipulating it in any way desired, or
44passed to a supplied (read: defined already in test-infrastructure.scm)
45function which manipulates it in a simple way usually producing human
46readable or html generated output. API functions to deal with the result
47types are supplied and the representation of the result is black boxed to
48the user. It is a violation of encapsulation to inspect the representation
49directly, and it may change unpredictably in the future.
50
51<p><b>The Test Package Macro API</b>
52
53<p>This macro will evaluate in a left to right fashion the clauses inside
54it. Clauses can only be certain things, detailed below. All of the clauses
55are executed, except of course if you bail out of the test package with
56the escape procedure mechanism.  Test packages may nest indefinitely.
57<dl>
58<dt><em>(macro)</em> <code> test-package</code>
59
60<pre>
61(test-package MESSAGE DESTNAME TERMNAME CLAUSES)
62(test-package MESSAGE DESTNAME TERMNAME (BINDINGS) CLAUSES)
63(test-package MESSAGE DESTNAME TERMNAME (warn MESSAGE) CLAUSES)
64(test-package MESSAGE DESTNAME TERMNAME (warn MESSAGE) (BINDINGS) CLAUSES)
65</pre>
66
67<dd>
68<ul>
69<li><code>MESSAGE</code> can be any scheme object, though usually it is a string.
70<li> <code>DESTNAME</code> is an unquoted symbol for an automatic destructor
71object that gets called when the test package completes for any reason.
72This symbol is bound to a destructor object and is available to you in
73the CLAUSES section of the test package. See below for the description
74of the destructor object interface.
75<li> <code>TERMNAME</code> is an unquoted symbol for an escape procedure
76available in the body of the test package, usually, this escape
77procedure is passed to <code>(terminate ...)</code> which calls it
78for you and performs other tasks. It is not recommended to call the escape
79procedure directly.
80<li> <code>(warn MESSAGE)</code> allows you to specify a warning object, usually
81a string, that gets associated with the test package. The
82<code>warn</code> function name is actually a syntax reserved word
83in the macro.
84<li> <code>BINDINGS</code> are let-style bindings that you may create and exist in
85the lexical scope of the test package.
86<li> <code>CLAUSES</code> are uses of <code>(test-case ...)</code> macros
87along with <code>(gloss ...)</code>, </code>(todo ...)</code>,
88<code>(skip ...)</code>, and </code>(terminate ...)</code> macros. While
89you may use the <code>(expect-* ...)</code> style macros directly in
90a test package, doing so is not recommended. If the expectation
91fails, the test package macro will continue evaluating until
92all clauses are evaluated or the escape procedure mechanism is
93activated. This is different than a test-case macro where upon
94discovery of a failed expectation, evaluation stops immediately.
95</ul>
96</dd>
97</dl>
98
99<p><b>The Test Case Macro API</b>
100
101<p>This macro will evaluate in a left to right fashion the clauses inside
102it <em>stopping at the first failed expectation</em>. Clauses can only
103be certain things as detailed below. You may also stop the execution of
104expectations if you bail out of the test case with the escape procedure
105mechanism.  Test cases may <em>NOT</em> nest.
106
107<dl>
108<dt><em>(macro)</em> <code> test-case</code>
109<pre>
110(test-case MESSAGE DESTNAME TERMNAME CLAUSES)
111(test-case MESSAGE DESTNAME TERMNAME (BINDINGS) CLAUSES)
112(test-case MESSAGE DESTNAME TERMNAME (warn MESSAGE) CLAUSES)
113(test-case MESSAGE DESTNAME TERMNAME (warn MESSAGE) (BINDINGS) CLAUSES)
114</pre>
115
116<dd>
117<ul>
118<li> <code>MESSAGE</code> can be any scheme object, though usually it is a string.
119<li> <code>DESTNAME</code> is an unquoted symbol for an automatic destructor
120object that gets called when the test case completes for any reason.
121This symbol is bound to a destructor object and is available to you in
122the CLAUSES section of the test package. See below for the description
123of the destructor object interface.
124<li> <code>TERMNAME</code> is an unquoted symbol for an escape procedure
125available in the body of the test case, usually, this escape
126procedure is passed to <code>(terminate ...)</code> which calls it
127for you and performs other tasks. It is not recommended to call the escape
128procedure directly.
129<li> <code>(warn MESSAGE)</code> allows you to specify a warning object, usually
130a string, that gets associated with the test case. The
131<code>warn</code> function name is actually a syntax reserved word
132in the macro.
133<li> <code>BINDINGS</code> are let-style bindings that you may create and exist in
134the lexical scope of the test case.
135<li> <code>CLAUSES</code> are uses of <code>(expect-* ...)</code> macros
136along with <code>(gloss ...)</code>, <code>(todo ...)</code>,
137<code>(skip ...)</code>, and <code>(terminate ...)</code> macros. It is
138important to note that upon discovery of a failed expectation,
139the test case stops its evaluation and returns with the previous
140successful, and including the failed, expectations.
141</ul>
142</dd>
143</dl>
144
145<p><b>The Expectation Macro API</b>
146<p>
147
148An expectation at its core simply evaluates its arguments and check to
149see if it matches the expectation. The positive or negative result is
150encapsulated, along with other things such as the unevaluated expressions
151being checked and some messages supplied with each expectation into
152a particular type of black box object that one can query with the
153appropriate API calls(detailed below).
154
155<p>Expectations all have a descriptive message that can be bound to them,
156along with an optional warning syntax detailed below. A design decision
157was made to supply expectation macros for the usual types of expectations
158a user needs because this reduced the abstractness of an expectation
159into something more manageable. In a future release however, I will
160supply a special expectation macro where you may supply any predicate
161you wish along with a ``type tag'' of the predicate.
162
163<dl>
164<p><dt><em>(macro)</em> <code> expect-zero</code>
165<pre>
166(expect-zero MESSAGE CLAUSE)
167(expect-zero MESSAGE (warn MESSAGE) CLAUSE)
168</pre>
169<dd>
170<ul>
171<li> This expectation checks to see if the evaluated expression passed to it
172is numerically equal to the exact integer zero.
173<li> <code>MESSAGE</code> can be any scheme object, though usually it is a string.
174<li> <code>(warn MESSAGE)</code> allows you to specify a warning object, usually
175a string, that gets associated with the expectation. The
176<code>warn</code> function name is actually a syntax reserved word
177in the macro.
178<li> <code>CLAUSE</code> is a single expression which should return a exact or
179inexact integer.
180</ul>
181</dd>
182
183
184<p><dt><em>(macro)</em> <code> expect-nonzero</code>
185<pre>
186(expect-nonzero MESSAGE CLAUSE)
187(expect-nonzero MESSAGE (warn MESSAGE) CLAUSE)
188</pre>
189<dd>
190<ul>
191<li> This expectation checks to see if the evaluated expression passed to it
192is numerically not equal to the exact integer zero.
193<li> <code>MESSAGE</code> can be any scheme object, though usually it is a string.
194<li> <code>(warn MESSAGE)</code> allows you to specify a warning object, usually
195a string, that gets associated with the expectation. The
196<code>warn</code> function name is actually a syntax reserved word
197in the macro.
198<li> <code>CLAUSE</code> is a single expression which should return an exact or
199inexact integer.
200</ul>
201</dd>
202
203
204
205<p><dt><em>(macro)</em> <code> expect-true</code>
206<pre>
207(expect-true MESSAGE CLAUSE)
208(expect-true MESSAGE (warn MESSAGE) CLAUSE)
209</pre>
210<dd>
211<ul>
212<li> This expectation checks to see if the evaluated expression passed to it
213is the value #t.
214<li> <code>MESSAGE</code> can be any scheme object, though usually it is a string.
215<li> <code>(warn MESSAGE)</code> allows you to specify a warning object, usually
216a string, that gets associated with the expectation. The
217<code>warn</code> function name is actually a syntax reserved word
218in the macro.
219<li> <code>CLAUSE</code> is a single expression which should return #t.
220</ul>
221</dd>
222
223
224
225<p><dt><em>(macro)</em> <code> expect-false</code>
226<pre>
227(expect-false MESSAGE CLAUSE)
228(expect-false MESSAGE (warn MESSAGE) CLAUSE)
229</pre>
230<dd>
231<ul>
232<li> This expectation checks to see if the evaluated expression passed to it
233is the value #f.
234<li> <code>MESSAGE</code> can be any scheme object, though usually it is a string.
235<li> <code>(warn MESSAGE)</code> allows you to specify a warning object, usually
236a string, that gets associated with the expectation. The
237<code>warn</code> function name is actually a syntax reserved word
238in the macro.
239<li> <code>CLAUSE</code> is a single expression which should return #t.
240</ul>
241</dd>
242
243
244
245<p><dt><em>(macro)</em> <code> expect-eq?</code>
246<pre>
247(expect-eq? MESSAGE EXPECTED CLAUSE)
248(expect-eq? MESSAGE (warn MESSAGE) EXPECTED CLAUSE)
249</pre>
250<dd>
251<ul>
252<li> This expectation checks to see if <code>(eq? EXPECTED CLAUSE)</code> is true.
253<li> <code>MESSAGE</code> can be any scheme object, though usually it is a string.
254<li> <code>(warn MESSAGE)</code> allows you to specify a warning object, usually
255a string, that gets associated with the expectation. The
256<code>warn</code> function name is actually a syntax reserved word
257in the macro.
258<li> <code>EXPECTED</code> is a single expression which is evaluated and represents
259the value the <code>CLAUSE</code> <em>must</em> be eq? to in order for this
260expectation to return a positive result.
261<li> <code>CLAUSE</code> is a single expression which, when evaluated must return
262an object where an eq? of this result and the <code>EXPECTED</code> expression
263is #t.
264<li> The result object this macro produce shall contain the unevaluated
265<code>CLAUSE</code> expression as a field, but not an unevaluated <code>EXPECTED</code>
266expression.
267</ul>
268</dd>
269
270
271
272<p><dt><em>(macro)</em> <code> expect-eqv?</code>
273<pre>
274(expect-eqv? MESSAGE EXPECTED CLAUSE)
275(expect-eqv? MESSAGE (warn MESSAGE) EXPECTED CLAUSE)
276</pre>
277<dd>
278<ul>
279<li> This expectation checks to see if <code>(eqv? EXPECTED CLAUSE)</code> is
280true.
281<li> <code>MESSAGE</code> can be any scheme object, though usually it is a string.
282<li> <code>(warn MESSAGE)</code> allows you to specify a warning object, usually
283a string, that gets associated with the expectation. The
284<code>warn</code> function name is actually a syntax reserved word
285in the macro.
286<li> <code>EXPECTED</code> is a single expression which is evaluated and represents
287the value the <code>CLAUSE</code> <em>must</em> be eqv? to in order for this
288expectation to return a positive result.
289<li> <code>CLAUSE</code> is a single expression which, when evaluated must return
290an object where an eqv? of this result and the <code>EXPECTED</code> expression
291is #t.
292<li> The result object this macro produce shall contain the unevaluated
293<code>CLAUSE</code> expression as a field, but not an unevaluated <code>EXPECTED</code>
294expression.
295</ul>
296</dd>
297
298
299
300<p><dt><em>(macro)</em> <code> expect-equal?</code>
301<pre>
302(expect-equal? MESSAGE EXPECTED CLAUSE)
303(expect-equal? MESSAGE (warn MESSAGE) EXPECTED CLAUSE)
304</pre>
305<dd>
306<ul>
307<li> This expectation checks to see if <code>(equal? EXPECTED CLAUSE)</code> is
308true.
309<li> <code>MESSAGE</code> can be any scheme object, though usually it is a string.
310<li> <code>(warn MESSAGE)</code> allows you to specify a warning object, usually
311a string, that gets associated with the expectation. The
312<code>warn</code> function name is actually a syntax reserved word
313in the macro.
314<li> <code>EXPECTED</code> is a single expression which is evaluated and represents
315the value the <code>CLAUSE</code> <em>must</em> be equal? to in order for this
316expectation to return a positive result.
317<li> <code>CLAUSE</code> is a single expression which, when evaluated must return
318an object where an equal? of this result and the <code>EXPECTED</code> expression
319is #t.
320<li> The result object this macro produce shall contain the unevaluated
321<code>CLAUSE</code> expression as a field, but not an unevaluated <code>EXPECTED</code>
322expression.
323</ul>
324</dd>
325
326
327
328<p><dt><em>(macro)</em> <code> expect-near?</code>
329<pre>
330(expect-near? MESSAGE EXPECTED TOL CLAUSE)
331(expect-near? MESSAGE (warn MESSAGE) EXPECTED TOL CLAUSE)
332</pre>
333<dd>
334<ul>
335<li> This expectation checks to see if
336<code>(< (abs (- EXPECTED CLAUSE)) TOL)))</code> is true.
337<li> <code>MESSAGE</code> can be any scheme object, though usually it is a string.
338<li> <code>(warn MESSAGE)</code> allows you to specify a warning object, usually
339a string, that gets associated with the expectation. The
340<code>warn</code> function name is actually a syntax reserved word
341in the macro.
342<li> <code>EXPECTED</code> is a single expression which is evaluated and represents
343the value the <code>CLAUSE</code> <em>must</em> be ``near'' to in order for this
344expectation to return a positive result.
345<li> <code>CLAUSE</code> is a single expression which should return an inexact or
346exact number.
347<li> <code>TOL</code> is a single expression which, when evaluated must return a
348tolerance value(usually a small inexact number like .0001).
349<li> The result object this macro produce shall contain the unevaluated
350<code>CLAUSE</code> expression as a field, but not the unevaluated <code>EXPECTED</code>
351or <code>TOL</code> expression.
352</ul>
353</dd>
354
355
356
357<p><dt><em>(macro)</em> <code> expect-positive</code>
358<pre>
359(expect-positive MESSAGE CLAUSE)
360(expect-positive MESSAGE (warn MESSAGE) CLAUSE)
361</pre>
362<dd>
363<ul>
364<li> This expectation checks to see if the evaluated expression passed to it
365is a positive value greater than zero.
366<li> <code>MESSAGE</code> can be any scheme object, though usually it is a string.
367<li> <code>(warn MESSAGE)</code> allows you to specify a warning object, usually
368a string, that gets associated with the expectation. The
369<code>warn</code> function name is actually a syntax reserved word
370in the macro.
371<li> <code>CLAUSE</code> is a single expression which should return an inexact or
372exact number.
373</ul>
374</dd>
375
376
377
378<p><dt><em>(macro)</em> <code> expect-negative</code>
379<pre>
380(expect-negative MESSAGE CLAUSE)
381(expect-negative MESSAGE (warn MESSAGE) CLAUSE)
382</pre>
383<dd>
384<ul>
385<li> This expectation checks to see if the evaluated expression passed to it
386is a negative value less than zero.
387<li> <code>MESSAGE</code> can be any scheme object, though usually it is a string.
388<li> <code>(warn MESSAGE)</code> allows you to specify a warning object, usually
389a string, that gets associated with the expectation. The
390<code>warn</code> function name is actually a syntax reserved word
391in the macro.
392<li> <code>CLAUSE</code> is a single expression which should return an inexact or
393exact number.
394</ul>
395</dd>
396</dl>
397
398<p><b>Result Object API</b>
399
400<p>Expectations, test cases, test packages, and helper macros(<code>gloss</code>,
401<code>todo</code>, etc) all return an object that contains the results and other various
402aspects of the action performed which ultimately get wired together to
403form the result tree. This collection of functions forming the rest of the
404test infrastructure API allows manipulation of these results in an abstracted
405way as to allow changing of the representation in the future.
406
407<p><b>Test Package Result Object API</b>
408
409<p>If any of these API functions, except <em>test-package-result?</em>,
410are passed something that isn't a test package result object, they will
411return 'not-a-test-package-result.
412
413
414<dl>
415<p><dt><em>(procedure)</em> <code> test-package-result?</code>
416<pre>
417(test-package-result? RESULT)
418</pre>
419<dd>
420If <code>RESULT</code> is a result object from the invocation
421of a test package macro, then this function will return
422#t. Otherwise, it will return #f.
423</dd>
424
425<p><dt><em>(procedure)</em> <code> test-package-result-result-ref</code>
426<pre>
427(test-package-result-result-ref RESULT)
428</pre>
429<dd>
430Returns the boolean result associated with the test package <code>RESULT</code>
431object.
432</dd>
433
434<p><dt><em>(procedure)</em> <code> test-package-result-message-ref</code>
435<pre>
436(test-package-result-message-ref RESULT)
437</pre>
438<dd>
439Returns the message object associated with the test package <code>RESULT</code>
440object.
441</dd>
442
443<p><dt><em>(procedure)</em> <code> test-package-result-exps-ref</code>
444<pre>
445(test-package-result-exps-ref RESULT)
446</pre>
447<dd>
448Returns the list of result objects associated with the test package
449<code>RESULT</code> object.
450</dd>
451
452<p><dt><em>(procedure)</em> <code> test-package-result-warning?</code>
453<pre>
454(test-package-result-warning? RESULT)
455</pre>
456<dd>
457If a warning had been attached to this test package, this function
458will return #t, otherwise it will be #f.
459</dd>
460
461<p><dt><em>(procedure)</em> <code> test-package-result-warning-ref</code>
462<pre>
463(test-package-result-warning-ref RESULT)
464</pre>
465<dd>
466If a warning had been attached to this test package, this function
467will return the warning object supplied by the user, otherwise it
468shall return <em>'()</em>.
469</dd>
470</dl>
471
472<p><b>Test Case Result Object API</b>
473
474<p>If any of these API functions, except <em>test-case-result?</em>,
475are passed something that isn't a test case result object, they will
476return 'not-a-test-case-result.
477
478
479<dl>
480<p><dt><em>(procedure)</em> <code> test-case-result?</code>
481<pre>
482(test-case-result? RESULT)
483</pre>
484<dd>
485If <code>RESULT</code> is a result object from the invocation
486of a test case macro, then this function will return
487#t. Otherwise, it will return #f.
488</dd>
489
490<p><dt><em>(procedure)</em> <code> test-case-result-result-ref</code>
491<pre>
492(test-case-result-result-ref RESULT)
493</pre>
494<dd>
495Returns the boolean result associated with the test case <code>RESULT</code>
496object.
497</dd>
498
499<p><dt><em>(procedure)</em> <code> test-case-result-message-ref</code>
500<pre>
501(test-case-result-message-ref RESULT)
502</pre>
503<dd>
504Returns the message object associated with the test case <code>RESULT</code>
505object.
506</dd>
507
508<p><dt><em>(procedure)</em> <code> test-case-result-expectations-ref</code>
509<pre>
510(test-case-result-expectations-ref RESULT)
511</pre>
512<dd>
513Returns the list of expctation result objects associated with the test
514case <code>RESULT</code> object.
515</dd>
516
517<p><dt><em>(procedure)</em> <code> test-case-result-warning?</code>
518<pre>
519(test-case-result-warning? RESULT)
520</pre>
521<dd>
522If a warning had been attached to this test case, this function
523will return #t, otherwise it will be #f.
524</dd>
525
526<p><dt><em>(procedure)</em> <code> test-case-result-warning-ref</code>
527<pre>
528(test-case-result-warning-ref RESULT)
529</pre>
530<dd>
531If a warning had been attached to this test case, this function
532will return the warning object supplied by the user, otherwise it
533shall return <em>'()</em>.
534</dd>
535</dl>
536
537
538<p><b>Expect Result Object API: Single Clause Style Expectation</b>
539
540<p>These expectations all take the form of passing a single expression to
541them to see if they match some a priori expectation.  If any of these
542API functions, except <em>expect-result?</em>, are passed something that
543isn't a single clause style expectation result object, they will return
544'not-an-expect-result.
545
546
547<dl>
548<p><dt><em>(procedure)</em> <code> expect-result?</code>
549<pre>
550(expect-result? RESULT)
551</pre>
552<dd>
553If <code>RESULT</code> is a single clause style result object from
554the invocation of an expectation macro, then this function will
555return #t. Otherwise, it will return #f.
556</dd>
557
558<p><dt><em>(procedure)</em> <code> expect-result-result-ref</code>
559<pre>
560(expect-result-result-ref RESULT)
561</pre>
562<dd>
563Returns the boolean result associated with the single clause
564style expectation <code>RESULT</code> object.
565</dd>
566
567<p><dt><em>(procedure)</em> <code> expect-result-specific-ref</code>
568<pre>
569(expect-result-specific-ref RESULT)
570</pre>
571<dd>
572This retrieves the ``specific'' field of a particular single clause
573style expectation.  For example, if you had a result object from
574an invocation of a <code>(expect-zero? "foobar" (- 1 1))</code>
575expectation, then the ``specific'' field of the expectation
576result object will be the string <em>"zero"</em>. Here is a
577table describing what the ``specific'' fields are for each kind
578of single clause style expectation:
579
580<p><table border=1>
581<tr><th>Single Clause Style Expectation</th><th>Associated Specific String</th></tr>
582<tr><td>expect-zero<td>                     "zero" </tr>
583<tr><td> expect-nonzero<td>                 "nonzero" </tr>
584<tr><td> expect-true                     <td> "true"</tr>
585<tr><td> expect-false                    <td> "false" </tr>
586<tr><td> expect-positive                 <td> "positive" </tr>
587<tr><td> expect-negative                 <td> "negative"</tr>
588</table>
589
590
591</dd>
592
593<p><dt><em>(procedure)</em> <code> expect-result-message-ref</code>
594<pre>
595(expect-result-message-ref RESULT)
596</pre>
597<dd>
598Returns the message object associated with the single clause
599style expectation <code>RESULT</code> object.
600</dd>
601
602<p><dt><em>(procedure)</em> <code> expect-result-unevaled-ref</code>
603<pre>
604(expect-result-unevaled-ref RESULT)
605</pre>
606<dd>
607Returns the unevaluated expression supplied to a single clause style
608expectation macro.
609</dd>
610
611<p><dt><em>(procedure)</em> <code> expect-result-evaled-ref</code>
612<pre>
613(expect-result-evaled-ref RESULT)
614</pre>
615<dd>Returns the evaluated expression supplied to a single clause style
616expectation macro.
617</dd>
618
619<p><dt><em>(procedure)</em> <code> expect-result-warning?</code>
620<pre>
621(expect-result-warning? RESULT)
622</pre>
623<dd>If a warning had been attached to this expectation, this function
624will return #t, otherwise it will be #f.
625</dd>
626
627<p><dt><em>(procedure)</em> <code> expect-result-warning-ref</code>
628<pre>
629(expect-result-warning-ref RESULT)
630</pre>
631<dd>If a warning had been attached to this expectation, this function
632will return the warning object supplied by the user, otherwise it
633shall return <em>'()</em>.
634</dd>
635</dl>
636
637
638<p><b>Expect Result Object API: Equivalence Style Expectation</b>
639
640<p>These expectations all take the form of passing a two expressions,
641the ``left hand side'' and the ``right hand side'' to them to see
642if they match some a priori equivalence.  The left hand side is that
643which you expect the right hand side to be equivalent. If any of these
644API functions, except <em>expect-equivalence-result?</em>, are passed
645something that isn't a single clause style expectation result object,
646they will return 'not-an-expect-equivalence-result.
647
648
649<dl>
650<p><dt><em>(procedure)</em> <code> expect-equivalence-result?</code>
651<pre>
652(expect-equivalence-result? RESULT)
653</pre>
654<dd>
655If <code>RESULT</code> is a comparison style result object from
656the invocation of an expectation macro, then this function will
657return #t. Otherwise, it will return #f.
658</dd>
659
660<p><dt><em>(procedure)</em> <code> expect-equivalence-result-result-ref</code>
661<pre>
662(expect-equivalence-result-result-ref RESULT)
663</pre>
664<dd>
665Returns the boolean result associated with the comparison style
666expectation <code>RESULT</code> object.
667</dd>
668
669<p><dt><em>(procedure)</em> <code> expect-equivalence-result-specific-ref</code>
670<pre>
671(expect-equivalence-result-specific-ref RESULT)
672</pre>
673<dd>
674This retrieves the ``specific'' field of a particular equivalence
675style expectation. For example, if you had a result object from
676an invocation of a <code>(expect-equal? "foobar" 0 (- 1 1))</code>
677expectation, then the ``specific'' field of the expectation
678result object will be the string <em>"equal"</em>. Here is a
679table describing what the ``specific'' fields are for each kind
680of equivalence style expectation:
681
682
683<p><table border=1><tr><th>Equivalence Style Expectation<th>Associated Specific String</tr>
684<tr><td> expect-eq                     <td> "eq" </tr>
685<tr><td> expect-eqv                    <td> "eqv" </tr>
686<tr><td> expect-equal                  <td> "equal"</tr>
687</table>
688
689</dd>
690
691<p><dt><em>(procedure)</em> <code> expect-equivalence-result-message-ref</code>
692<pre>
693(expect-equivalence-result-message-ref RESULT)
694</pre>
695<dd>Returns the message object associated with the equivalence
696style expectation <code>RESULT</code> object.
697</dd>
698
699<p><dt><em>(procedure)</em> <code> expect-equivalence-result-lhs-evaled-ref</code>
700<pre>
701(expect-equivalence-result-lhs-evaled-ref RESULT)
702</pre>
703<dd>Returns the evaluated ``left hand side'' expression supplied to
704an equivalence style expectation.
705</dd>
706
707<p><dt><em>(procedure)</em> <code> expect-equivalence-result-rhs-unevaled-ref</code>
708<pre>
709(expect-equivalence-result-rhs-unevaled-ref RESULT)
710</pre>
711<dd>Returns the unevaluated ``right hand side'' expression supplied
712to an equivalence style expectation.
713</dd>
714
715<p><dt><em>(procedure)</em> <code> expect-equivalence-result-rhs-evaled-ref</code>
716<pre>
717(expect-equivalence-result-rhs-evaled-ref RESULT)
718</pre>
719<dd>Returns the evaluated ``right hand side'' expression supplied
720to an equivalence style expectation.
721</dd>
722
723<p><dt><em>(procedure)</em> <code> expect-equivalence-result-warning?</code>
724<pre>
725(expect-equivalence-result-warning? RESULT)
726</pre>
727<dd>If a warning had been attached to this expectation, this function
728will return #t, otherwise it will be #f.
729</dd>
730
731<p><dt><em>(procedure)</em> <code> expect-equivalence-result-warning-ref</code>
732<pre>
733(expect-equivalence-result-warning-ref RESULT)
734</pre>
735<dd>If a warning had been attached to this expectation, this function
736will return the warning object supplied by the user, otherwise it
737shall return <em>'()</em>.
738</dd>
739</dl>
740
741
742<p><b>Expect Result Object API: Tolerance Style Expectation</b>
743
744<p>This is a specialized expectation which accepts three expressions and
745checks to see if the ``right hand side'' is within a ``tolerance''
746of the ``left hand side''. There is only one expectation in the
747tolerance style currently.  If any of these API functions, except
748<em>expect-tolerance-result?</em>, are passed something that isn't
749a tolerance style expectation result object, they will return
750'not-an-expect-tolerance-result.
751
752
753<dl>
754<p><dt><em>(procedure)</em> <code> expect-tolerance-result?</code>
755<pre>
756(expect-tolerance-result? RESULT)
757</pre>
758<dd>If <code>RESULT</code> is a tolerance style result object from
759the invocation of an expectation macro, then this function will
760return #t. Otherwise, it will return #f.
761</dd>
762
763<p><dt><em>(procedure)</em> <code> expect-tolerance-result-result-ref</code>
764<pre>
765(expect-tolerance-result-result-ref RESULT)
766</pre>
767<dd>Returns the boolean result associated with the tolerance style
768expectation <code>RESULT</code> object.
769</dd>
770
771<p><dt><em>(procedure)</em> <code> expect-tolerance-result-specific-ref</code>
772<pre>
773(expect-tolerance-result-specific-ref RESULT)
774</pre>
775<dd>This retrieves the ``specific'' field of a particular tolerance
776style expectation. For example, if you had a result object from
777an invocation of a <code>(expect-near? "foobar" 100 .01 100.001)</code>
778expectation, then the ``specific'' field of the expectation
779result object will be the string <em>"near"</em>. Here is a
780table describing what the ``specific'' fields are for each kind
781of tolerance style expectation:
782
783
784<p><table border=1><tr><th>Tolerance Style Expectation<th>Associated Specific String</tr>
785<tr><td> expect-near                 <td> "near"</tr>
786</table>
787
788
789</dd>
790
791<p><dt><em>(procedure)</em> <code> expect-tolerance-result-message-ref</code>
792<pre>
793(expect-tolerance-result-message-ref RESULT)
794</pre>
795<dd>Returns the message object associated with a tolerance
796style expectation <code>RESULT</code> object.
797</dd>
798
799<p><dt><em>(procedure)</em> <code> expect-tolerance-result-lhs-evaled-ref</code>
800<pre>
801(expect-tolerance-result-lhs-evaled-ref RESULT)
802</pre>
803<dd>Returns the evaluated ``left hand side'' expression supplied to
804a tolerance style expectation.
805</dd>
806
807<p><dt><em>(procedure)</em> <code> expect-tolerance-result-lhs-tol-evaled-ref</code>
808<pre>
809(expect-tolerance-result-lhs-tol-evaled-ref RESULT)
810</pre>
811<dd>Returns the evaluated ``tolerance'' expression supplied to
812a tolerance style expectation.
813</dd>
814
815<p><dt><em>(procedure)</em> <code> expect-tolerance-result-rhs-unevaled-ref</code>
816<pre>
817(expect-tolerance-result-rhs-unevaled-ref RESULT)
818</pre>
819<dd>Returns the unevaluated ``right hand side'' expression supplied
820to a tolerance style expectation.
821</dd>
822
823<p><dt><em>(procedure)</em> <code> expect-tolerance-result-rhs-evaled-ref</code>
824<pre>
825(expect-tolerance-result-rhs-evaled-ref RESULT)
826</pre>
827<dd>Returns the evaluated ``right hand side'' expression supplied
828to a tolerance style expectation.
829</dd>
830
831<p><dt><em>(procedure)</em> <code> expect-tolerance-result-warning?</code>
832<pre>
833(expect-tolerance-result-warning? RESULT)
834</pre>
835<dd>If a warning had been attached to this expectation, this function
836will return #t, otherwise it will be #f.
837</dd>
838
839<p><dt><em>(procedure)</em> <code> expect-tolerance-result-warning-ref</code>
840<pre>
841(expect-tolerance-result-warning-ref RESULT)
842</pre>
843<dd>If a warning had been attached to this expectation, this function
844will return the warning object supplied by the user, otherwise it
845shall return <em>'()</em>.
846</dd>
847</dl>
848
849
850<p><b>Various Helper API</b>
851
852<p>These upcoming macros and functions allow the author of the test suite to
853better control both the execution flow of the test suite and ``decoration''
854of the test suite with important information like things yet to do, or just
855plain documentation.
856
857<p><b>Termination API</b>
858
859<p>When executing in a test package or a test case, one might discover some
860catastrophic failure of such proportions that it is utterly impossible
861to continue executing the test case or test package. When that happens
862you can use the termination facility to exit the test case or test
863package. Of course, no more expressions will be evaluated in the scope of
864the termination. It is recommended that you use this method of terminating
865the test case or test package evaluation since it wraps some contextual
866information up into the termination result so you can figure out what
867happened(and where) later when analyzing the result tree.
868
869<p>When using the manipulation API for a terminate result, if you pass a
870result to one of these function that is not a terminate result, it will
871return 'not-a-terminate-result.
872
873<dl>
874<p><dt><em>(procedure)</em> <code> terminate</code>
875<pre>
876(terminate TERMFUNC MESSAGE)
877</pre>
878<dd>
879<ul>
880<li> This is the recommended termination method for a test case or a test
881package.
882<li> <code>TERMFUNC</code> is the name of the termination procedure that you
883specified in a test case or test package. You may pass any test package
884or test case termination function available to you in the lexical scope
885in which you call this function. The termination will take effect in the
886scope of the created termination function.
887<li> <code>MESSAGE</code> can be any scheme object, though usually it is a string.
888</ul>
889</dd>
890
891<p><dt><em>(procedure)</em> <code> terminate-result?</code>
892<pre>
893(terminate-result? RESULT)
894</pre>
895<dd>If <code>RESULT</code> is a termination result object from the
896invocation of a termination function, then this function will
897return #t. Otherwise, it will return #f.
898</dd>
899
900<p><dt><em>(procedure)</em> <code> terminate-result-result-ref</code>
901<pre>
902(terminate-result-result-ref RESULT)
903</pre>
904<dd>Returns the boolean result associated with the termination
905function <code>RESULT</code> object. This is currently hard coded to
906be #f.
907</dd>
908
909<p><dt><em>(procedure)</em> <code> terminate-result-scope-ref</code>
910<pre>
911(terminate-result-scope-ref RESULT)
912</pre>
913<dd>The ``scope'' of the termination result is exactly the <code>MESSAGE</code>
914parameter supplied to the test case or test package associated with the
915<code>TERMFUNC</code>.
916</dd>
917
918<p><dt><em>(procedure)</em> <code> terminate-result-container-ref</code>
919<pre>
920(terminate-result-container-ref RESULT)
921</pre>
922<dd>The ``container'' of the termination result is going to be
923either 'test-package or 'test-case depending upon which the
924<code>TERMFUNC</code> was associated.
925</dd>
926
927<p><dt><em>(procedure)</em> <code> terminate-result-message-ref</code>
928<pre>
929(terminate-result-message-ref RESULT)
930</pre>
931<dd>Returns the message object associated with the termination
932<code>RESULT</code> object.
933</dd>
934</dl>
935
936
937<p><b>Destructor Object API</b>
938<p>The destructor object allows for you to create helper functions
939which clean up for you usually in case of aborting of a test case
940or package. For example, suppose you are testing whether or not file
941writing to a file works correctly in a test case, so, you'd perform an
942expectation to open the file, and then queue a function in the destructor
943to remove the file, and then perform the expectation of the write. If
944the write(or subsequent) expectation fails, then the test case will
945<em>automatically</em> invoke the helper cleanup function specified in
946the destructor object that removes the file.
947
948<p><em>NOTE:</em> This API is still a little experimental in the sense
949that eventually he destructor object should return a typed result that
950contains the success of the individual destructor calls. But for now,
951it is functional for what it does. Also, be <em>VERY CAREFUL</em> that
952you specify the arguments to these API calls correctly since due to
953lambda functions not being comparable, this API cannot garuantee that
954a true destructor object name had been passed to it. So if you call one
955of the following API calls incorrectly, the behavior will be undefined.
956
957
958<dl>
959<p><dt><em>(procedure)</em> <code> destructor-atexit!</code>
960<pre>
961(destructor-atexit! DESTNAME FUNC ARGS ...)
962</pre>
963<dd>This will insert a promise to calculate the <code>FUNC</code> with the
964supplied <code>ARGS ...</code> into a queue in the <code>DESTNAME</code>
965destructor object. Multiple invocations of this API call will
966continue to queue up <code>(FUNC ARGS ...)</code> promises indefinitely.
967This function returns a special <em>ignore</em> type that is ignored
968by the test infrastructure system.
969</dd>
970
971<p><dt><em>(procedure)</em> <code> destructor-activate!</code>
972<pre>
973(destructor-activate! DESTNAME)
974</pre>
975<dd>This function will call, in order of queueing, all the promises
976embedded into this destructor object, and then delete the
977queue. This function is <em>ALWAYS</em> called at the completion
978of a test package or test case; so be careful that the destructor
979object doesn't contain anything harmful.  However, you may call
980it yourself and if you do, it will execute all of the queued
981promises and then <code>clear</code> itself. This function returns
982a special <em>ignore</em> type that is ignored by the test
983infrastructure system.
984</dd>
985
986<p><dt><em>(procedure)</em> <code> destructor-clear!</code>
987<pre>
988(destructor-clear! DESTNAME)
989</pre>
990<dd>This function completely removes all of the promises associated
991with the destructor object <code>DESTNAME</code>. This function
992returns a special <em>ignore</em> type that is ignored by the
993test infrastructure system.
994</dd>
995
996<p><dt><em>(procedure)</em> <code> destructor-dump</code>
997<pre>
998(destructor-dump DESTNAME)
999</pre>
1000<dd>This function, mostly used for debugging purposes, prints out
1001a simple representation of the queued atexit functions to the
1002current port.  This function returns a special <em>ignore</em>
1003type that is ignored by the test infrastructure system.
1004</dd>
1005</dl>
1006
1007
1008<p><b>Todo API</b>
1009
1010<p>The purpose of the todo API is to allow the author of a test suite the
1011ability to record into the result tree for later analysis that something
1012still needs to be done. This way you can count/manipulate this information
1013at a later date.  Todo macro invocations can occur inside of test cases
1014or test packages.
1015
1016<dl>
1017<p><dt><em>(macro)</em> <code> todo</code>
1018<pre>
1019(todo MESSAGE)
1020(todo (warn WARNING) MESSAGE)
1021</pre>
1022<dd><ul>
1023<li> <code>MESSAGE</code> can be any scheme object, though usually it is a string.
1024<li> <code>(warn WARNING)</code> allows you to specify a warning object, usually
1025a string, that gets associated with the todo. The <code>warn</code>
1026function name is actually a syntax reserved word in the macro.
1027</ul>
1028</dd>
1029
1030<p><dt><em>(procedure)</em> <code> todo-result?</code>
1031<pre>
1032(todo-result? RESULT)
1033</pre>
1034<dd>If <code>RESULT</code> is a todo result object from the
1035invocation of a todo macro, then this function will
1036return #t. Otherwise, it will return #f.
1037</dd>
1038
1039<p><dt><em>(procedure)</em> <code> todo-result-message-ref</code>
1040<pre>
1041(todo-result-message-ref RESULT)
1042</pre>
1043<dd>Returns the message object associated with the todo
1044<code>RESULT</code> object.
1045</dd>
1046
1047<p><dt><em>(procedure)</em> <code> todo-result-warning?</code>
1048<pre>
1049(todo-result-warning? RESULT)
1050</pre>
1051<dd>If a warning had been attached to this todo, this function
1052will return #t, otherwise it will be #f.
1053</dd>
1054
1055<p><dt><em>(procedure)</em> <code> todo-result-warning-ref</code>
1056<pre>
1057(todo-result-warning-ref RESULT)
1058</pre>
1059<dd>If a warning had been attached to this todo, this function
1060will return the warning object supplied by the user, otherwise it
1061shall return <em>'()</em>.
1062</dd>
1063</dl>
1064
1065
1066<p><b>Gloss API</b>
1067
1068<p>The purpose of the gloss API is to allow the author of a test suite the
1069ability to record messages into the result tree purely for documentation
1070purposes.  Gloss macro invocations can occur inside of test cases or
1071test packages.
1072
1073</dl>
1074<p><dt><em>(macro)</em> <code> gloss</code>
1075<pre>
1076(gloss MESSAGE)
1077(gloss (warn WARNING) MESSAGE)
1078</pre>
1079<dd><ul>
1080<li> <code>MESSAGE</code> can be any scheme object, though usually it is a string.
1081<li> <code>(warn WARNING)</code> allows you to specify a warning object, usually
1082a string, that gets associated with the gloss. The <code>warn</code>
1083function name is actually a syntax reserved word in the macro.
1084</ul>
1085</dd>
1086
1087<p><dt><em>(procedure)</em> <code> gloss-result?</code>
1088<pre>
1089(gloss-result? RESULT)
1090</pre>
1091<dd>If <code>RESULT</code> is a gloss result object from the
1092invocation of the gloss macro, then this function will
1093return #t. Otherwise, it will return #f.
1094</dd>
1095
1096<p><dt><em>(procedure)</em> <code> gloss-result-message-ref</code>
1097<pre>
1098(gloss-result-message-ref RESULT)
1099</pre>
1100<dd>Returns the message object associated with the gloss
1101<code>RESULT</code> object.
1102</dd>
1103
1104<p><dt><em>(procedure)</em> <code> gloss-result-warning?</code>
1105<pre>
1106(gloss-result-warning? RESULT)
1107</pre>
1108<dd>If a warning had been attached to this gloss, this function
1109will return #t, otherwise it will be #f.
1110</dd>
1111
1112<p><dt><em>(procedure)</em> <code> gloss-result-warning-ref</code>
1113<pre>
1114(gloss-result-warning-ref RESULT)
1115</pre>
1116<dd>If a warning had been attached to this gloss, this function
1117will return the warning object supplied by the user, otherwise it
1118shall return <em>'()</em>.
1119</dd>
1120</dl>
1121
1122
1123<p><b>Skip API</b>
1124
1125<p>The purpose of the skip API is to allow the author of a test suite
1126to completely skip evaluation of a set of expresssions.  Skip macro
1127invocations can occur inside of test cases or test packages.
1128
1129<dl>
1130<p><dt><em>(macro)</em> <code> skip</code>
1131<pre>
1132(skip MESSAGE CLAUSES)
1133(skip (warn WARNING) MESSAGE CLAUSES)
1134</pre>
1135<dd><ul>
1136<li> <code>MESSAGE</code> can be any scheme object, though usually it is a string.
1137<li> <code>(warn WARNING)</code> allows you to specify a warning object, usually
1138a string, that gets associated with the gloss. The <code>warn</code>
1139function name is actually a syntax reserved word in the macro.
1140<li> <code>CLAUSES</code> can be more than one expression(as in a lambda form)
1141that does <em>NOT</em> get evaluated at any time.
1142</ul>
1143</dd>
1144
1145<p><dt><em>(procedure)</em> <code> skip-result?</code>
1146<pre>
1147(skip-result? RESULT)
1148</pre>
1149<dd>If <code>RESULT</code> is a skip result object from the
1150invocation of the skip macro, then this function will
1151return #t. Otherwise, it will return #f.
1152</dd>
1153
1154<p><dt><em>(procedure)</em> <code> skip-result-message-ref</code>
1155<pre>
1156(skip-result-message-ref RESULT)
1157</pre>
1158<dd>Returns the message object associated with the skip
1159<code>RESULT</code> object. Hopefully, it was stated why this
1160set of clauses had been skipped.
1161</dd>
1162
1163<p><dt><em>(procedure)</em> <code> skip-result-warning?</code>
1164<pre>
1165(skip-result-warning? RESULT)
1166</pre>
1167<dd>If a warning had been attached to this skip, this function
1168will return #t, otherwise it will be #f.
1169</dd>
1170
1171<p><dt><em>(procedure)</em> <code> skip-result-warning-ref</code>
1172<pre>
1173(skip-result-warning-ref RESULT)
1174</pre>
1175<dd>If a warning had been attached to this skip, this function
1176will return the warning object supplied by the user, otherwise it
1177shall return <em>'()</em>.
1178</dd>
1179</dl>
1180
1181
1182<p><b>Side Effect API</b>
1183
1184<p>This section of the API just contains a single macro currently since
1185it is considered a little experimental for now.  The side effecting
1186evaluates all of its arguments as in a <code>(begin ...)</code> form, it
1187returns a result that is completely ignored by the system and unavailable
1188to the output analysis code.
1189
1190<dl>
1191<p><dt><em>(macro)</em> <code> side-effect</code>
1192<pre>
1193(side-effect CLAUSES)
1194</pre>
1195<dd>This macro expands into a begin form the clauses in order and when it
1196finishes evaluating them, returns a result that is silently ignored by
1197the testing infrastructure system. Usually this is used in conjunction with
1198<code>(set! ...)</code> or with complicated situations where a lot of setup
1199work must happen for an expectation to be performed.
1200</dd>
1201</dl>
1202
1203
1204
1205<p><b>Miscellaneous API</b>
1206
1207<p>This section contains a few functions whose purpose is to simplify certain
1208kinds of manipulations of result objects.
1209
1210<dl>
1211<p><dt><em>(procedure)</em> <code> *-restult?</code>
1212<pre>
1213(*-result? RESULTOBJ)
1214</pre>
1215<dd>
1216This function will return #t of <code>RESULTOBJ</code> is any kind of an
1217evaluated result object. Otherwise, it shall return #f.
1218</dd>
1219
1220<p><dt><em>(procedure)</em> <code> *-result-ref</code>
1221<pre>
1222(*-result-ref RESULTOBJ)
1223</pre>
1224<dd>This function will return the result of any kind of <code>RESULTOBJ</code>
1225passed to it if it is indeed a true result object. Otherwise, it
1226shall emit an error to the current port, and return #f.
1227</dd>
1228
1229<p><dt><em>(procedure)</em> <code> all-testpackage-results-true?</code>
1230<pre>
1231(all-testpackage-results-true? RESULTLIST)
1232</pre>
1233<dd>This function takes the result of a call to
1234<code>(test-package-result-result-ref PACKAGERESULTOBJ)</code> and returns
1235#t if every single contained result in that list had been true, or #f
1236otherwise.
1237</dd>
1238
1239<p><dt><em>(procedure)</em> <code> all-testcase-expectations-true?</code>
1240<pre>
1241(all-testcase-expectations-true? RESULTLIST)
1242</pre>
1243<dd>This function takes the result of a call to
1244<code>(test-case-result-result-ref CASERESULTOBJ)</code> and returns
1245#t if every single contained result in that list had been true, or #f
1246otherwise.
1247</dd>
1248</dl>
1249
1250
1251<p><b>Analysis of the Result Tree</b>
1252       
1253<p>Once a result tree has been evaluated and constructed in memory, what
1254do you do with it? Well, you can do anything you want with it if you
1255choose to write the analysis or output generation functions and pass it
1256the evaluated result tree, and this is, in fact, encouraged. However,
1257usually you just want to print out the tree in a human readable format so
1258you can check things before the serious analysis code gets written. So,
1259to save work for the test suite designer, a tiny API has been written
1260to produce human readable output given a tree of results rooted in a
1261single test package. Of course the single test package may have many
1262other test packages and test cases embedded within it.
1263
1264<p><b>Output Generation API</b>
1265
1266<p>
1267<dl>
1268<p><dt><em>(procedure)</em> <code> printnl</code>
1269<pre>
1270(printnl CLAUSES)
1271</pre>
1272<dd>This function will print all of the evaluated <code>CLAUSES</code>
1273in order with a newline at the end of it.
1274</dd>
1275
1276<p><dt><em>(procedure)</em> <code> printinl</code>
1277<pre>
1278(printinl INDENT CLAUSES)
1279</pre>
1280<dd>This function will <code>INDENT</code> a number of spaces and then
1281print all of the evaluated <code>CLAUSES</code> in order with a
1282newline at the end of it.
1283</dd>
1284
1285<p><dt><em>(procedure)</em> <code> output-style-human</code>
1286<em>(procedure)</em> <code> output-style-html</code>
1287<em>(procedure)</em> <code> output-text-compact</code>
1288<pre>
1289(output-style-human RESULTTREE)
1290(output-style-html RESULTTREE)
1291(output-text-compact RESULTTREE)
1292</pre>
1293<dd>These functions will print out a text, html or compact text rendering of the
1294<code>RESULTTREE</code> and return the toplevel package result. <p><code>output-text-compact</code>
1295has been contributed by Patrick Brannan.
1296</dd>
1297</dl>
1298
1299<p><b>Example Usages of the Test Suite Infrastructure</b>
1300
1301<p>This section contains some simple examples of how to author test suites.
1302
1303<p>Here is a simple example:
1304
1305<pre>
1306(let ((result
1307        ;; output-style-human function requires a single test package
1308        ;; to encapsulate everything.
1309        (test-package "Arithmetic Operators" pd pe
1310
1311                (test-case "Testing '+'" d e
1312                        (expect-equal "Adding two positive numbers" 2 (+ 1 1))
1313                        (expect-equal "Adding two negative numbers" -2 (+ -1 -1))
1314                        (expect-zero "Adding positive and negative" (+ -1 1)))
1315
1316                (test-case "Testing '-'" d e
1317                        (expect-zero "Subtracting two positive numbers" (- 1 1))
1318                        (expect-zero "Subtracting two negative numbers" (- -1 -1))
1319                        (expect-equal "Subtracting positive and negative" -2 (- -1 1))))))
1320        (output-style-human result))
1321</pre>
1322
1323<p>The above example, when evaluated, will produce some human readable output
1324and the a #t value as the result of the top level package. The <code>result</code>
1325variable contains the tree of evaluated expectations, test cases, and the
1326package arranged in a hierarchy extremely similar to the nesting of the
1327above macros. If you desire to manipulate the result tree yourself, you
1328may use the various APIs to manipulate the various results. Please see the
1329implementation of <code>(output-style-human ...)</code> (it isn't large) in the
1330test-infrastructure.scm file to see an example of this.
1331
1332<p>The variables: <code>pe, e</code> are the escape functions you may use with the
1333<code>(terminate ...)</code> function call if you wish to abort the above code
1334somewhere.
1335
1336<p>The variables: <code>pd, d</code> allow use of a "destructor" object which allows
1337you to run side effecting functions at the "finishing" point of the evaluation
1338of the test case or test package. These functions are run no matter if the code
1339succeeded correctly or not, so be careful to manage the destructor object
1340carefully so you don't perform unwanted side effects. The names of the
1341destructor objects you supply are lexically scoped in the bodies of the
1342test case or test package.
1343
1344<p>Now, here is some example output that <code>(output-style-human ...)</code> might
1345generate with the above testing code:
1346
1347<pre>
1348Begin Package: Arithmetic Operators
1349  Begin Test Case: Testing '+'
1350    Begin Expectation: Adding two positive numbers
1351    Expect equal
1352      Expected Value:
1353      2
1354      Unevaluated:
1355      (+ 1 1)
1356      Evaluated:
1357      2
1358    Result: #t
1359    End Expectation: Adding two positive numbers
1360
1361    Begin Expectation: Adding two negative numbers
1362    Expect equal
1363      Expected Value:
1364      -2
1365      Unevaluated:
1366      (+ -1 -1)
1367      Evaluated:
1368      -2
1369    Result: #t
1370    End Expectation: Adding two negative numbers
1371
1372    Begin Expectation: Adding positive and negative
1373    Expect zero
1374      Unevaluated:
1375      (+ -1 1)
1376      Evaluated:
1377      0
1378    Result: #t
1379    End Expectation: Adding positive and negative
1380
1381  Result: #t
1382  End Test Case: Testing '+'
1383
1384  Begin Test Case: Testing '-'
1385    Begin Expectation: Subtracting two positive numbers
1386    Expect zero
1387      Unevaluated:
1388      (- 1 1)
1389      Evaluated:
1390      0
1391    Result: #t
1392    End Expectation: Subtracting two positive numbers
1393
1394    Begin Expectation: Subtracting two negative numbers
1395    Expect zero
1396      Unevaluated:
1397      (- -1 -1)
1398      Evaluated:
1399      0
1400    Result: #t
1401    End Expectation: Subtracting two negative numbers
1402
1403    Begin Expectation: Subtracting positive and negative
1404    Expect equal
1405      Expected Value:
1406      -2
1407      Unevaluated:
1408      (- -1 1)
1409      Evaluated:
1410      -2
1411    Result: #t
1412    End Expectation: Subtracting positive and negative
1413
1414  Result: #t
1415  End Test Case: Testing '-'
1416
1417Result: #t
1418End Package: Arithmetic Operators
1419
1420#t
1421</pre>
1422
1423<h3>License:</h3>
1424
1425<pre>
1426Copyright (c) 2000-2005, Peter Keller - All rights reserved.
1427
1428<p>Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following
1429conditions are met:
1430
1431<p>  Redistributions of source code must retain the above copyright notice, this list of conditions and the following
1432    disclaimer.
1433<p>  Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
1434    disclaimer in the documentation and/or other materials provided with the distribution.
1435<p>  Neither the name of the author nor the names of its contributors may be used to endorse or promote
1436    products derived from this software without specific prior written permission.
1437
1438<p>THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS
1439OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
1440AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
1441CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
1442CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
1443SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
1444THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
1445OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
1446POSSIBILITY OF SUCH DAMAGE.
1447</pre>
1448
1449
1450<hr><a href="index.html">back</a>
1451
1452</body>
1453</html>
Note: See TracBrowser for help on using the repository browser.