Wiki
Download
Manual
Eggs
API
Tests
Bugs
show
edit
history
You can edit this page using
wiki syntax
for markup.
Article contents:
== Outdated egg! This is an egg for CHICKEN 3, the unsupported old release. You're almost certainly looking for [[/eggref/4/test-infrastructure|the CHICKEN 4 version of this egg]], if it exists. If it does not exist, there may be equivalent functionality provided by another egg; have a look at the [[https://wiki.call-cc.org/chicken-projects/egg-index-4.html|egg index]]. Otherwise, please consider porting this egg to the current version of CHICKEN. [[tags: egg]] == test-infrastructure [[toc:]] === Description Macro based unit-testing facility === Author [[Peter Keller]] === Requirements Requires the [[syntax-case]] egg, and Chicken 2.225 or later. === Download [[http://code.call-cc.org/legacy-eggs/3/test-infrastructure.egg|test-infrastructure.egg]] === Documentation This extension can currently only be used with the [[syntax-case]] (highlevel) macro system. This extension provides a macro based unit testing facility based upon expectations concerning evaluations of expressions. These functions return tagged lists which contain the results of the test package, test case, or expectations evaluated (there are a few other types of results dealing with the gloss, todo, and skip macros detailed below). These result lists are wired together during evaluation to form a large hierarchical tree in memory. This result tree is then passed to either user defined functions which traverse the tree manipulating it in any way desired, or passed to a supplied function which manipulates it in a simple way usually producing human readable or html generated output. API functions to deal with the result types are supplied and the representation of the result is black boxed to the user. It is a violation of encapsulation to inspect the representation directly, and it may change unpredictably in the future. The term {{MESSAGE}} below means the name given to a test element. While this can be any Scheme object {{#f}} is interpreted as a missing name. Further, {{#f}} is assumed when a name is missing. Thus, the name of all un-named test elements is the same - {{#f}}. ==== The Immediate Test Macro API <macro>(test-it (EXPRESSION EXPECTED) ...)</macro> In the above, {{EXPRESSION}} and {{EXPECTED}} can be any scheme expression. This macro will evaluate in a left to right fashion the clauses inside it and output the results. The clauses are a sequence of {{(EXPRESSION EXPECTATION)}} forms. A clause is evaluated as {{(expect-equal 'EXPRESSION EXPECTATION EXPRESSION)}}. For use in a REPL. The results are not kept and no other forms are allowed in the body. ==== The Quick Test Macro API This macro will execute the test procedure and send the results to a stylist procedure. The specifiers can be used to select and de-select test packages, groups, cases, and expectations. <macro>(test-apply [STYLER] [SPECIFIER ...] THUNK)</macro> {{STYLER}} is a single argument procedure taking the test result object, {{output-style-minimal}} when missing. {{SPECIFIER}} is {{(skip MESSAGE ...)}} or {{(take MESSAGE ...)}}, where MESSAGE is a test element name as below. The {{skip}} specifier causes the named test elements not to be performed and the {{take}} specifier is the opposite. Do not use these forms together, they override each other. Only named test elements can be selected. Unnamed elements are always performed. Also, {{(skip CLAUSE ...)}} forms, see below, still apply. {{THUNK}} is a zero argument procedure returning a test result object. Do not de-select all, or omit to select least one, test packages or groups. Otherwise the result will be ill-formed. The results are not kept. ==== The Test Message Introspection API Provides information on the tree structure of a test. This macro will walk the test procedure(s), only capturing the type and message of each test element. An association list is returned where the key is the element type ({{thunk}}, {{package}}, {{case}}, {{expect}}) and the value is the message (which will be {{#f}} when the element is not named). The {{thunk}} element value is the symbolic form of the {{THUNK}}. <macro>(test-named-structure THUNK ...)</macro> It is best if the {{THUNK}} argument is a procedure variable, and not a procedure object. The association list is a pre-order of the test hierarchy. <procedure>(walk-test-named-structure PROCEDURE NAMED-STRUCTURE)</procedure> This procedure will enumerate the {{NAMED-STRUCTURE}} association list, invoking the {{PROCEDURE}} for each element. The hierarchy level value is the tree depth at the point of call. {{PROCEDURE}} is a three argument procedure. The first argument is the hierarchy level, counting up from 0. The second argument is the type of the test element, as above. The third argument is the name of the test element. ==== The Simple Test Package Macro API This macro will evaluate in a left to right fashion the clauses inside it. Clauses can only be certain things, detailed below. All of the clauses are executed, except of course if you bail out of the test group with the escape procedure mechanism. Note that a test group is a test package. The destructor object name is {{destructor}}. The escape procedure name is {{escape}}. Each nesting will lexically shadow the previous such definitions of an outer test group. <macro>(test-group [MESSAGE] [(BINDINGS)] CLAUSES)</macro> {{MESSAGE}} can be any scheme object, though usually it is a string. {{BINDINGS}} are let-style bindings that you may create and exist in the lexical scope of the test package. {{CLAUSES}} are uses of {{(test-group ...)}}, {{(test-package ...)}}, {{(test-case ...)}}, {{(expect* ...)}} along with {{(gloss ...)}}, {{(todo ...)}}, {{(skip ...)}}, and {{(terminate ...)}} macros. If the expectation fails, the test group macro will continue evaluating until all clauses are evaluated or the escape procedure mechanism is activated. This is different than a test-case macro where upon discovery of a failed expectation, evaluation stops immediately. ==== The Test Package Macro API This macro will evaluate in a left to right fashion the clauses inside it. Clauses can only be certain things, detailed below. All of the clauses are executed, except of course if you bail out of the test package with the escape procedure mechanism. Test groups and packages may nest indefinitely. <macro>(test-package MESSAGE DESTNAME TERMNAME [(warn MESSAGE)] [(BINDINGS)] CLAUSES)</macro> {{MESSAGE}} can be any scheme object, though usually it is a string. {{DESTNAME}} is an unquoted symbol for an automatic destructor object that gets called when the test package completes for any reason. This symbol is bound to a destructor object and is available to you in the CLAUSES section of the test package. See below for the description of the destructor object interface. {{TERMNAME}} is an unquoted symbol for an escape procedure available in the body of the test package, usually, this escape procedure is passed to {{(terminate ...)}} which calls it for you and performs other tasks. It is not recommended to call the escape procedure directly. {{(warn MESSAGE)}} allows you to specify a warning object, usually a string, that gets associated with the test package. The {{warn}} function name is actually a syntax reserved word in the macro. {{BINDINGS}} are let-style bindings that you may create and exist in the lexical scope of the test package. {{CLAUSES}} are uses of {{(test-group ...)}}, {{(test-package ...)}}, {{(test-case ...)}} macros along with {{(gloss ...)}}, {{(todo ...)}}, {{(skip ...)}}, and {{(terminate ...)}} macros. While you may use the {{(expect* ...)}} style macros directly in a test package, doing so is not recommended. If the expectation fails, the test package macro will continue evaluating until all clauses are evaluated or the escape procedure mechanism is activated. This is different than a test-case macro where upon discovery of a failed expectation, evaluation stops immediately. ==== The Test Case Macro API This macro will evaluate in a left to right fashion the clauses inside it, ''stopping at the first failed expectation''. Clauses can only be certain things as detailed below. You may also stop the execution of expectations if you bail out of the test case with the escape procedure mechanism. Test cases may ''NOT'' nest. <macro>(test-case MESSAGE DESTNAME TERMNAME [(warn MESSAGE)] [(BINDINGS)] CLAUSES)</macro> {{MESSAGE}} can be any scheme object, though usually it is a string. {{DESTNAME}} is an unquoted symbol for an automatic destructor object that gets called when the test case completes for any reason. This symbol is bound to a destructor object and is available to you in the CLAUSES section of the test package. See below for the description of the destructor object interface. {{TERMNAME}} is an unquoted symbol for an escape procedure available in the body of the test case, usually, this escape procedure is passed to {{(terminate ...)}} which calls it for you and performs other tasks. It is not recommended to call the escape procedure directly. {{(warn MESSAGE)}} allows you to specify a warning object, usually a string, that gets associated with the test case. The {{warn}} function name is actually a syntax reserved word in the macro. {{BINDINGS}} are let-style bindings that you may create and exist in the lexical scope of the test case. {{CLAUSES}} are uses of {{(expect* ...)}} macros along with {{(gloss ...)}}, {{(todo ...)}}, {{(skip ...)}}, and {{(terminate ...)}} macros. It is important to note that upon discovery of a failed expectation, the test case stops its evaluation and returns with the previous successful, and including the failed, expectations. This behavior can be changed using the {{test-continue?}} form. This behavior reverts to default at the start of each test-case. ==== The Expectation Macro API An expectation at its core simply evaluates its arguments and check to see if it matches the expectation. The positive or negative result is encapsulated, along with other things such as the unevaluated expressions being checked and some messages supplied with each expectation into a particular type of black box object that one can query with the appropriate API calls (detailed below). Expectations all have a descriptive message that can be bound to them, along with an optional warning syntax detailed below. A design decision was made to supply expectation macros for the usual types of expectations a user needs because this reduced the abstractness of an expectation into something more manageable. Expectations are evaluated under an exception handler. An unexpected exception is treated as expectation failure. Note that only the {{CLAUSE}} expression evaluation traps exceptions. Any exceptions in setup or teardown expressions will not be caught by the test-infrastructure. ===== expect <macro>(expect [MESSAGE] [(warn MESSAGE)] KIND PREDICATE CLAUSE)</macro> This expectation checks to see if the evaluated expression passed to it meets the predicate condition. {{MESSAGE}} can be any scheme object, though usually it is a string. {{(warn MESSAGE)}} allows you to specify a warning object, usually a string, that gets associated with the expectation. The {{warn}} function name is actually a syntax reserved word in the macro. {{KIND}} is a string stating the kind of test. {{PREDICATE}} is a procedure of one argument to perform the test. {{CLAUSE}} is a single expression which should return a value meeting the conditions of the predicate. ===== expect-zero <macro>(expect-zero [MESSAGE] [(warn MESSAGE)] CLAUSE)</macro> This expectation checks to see if the evaluated expression passed to it is numerically equal to the exact integer zero. {{MESSAGE}} can be any scheme object, though usually it is a string. {{(warn MESSAGE)}} allows you to specify a warning object, usually a string, that gets associated with the expectation. The {{warn}} function name is actually a syntax reserved word in the macro. {{CLAUSE}} is a single expression which should return a exact or inexact integer. ===== expect-nonzero <macro>(expect-nonzero [MESSAGE] [(warn MESSAGE)] CLAUSE)</macro> This expectation checks to see if the evaluated expression passed to it is numerically not equal to the exact integer zero. {{MESSAGE}} can be any scheme object, though usually it is a string. {{(warn MESSAGE)}} allows you to specify a warning object, usually a string, that gets associated with the expectation. The {{warn}} function name is actually a syntax reserved word in the macro. {{CLAUSE}} is a single expression which should return an exact or inexact integer. ===== expect-true <macro>(expect-true [MESSAGE] [(warn MESSAGE)] CLAUSE)</macro> This expectation checks to see if the evaluated expression passed to it is the value {{#t}}. {{MESSAGE}} can be any scheme object, though usually it is a string. {{(warn MESSAGE)}} allows you to specify a warning object, usually a string, that gets associated with the expectation. The {{warn}} function name is actually a syntax reserved word in the macro. {{CLAUSE}} is a single expression which should return {{#t}}. ===== expect-false <macro>(expect-false [MESSAGE] [(warn MESSAGE)] CLAUSE)</macro> This expectation checks to see if the evaluated expression passed to it is the value {{{#f}}. {{MESSAGE}} can be any scheme object, though usually it is a string. {{(warn MESSAGE)}} allows you to specify a warning object, usually a string, that gets associated with the expectation. The {{warn}} function name is actually a syntax reserved word in the macro. {{CLAUSE}} is a single expression which should return {{#f}}. ===== expect-success <macro>(expect-success [MESSAGE] [(warn MESSAGE)] CLAUSE)</macro> This expectation checks to see if the evaluated expression passed to it is the value {{#t}}, or a non-error exception occured. {{MESSAGE}} can be any scheme object, though usually it is a string. {{(warn MESSAGE)}} allows you to specify a warning object, usually a string, that gets associated with the expectation. The {{warn}} function name is actually a syntax reserved word in the macro. {{CLAUSE}} is a single expression which should return {{#t}}, or generate a non-error exception. ===== expect-failure <macro>(expect-failure [MESSAGE] [(warn MESSAGE)] CLAUSE)</macro> This expectation checks to see if the evaluated expression passed to it is the value {{#f}}, or an error exception occured. {{MESSAGE}} can be any scheme object, though usually it is a string. {{(warn MESSAGE)}} allows you to specify a warning object, usually a string, that gets associated with the expectation. The {{warn}} function name is actually a syntax reserved word in the macro. {{CLAUSE}} is a single expression which should return {{#f}}, or generate an error exception. ===== expect-not-false (expect-not-false [MESSAGE] [(warn MESSAGE)] CLAUSE) This expectation checks to see if the evaluated expression passed to it is not the value {{#f}}. {{MESSAGE}} can be any scheme object, though usually it is a string. {{(warn MESSAGE)}} allows you to specify a warning object, usually a string, that gets associated with the expectation. The {{warn}} function name is actually a syntax reserved word in the macro. {{CLAUSE}} is a single expression which should not return {{#f}}, any other value is accepted. ===== expect-equiv <macro>(expect-equiv [MESSAGE] [(warn MESSAGE)] KIND PREDICATE EXPECTED CLAUSE)</macro> This expectation checks to see if {{(PREDICATE EXPECTED CLAUSE)}} is true. {{MESSAGE}} can be any scheme object, though usually it is a string. {{(warn MESSAGE)}} allows you to specify a warning object, usually a string, that gets associated with the expectation. The {{warn}} function name is actually a syntax reserved word in the macro. {{EXPECTED}} is a single expression which is evaluated and represents the value the {{CLAUSE}} ''must'' be equiv? to in order for this expectation to return a positive result. {{CLAUSE}} is a single expression which, when evaluated must return an object where an equiv? of this result and the {{EXPECTED}} expression is {{#t}}. {{KIND}} is a string stating the kind of test. {{PREDICATE}} is a procedure of two arguments to perform the test. The result object this macro produce shall contain the unevaluated {{CLAUSE}} expression as a field, but not an unevaluated {{EXPECTED}} expression. ===== expect-eq <macro>(expect-eq [MESSAGE] [(warn MESSAGE)] EXPECTED CLAUSE)</macro> This expectation checks to see if {{(eq? EXPECTED CLAUSE)}} is true. {{MESSAGE}} can be any scheme object, though usually it is a string. {{(warn MESSAGE)}} allows you to specify a warning object, usually a string, that gets associated with the expectation. The {{warn}} function name is actually a syntax reserved word in the macro. {{EXPECTED}} is a single expression which is evaluated and represents the value the {{CLAUSE}} ''must'' be {{eq?}} to in order for this expectation to return a positive result. {{CLAUSE}} is a single expression which, when evaluated must return an object where an eq? of this result and the {{EXPECTED}} expression is {{#t}}. The result object this macro produce shall contain the unevaluated {{CLAUSE}} expression as a field, but not an unevaluated {{EXPECTED}} expression. ===== expect-eqv <macro>(expect-eqv [MESSAGE] [(warn MESSAGE)] EXPECTED CLAUSE)</macro> This expectation checks to see if {{(eqv? EXPECTED CLAUSE)}} is true. {{MESSAGE}} can be any scheme object, though usually it is a string. {{(warn MESSAGE)}} allows you to specify a warning object, usually a string, that gets associated with the expectation. The {{warn}} function name is actually a syntax reserved word in the macro. {{EXPECTED}} is a single expression which is evaluated and represents the value the {{CLAUSE}} ''must'' be {{eqv?}} to in order for this expectation to return a positive result. {{CLAUSE}} is a single expression which, when evaluated must return an object where an eqv? of this result and the {{EXPECTED}} expression is {{#t}}. The result object this macro produce shall contain the unevaluated {{CLAUSE}} expression as a field, but not an unevaluated {{EXPECTED}} expression. ===== expect-equal <macro>(expect-equal [MESSAGE] [(warn MESSAGE)] EXPECTED CLAUSE)</macro> This expectation checks to see if {{(equal? EXPECTED CLAUSE)}} is true. {{MESSAGE}} can be any scheme object, though usually it is a string. {{(warn MESSAGE)}} allows you to specify a warning object, usually a string, that gets associated with the expectation. The {{warn}} function name is actually a syntax reserved word in the macro. {{EXPECTED}} is a single expression which is evaluated and represents the value the {{CLAUSE}} ''must'' be equal? to in order for this expectation to return a positive result. {{CLAUSE}} is a single expression which, when evaluated must return an object where an equal? of this result and the {{EXPECTED}} expression is {{#t}}. The result object this macro produce shall contain the unevaluated {{CLAUSE}} expression as a field, but not an unevaluated {{EXPECTED}} expression. ===== expect-values <macro>(expect-values [MESSAGE] [(warn MESSAGE)] PREDICATE CLAUSE)</macro> This expectation checks to see if the evaluated multi-valued expression passed to it meets the criteria of the single argument procedure {{PREDICATE}}. {{MESSAGE}} can be any scheme object, though usually it is a string. {{(warn MESSAGE)}} allows you to specify a warning object, usually a string, that gets associated with the expectation. The {{warn}} function name is actually a syntax reserved word in the macro. {{PREDICATE}} is a procedure taking a single list argument and returning {{#t}} or {{#f}}. {{CLAUSE}} is a single expression which has a multi-valued result. ===== expect-values-eq <macro>(expect-values-eq [MESSAGE] [(warn MESSAGE)] VALUES CLAUSE)</macro> This expectation checks to see if the result of the evaluated multi-valued expression passed to it is element-wise {{eq?}} to the {{VALUES}} list. The count of returned multiple values must match the length of the {{VALUES}} list. {{MESSAGE}} can be any scheme object, though usually it is a string. {{(warn MESSAGE)}} allows you to specify a warning object, usually a string, that gets associated with the expectation. The {{warn}} function name is actually a syntax reserved word in the macro. {{VALUES}} is a list of values. {{CLAUSE}} is a single expression which has a multi-valued result. ===== expect-values-eqv <macro>(expect-values-eqv [MESSAGE] [(warn MESSAGE)] VALUES CLAUSE)</macro> This expectation checks to see if the result of the evaluated multi-valued expression passed to it is element-wise eqv? to the {{VALUES}} list. The count of returned multiple values must match the length of the {{VALUES}} list. {{MESSAGE}} can be any scheme object, though usually it is a string. {{(warn MESSAGE)}} allows you to specify a warning object, usually a string, that gets associated with the expectation. The {{warn}} function name is actually a syntax reserved word in the macro. {{VALUES}} is a list of values. {{CLAUSE}} is a single expression which has a multi-valued result. ===== expect-values-equal <macro>(expect-values-equal [MESSAGE] [(warn MESSAGE)] VALUES CLAUSE)</macro> This expectation checks to see if the result of the evaluated multi-valued expression passed to it is element-wise {{equal?}} to the {{VALUES}} list. The count of returned multiple values must match the length of the {{VALUES}} list. {{MESSAGE}} can be any scheme object, though usually it is a string. {{(warn MESSAGE)}} allows you to specify a warning object, usually a string, that gets associated with the expectation. The {{warn}} function name is actually a syntax reserved word in the macro. {{VALUES}} is a list of values. {{CLAUSE}} is a single expression which has a multi-valued result. ===== expect-near <macro>(expect-near [MESSAGE] [(warn MESSAGE)] EXPECTED TOL CLAUSE)</macro> This expectation checks to see if {{(< (abs (- EXPECTED CLAUSE)) TOL)}} is true. {{MESSAGE}} can be any scheme object, though usually it is a string. {{(warn MESSAGE)}} allows you to specify a warning object, usually a string, that gets associated with the expectation. The {{warn}} function name is actually a syntax reserved word in the macro. {{EXPECTED}} is a single expression which is evaluated and represents the value the {{CLAUSE}} ''must'' be "near" to in order for this expectation to return a positive result. {{CLAUSE}} is a single expression which should return an inexact or exact number. {{TOL}} is a single expression which, when evaluated must return a tolerance value (usually a small inexact number like .0001). The result object this macro produce shall contain the unevaluated {{CLAUSE}} expression as a field, but not the unevaluated {{EXPECTED}} or {{TOL}} expression. ===== expect-positive <macro>(expect-positive [MESSAGE] [(warn MESSAGE)] CLAUSE)</macro> This expectation checks to see if the evaluated expression passed to it is a positive value greater than zero. {{MESSAGE}} can be any scheme object, though usually it is a string. {{(warn MESSAGE)}} allows you to specify a warning object, usually a string, that gets associated with the expectation. The {{warn}} function name is actually a syntax reserved word in the macro. {{CLAUSE}} is a single expression which should return an inexact or exact number. ===== expect-negative <macro>(expect-negative [MESSAGE] [(warn MESSAGE)] CLAUSE)</macro> This expectation checks to see if the evaluated expression passed to it is a negative value less than zero. {{MESSAGE}} can be any scheme object, though usually it is a string. {{(warn MESSAGE)}} allows you to specify a warning object, usually a string, that gets associated with the expectation. The {{warn}} function name is actually a syntax reserved word in the macro. {{CLAUSE}} is a single expression which should return an inexact or exact number. ===== expect-exception <macro>(expect-exception [MESSAGE] [(warn MESSAGE)] EXN CLAUSE)</macro> This expectation checks to see if the evaluated expression passed to it signals an exception that matches the supplied exception pattern {{EXN}}. {{MESSAGE}} can be any scheme object, though usually it is a string. {{(warn MESSAGE)}} allows you to specify a warning object, usually a string, that gets associated with the expectation. The {{warn}} function name is actually a syntax reserved word in the macro. {{EXN}} is a specialized logical expression describing the expected exception, a condition as defined by SRFI-12. {{CLAUSE}} is a single expression which should signal an exception matching EXN. EXN : COND-EXN | SIMP-EXN | () SIMP-EXN : KINDKEY | (property KINDKEY PROP-EXPR ...) | (SIMP-EXN ...) COND-EXN : (and EXN ...) | (or EXN ...) | (not EXN) PROP-EXPR : COND-PROP-EXPR | SIMP-PROP-EXPR | () SIMP-PROP-EXPR : PROPKEY | (PROPKEY ...) | (PROPKEY VALUE) | (PREDICATE PROPKEY VALUE) COND-PROP-EXPR : (and PROP-EXPR ...) | (or PROP-EXPR ...) | (not PROP-EXPR) Here's an example: <enscript highlight="scheme"> (test-case "exn1" d e ([exn1 (make-composite-condition (make-property-condition 'abc 'cbs "pbs") (make-property-condition 'foo 'bar "zip"))]) (expect-exception "1" (foo abc) (signal exn1)) ;; These are the same test, the 2nd has an explicit predicate (expect-exception "2" ((property foo (bar "zip")) (property abc (cbs "pbs"))) (signal exn1)) (expect-exception "3" ((property foo (equal? bar "zip")) (property abc (equal? cbs "pbs"))) (signal exn1))) </enscript> ===== expect-ec <macro>(expect-ec [MESSAGE] [(warn MESSAGE)] QUALIFIER ... EXPECTED [=> PREDICATE] CLAUSE)</macro> This expectation checks to see if {{(PREDICATE EXPECTED CLAUSE)}} is true for every state produced by the set of {{QUALIFIER}}. {{MESSAGE}} can be any scheme object, though usually it is a string. {{(warn MESSAGE)}} allows you to specify a warning object, usually a string, that gets associated with the expectation. The {{warn}} function name is actually a syntax reserved word in the macro. {{CLAUSE}} and {{EXPECTED}} are expressions. {{PREDICATE}} is a two argument procedure returning a boolean, {{equal?}} is used when missing. {{QUALIFIER}} is a SRFI-42 {{<qualifier>}. An eager comprehension implementation, as described by [[http://srfi.schemers.org/srfi-42/srfi-42.html|SRFI-42]] must be provided to use this expectation. ===== expect-set! <macro>(expect-set! ID EXPR)</macro> Evaluates {{EXPR}} under an {{expect-success}}. When successful a {{test:set!}} is performed of the {{EXPR}} to {{ID}}. The {{EXPR}} is therefore evaluated '''twice'''. ===== expect-successful-failure <macro>(expect-successful-failure EXPR)</macro> Same as {{(expect-success "Failure" EXPR)}}. ==== Testeez-like API A suite of synonyms for the {{expect-*}} macros. Note that the {{(warn WARNING)}} argument form is not supported. Here {{DESC}} is the same as {{MESSAGE}}, and {{EXPR}} is the same as {{CLAUSE}}. * <macro>(test/zero [DESC] EXPR)</macro> * <macro>(test/nonzero [DESC] EXPR)</macro> * <macro>(test/true [DESC] EXPR)</macro> * <macro>(test/false [DESC] EXPR)</macro> * <macro>(test/success [DESC] EXPR)</macro> * <macro>(test/failure [DESC] EXPR)</macro> * <macro>(test/positive [DESC] EXPR)</macro> * <macro>(test/negative [DESC] EXPR)</macro> * <macro>(test/not-false [DESC] EXPR)</macro> * <macro>(test/equiv [DESC] EXPR EXPECTED PRED)</macro> * <macro>(test/eq [DESC] EXPR EXPECTED)</macro> * <macro>(test/eqv [DESC] EXPR EXPECTED)</macro> * <macro>(test/equal [DESC] EXPR EXPECTED)</macro> * <macro>(test/near [DESC] EXPR EXPECTED [TOL 0.0001])</macro> * <macro>(test/values [DESC] EXPR EXPECTED)</macro> * <macro>(test/values-eq [DESC] EXPR EXPECTED)</macro> * <macro>(test/values-eqv [DESC] EXPR EXPECTED)</macro> * <macro>(test/values-equal [DESC] EXPR EXPECTED)</macro> * <macro>(test/exception [DESC] EXPR EXPECTED)</macro> * <macro>(test/ec [DESC] QUALIFIER ... EXPECTED [=> PRED] EXPR)</macro> {{test/ec}} is just a synonym. Cannot follow testeez argument order pattern. ==== Result Object API Expectations, test cases, test packages, and helper macros ({{gloss}}, {{todo}}, etc) all return an object that contains the results and other various aspects of the action performed which ultimately get wired together to form the result tree. This collection of functions forming the rest of the test infrastructure API allows manipulation of these results in an abstracted way as to allow changing of the representation in the future. ===== Test Package Result Object API If any of these API functions, except ''test-package-result?'', are passed something that isn't a test package result object, they will return {{'not-a-test-package-result}}. <procedure>(test-package-result? RESULT)</procedure> If {{RESULT}} is a result object from the invocation of a test package macro, then this function will return {{#t}}. Otherwise, it will return {{#f}}. <procedure>(test-package-result-result-ref RESULT)</procedure> Returns the boolean result associated with the test package {{RESULT}} object. <procedure>(test-package-result-message-ref RESULT)</procedure> Returns the message object associated with the test package {{RESULT}} object. <procedure>(test-package-result-exps-ref RESULT)</procedure> Returns the list of result objects associated with the test package {{RESULT}} object. <procedure>(test-package-result-warning? RESULT)</procedure> If a warning had been attached to this test package, this function will return {{#t}}, otherwise it will be {{#f}}. <procedure>(test-package-result-warning-ref RESULT)</procedure> If a warning had been attached to this test package, this function will return the warning object supplied by the user, otherwise it shall return {{'()}}. ===== Test Case Result Object API If any of these API functions, except {{test-case-result?}}, are passed something that isn't a test case result object, they will return {{'not-a-test-case-result}}. <procedure>(test-case-result? RESULT)</procedure> If {{RESULT}} is a result object from the invocation of a test case macro, then this function will return {{#t}}. Otherwise, it will return {{#f}}. <procedure>(test-case-result-result-ref RESULT)</procedure> Returns the boolean result associated with the test case {{RESULT}} object. <procedure>(test-case-result-message-ref RESULT)</procedure> Returns the message object associated with the test case {{RESULT}} object. <procedure>(test-case-result-expectations-ref RESULT)</procedure> Returns the list of expectation result objects associated with the test case {{RESULT}} object. <procedure>(test-case-result-warning? RESULT)</procedure> If a warning had been attached to this test case, this function will return {{#t}}, otherwise it will be {{#f}}. <procedure>(test-case-result-warning-ref RESULT)</procedure> If a warning had been attached to this test case, this function will return the warning object supplied by the user, otherwise it shall return {{'()}}. ===== Expect Result Object API: Single Clause Style Expectation These expectations all take the form of passing a single expression to them to see if they match some a priori expectation. If any of these API functions, except {{expect-result?}}, are passed something that isn't a single clause style expectation result object, they will return {{'not-an-expect-result}}. <procedure>(expect-result? RESULT)</procedure> If {{RESULT}} is a single clause style result object from the invocation of an expectation macro, then this function will return {{#t}}. Otherwise, it will return {{#f}}. <procedure>(expect-result-result-ref RESULT)</procedure> Returns the boolean result associated with the single clause style expectation {{RESULT}} object. <procedure>(expect-result-specific-ref RESULT)</procedure> This retrieves the {{specific}} field of a particular single clause style expectation. For example, if you had a result object from an invocation of a {{(expect-zero? "foobar" (- 1 1))}} expectation, then the {{specific}} field of the expectation result object will be the string {{"zero"}}. Here is a table describing what the {{specific}} fields are for each kind of single clause style expectation: <table border="1"> <tr><th>Single Clause Style Expectation</th><th>Associated Specific String</th></tr> <tr><td>expect-zero</td> <td>"zero"</td></tr> <tr><td>expect-nonzero</td> <td>"nonzero"</td></tr> <tr><td>expect-true</td> <td>"true"</td></tr> <tr><td>expect-not-false</td> <td>"not-false"</td></tr> <tr><td>expect-false</td> <td>"false"</td></tr> <tr><td>expect-positive</td> <td>"positive"</td></tr> <tr><td>expect-negative</td> <td>"negative"</td></tr> <tr><td>expect</td> <td>{{KIND}}</td></tr> </table> <procedure>(expect-result-message-ref RESULT)</procedure> Returns the message object associated with the single clause style expectation {{RESULT}} object. <procedure>(expect-result-unevaled-ref RESULT)</procedure> Returns the unevaluated expression supplied to a single clause style expectation macro. <procedure>(expect-result-evaled-ref RESULT)</procedure> Returns the evaluated expression supplied to a single clause style expectation macro. <procedure>(expect-result-warning? RESULT)</procedure> If a warning had been attached to this expectation, this function will return {{#t}}, otherwise it will be {{#f}}. <procedure>(expect-result-warning-ref RESULT)</procedure> If a warning had been attached to this expectation, this function will return the warning object supplied by the user, otherwise it shall return {{'()}}. ===== Expect Result Object API: Equivalence Style Expectation These expectations all take the form of passing a two expressions, the "left hand side" and the "right hand side" to them to see if they match some a priori equivalence. The left hand side is that which you expect the right hand side to be equivalent. If any of these API functions, except {{expect-equivalence-result?}}, are passed something that isn't a single clause style expectation result object, they will return {{'not-an-expect-equivalence-result}}. <procedure>(expect-equivalence-result? RESULT)</procedure> If {{RESULT}} is a comparison style result object from the invocation of an expectation macro, then this function will return {{#t}}. Otherwise, it will return {{#f}}. <procedure>(expect-equivalence-result-result-ref RESULT)</procedure> Returns the boolean result associated with the comparison style expectation {{RESULT}} object. <procedure>(expect-equivalence-result-specific-ref RESULT)</procedure> This retrieves the "specific" field of a particular equivalence style expectation. For example, if you had a result object from an invocation of a {{(expect-equal? "foobar" 0 (- 1 1))}} expectation, then the {{specific}} field of the expectation result object will be the string {{"equal"}}. Here is a table describing what the {{specific}} fields are for each kind of equivalence style expectation: <table border="1"><tr><th>Equivalence Style Expectation</th><th>Associated Specific String</th></tr> <tr><td>expect-eq</td> <td>"eq"</td></tr> <tr><td>expect-eqv</td> <td>"eqv"</td></tr> <tr><td>expect-equal</td> <td>"equal"</td></tr> <tr><td>expect-exception</td> <td>"exception"</td></tr> <tr><td>expect-equiv</td> <td>{{KIND}}</td></tr> </table> <procedure>(expect-equivalence-result-message-ref RESULT)</procedure> Returns the message object associated with the equivalence style expectation {{RESULT}} object. <procedure>(expect-equivalence-result-lhs-evaled-ref RESULT)</procedure> Returns the evaluated "left hand side" expression supplied to an equivalence style expectation. <procedure>(expect-equivalence-result-rhs-unevaled-ref RESULT)</procedure> Returns the unevaluated "right hand side" expression supplied to an equivalence style expectation. <procedure>(expect-equivalence-result-rhs-evaled-ref RESULT)</procedure> Returns the evaluated "right hand side" expression supplied to an equivalence style expectation. <procedure>(expect-equivalence-result-warning? RESULT)</procedure> If a warning had been attached to this expectation, this function will return {{#t}}, otherwise it will be {{#f}}. <procedure>(expect-equivalence-result-warning-ref RESULT)</procedure> If a warning had been attached to this expectation, this function will return the warning object supplied by the user, otherwise it shall return {{'()}}. ===== Expect Result Object API: Tolerance Style Expectation This is a specialized expectation which accepts three expressions and checks to see if the "right hand side" is within a "tolerance" of the "left hand side". There is only one expectation in the tolerance style currently. If any of these API functions, except {{expect-tolerance-result?}}, are passed something that isn't a tolerance style expectation result object, they will return {{'not-an-expect-tolerance-result}}. <procedure>(expect-tolerance-result? RESULT)</procedure> If {{RESULT}} is a tolerance style result object from the invocation of an expectation macro, then this function will return {{#t}}. Otherwise, it will return {{#f}}. <procedure>(expect-tolerance-result-result-ref RESULT)</procedure> Returns the boolean result associated with the tolerance style expectation {{RESULT}} object. <procedure>(expect-tolerance-result-specific-ref RESULT)</procedure> This retrieves the {{specific}} field of a particular tolerance style expectation. For example, if you had a result object from an invocation of a {{(expect-near? "foobar" 100 .01 100.001)}} expectation, then the {{specific}} field of the expectation result object will be the string {{"near"}}. Here is a table describing what the {{specific}} fields are for each kind of tolerance style expectation <procedure>(expect-tolerance-result-message-ref RESULT)</procedure> Returns the message object associated with a tolerance style expectation {{RESULT}} object. <procedure>(expect-tolerance-result-lhs-evaled-ref RESULT)</procedure> Returns the evaluated "left hand side" expression supplied to a tolerance style expectation. <procedure>(expect-tolerance-result-lhs-tol-evaled-ref RESULT)</procedure> Returns the evaluated {{tolerance}} expression supplied to a tolerance style expectation. <procedure>(expect-tolerance-result-rhs-unevaled-ref RESULT)</procedure> Returns the unevaluated "right hand side" expression supplied to a tolerance style expectation. <procedure>(expect-tolerance-result-rhs-evaled-ref RESULT)</procedure> Returns the evaluated "right hand side" expression supplied to a tolerance style expectation. <procedure>(expect-tolerance-result-warning? RESULT)</procedure> If a warning had been attached to this expectation, this function will return {{#t}}, otherwise it will be {{#f}}. <procedure>(expect-tolerance-result-warning-ref RESULT)</procedure> If a warning had been attached to this expectation, this function will return the warning object supplied by the user, otherwise it shall return {{'()}}. ==== Various Helper API These upcoming macros and functions allow the author of the test suite to better control both the execution flow of the test suite and ``decoration'' of the test suite with important information like things yet to do, or just plain documentation. ===== Termination API When executing in a test package or a test case, one might discover some catastrophic failure of such proportions that it is utterly impossible to continue executing the test case or test package. When that happens you can use the termination facility to exit the test case or test package. Of course, no more expressions will be evaluated in the scope of the termination. It is recommended that you use this method of terminating the test case or test package evaluation since it wraps some contextual information up into the termination result so you can figure out what happened (and where) later when analyzing the result tree. When using the manipulation API for a terminate result, if you pass a result to one of these function that is not a terminate result, it will return 'not-a-terminate-result. <procedure>(terminate TERMFUNC MESSAGE)</procedure> This is the recommended termination method for a test case or a test package. {{TERMFUNC}} is the name of the termination procedure that you specified in a test case or test package. You may pass any test package or test case termination function available to you in the lexical scope in which you call this function. The termination will take effect in the scope of the created termination function. {{MESSAGE}} can be any scheme object, though usually it is a string. <procedure>(terminate-result? RESULT)</procedure> If {{RESULT}} is a termination result object from the invocation of a termination function, then this function will return {{#t}}. Otherwise, it will return {{#f}}. <procedure>(terminate-result-result-ref RESULT)</procedure> Returns the boolean result associated with the termination function {{RESULT}} object. This is currently hard coded to be {{#f}}. <procedure>(terminate-result-scope-ref RESULT)</procedure> The ''scope'' of the termination result is exactly the {{MESSAGE}} parameter supplied to the test case or test package associated with the {{TERMFUNC}}. <procedure>(terminate-result-container-ref RESULT)</procedure> The ''container'' of the termination result is going to be either {{'test-package}} or {{'test-case}} depending upon which the {{TERMFUNC}} was associated. <procedure>(terminate-result-message-ref RESULT)</procedure> Returns the message object associated with the termination {{RESULT}} object. ===== Destructor Object API The destructor object allows for you to create helper functions which clean up for you usually in case of aborting of a test case or package. For example, suppose you are testing whether or not file writing to a file works correctly in a test case, so, you'd perform an expectation to open the file, and then queue a function in the destructor to remove the file, and then perform the expectation of the write. If the write (or subsequent) expectation fails, then the test case will ''automatically'' invoke the helper cleanup function specified in the destructor object that removes the file. '''NOTE:''' This API is still a little experimental in the sense that eventually he destructor object should return a typed result that contains the success of the individual destructor calls. But for now, it is functional for what it does. Also, be ''VERY CAREFUL'' that you specify the arguments to these API calls correctly since due to lambda functions not being comparable, this API cannot guarantee that a true destructor object name had been passed to it. So if you call one of the following API calls incorrectly, the behavior will be undefined. <procedure>(destructor-atexit! DESTNAME FUNC ARGS ...)</procedure> This will insert a promise to calculate the {{FUNC}} with the supplied {{ARGS ...}} into a queue in the {{DESTNAME}} destructor object. Multiple invocations of this API call will continue to queue up {{(FUNC ARGS ...)}} promises indefinitely. This function returns a special ''ignore'' type that is ignored by the test infrastructure system. <procedure>(destructor-activate! DESTNAME)</procedure> This function will call, in order of queueing, all the promises embedded into this destructor object, and then delete the queue. This function is ''ALWAYS'' called at the completion of a test package or test case; so be careful that the destructor object doesn't contain anything harmful. However, you may call it yourself and if you do, it will execute all of the queued promises and then {{clear}} itself. This function returns a special ''ignore'' type that is ignored by the test infrastructure system. <procedure>(destructor-clear! DESTNAME)</procedure> This function completely removes all of the promises associated with the destructor object {{DESTNAME}}. This function returns a special ''ignore'' type that is ignored by the test infrastructure system. <procedure>(destructor-dump DESTNAME)</procedure> This function, mostly used for debugging purposes, prints out a simple representation of the queued atexit functions to the current port. This function returns a special ''ignore'' type that is ignored by the test infrastructure system. ==== Todo API The purpose of the todo API is to allow the author of a test suite the ability to record into the result tree for later analysis that something still needs to be done. This way you can count/manipulate this information at a later date. Todo macro invocations can occur inside of test cases or test packages. <macro>(todo MESSAGE)</macro> <macro>(todo (warn WARNING) MESSAGE)</macro> {{MESSAGE}} can be any scheme object, though usually it is a string. {{(warn WARNING)}} allows you to specify a warning object, usually a string, that gets associated with the todo. The {{warn}} function name is actually a syntax reserved word in the macro. <procedure>(todo-result? RESULT)</procedure> If {{RESULT}} is a todo result object from the invocation of a todo macro, then this function will return {{#t}}. Otherwise, it will return {{#f}}. <procedure>(todo-result-message-ref RESULT)</procedure> Returns the message object associated with the todo {{RESULT}} object. <procedure>(todo-result-warning? RESULT)</procedure> If a warning had been attached to this todo, this function will return {{#t}}, otherwise it will be {{#f}}. <procedure>(todo-result-warning-ref RESULT)</procedure> If a warning had been attached to this todo, this function will return the warning object supplied by the user, otherwise it shall return {{'()}}. ==== Gloss API The purpose of the gloss API is to allow the author of a test suite the ability to record messages into the result tree purely for documentation purposes. Gloss macro invocations can occur inside of test cases or test packages. <macro>(gloss MESSAGE)</macro> <macro>(gloss (warn WARNING) MESSAGE)</macro> {{MESSAGE}} can be any scheme object, though usually it is a string. {{(warn WARNING)}} allows you to specify a warning object, usually a string, that gets associated with the gloss. The {{warn}} function name is actually a syntax reserved word in the macro. <procedure>(gloss-result? RESULT)</procedure> If {{RESULT}} is a gloss result object from the invocation of the gloss macro, then this function will return {{#t}}. Otherwise, it will return {{#f}}. <procedure>(gloss-result-message-ref RESULT)</procedure> Returns the message object associated with the gloss {{RESULT}} object. <procedure>(gloss-result-warning? RESULT)</procedure> If a warning had been attached to this gloss, this function will return {{#t}}, otherwise it will be {{#f}}. <procedure>(gloss-result-warning-ref RESULT)</procedure> If a warning had been attached to this gloss, this function will return the warning object supplied by the user, otherwise it shall return {{'()}}. ==== Skip API The purpose of the skip API is to allow the author of a test suite to completely skip evaluation of a set of expressions. Skip macro invocations can occur inside of test cases or test packages. <macro>(skip MESSAGE CLAUSES)</macro> <macro>(skip (warn WARNING) MESSAGE CLAUSES)</macro> {{MESSAGE}} can be any scheme object, though usually it is a string. {{(warn WARNING)}} allows you to specify a warning object, usually a string, that gets associated with the gloss. The {{warn}} function name is actually a syntax reserved word in the macro. {{CLAUSES}} can be more than one expression (as in a lambda form) that does ''NOT'' get evaluated at any time. <procedure>(skip-result? RESULT)</procedure> If {{RESULT}} is a skip result object from the invocation of the skip macro, then this function will return {{#t}}. Otherwise, it will return {{#f}}. <procedure>(skip-result-message-ref RESULT)</procedure> Returns the message object associated with the skip {{RESULT}} object. Hopefully, it was stated why this set of clauses had been skipped. <procedure>(skip-result-warning? RESULT)</procedure> If a warning had been attached to this skip, this function will return {{#t}}, otherwise it will be {{#f}}. <procedure>(skip-result-warning-ref RESULT)</procedure> If a warning had been attached to this skip, this function will return the warning object supplied by the user, otherwise it shall return {{'()}}. ==== Side Effect API This section of the API is considered a little experimental for now. The side effecting evaluates all of its arguments as in a {{(begin ...)}} form, it returns a result that is completely ignored by the system and unavailable to the output analysis code. <macro>(side-effect CLAUSES)</macro> This macro expands into a begin form the clauses in order and when it finishes evaluating them, returns a result that is silently ignored by the testing infrastructure system. Usually this is used in conjunction with {{(set! ...)}} or with complicated situations where a lot of setup work must happen for an expectation to be performed. <macro>(test-continue? BOOLEAN)</macro> This macro will set the test-case evaluation continuation flag to the boolean value. <macro>(test-timing? BOOLEAN)</macro> This macro will set the expect timing flag. <macro>(test:set! VAR EXPR)</macro> Sets the local variable to the result of the expression. ==== Miscellaneous API This section contains a few functions whose purpose is to simplify certain kinds of manipulations of result objects. <procedure>(*-result? RESULT-OBJ)</procedure> This function will return {{#t}} of {{RESULT-OBJ}} is any kind of an evaluated result object. Otherwise, it shall return {{#f}}. <procedure>(*-result-ref RESULT-OBJ)</procedure> This function will return the result of any kind of {{RESULT-OBJ}} passed to it if it is indeed a true result object. Otherwise, it shall emit an error to the current port, and return {{#f}}. <procedure>(*-result-timing-values-ref RESULT-OBJ)</procedure> This function will return the timing values of any kind of {{RESULT-OBJ}} passed to it if it is indeed a true result object. Otherwise, it shall emit an error to the current port, and return {{#f}}. The timing values will either be a list of the milliseconds spent in user code and in system code, or {{#f}} when no timing was performed, for the test corresponding to this test-result-object. For example, the list {{(6 1)}} indicates 6 milliseconds spent in user code and 1 millisecond spent in system code. <procedure>(all-testpackage-results-true? RESULT-LIST)</procedure> This function takes the result of a call to {{(test-package-result-result-ref PACKAGE-RESULT-OBJ)}} and returns {{#t}} if every single contained result in that list had been true, or {{#f}} otherwise. <procedure>(all-testcase-expectations-true? RESULT-LIST)</procedure> This function takes the result of a call to {{(test-case-result-result-ref CASE-RESULT-OBJ)}} and returns {{#t}} if every single contained result in that list had been true, or {{#f}} otherwise. ==== Analysis of the Result Tree Once a result tree has been evaluated and constructed in memory, what do you do with it? Well, you can do anything you want with it if you choose to write the analysis or output generation functions and pass it the evaluated result tree, and this is, in fact, encouraged. However, usually you just want to print out the tree in a human readable format so you can check things before the serious analysis code gets written. So, to save work for the test suite designer, a tiny API has been written to produce human readable output given a tree of results rooted in a single test package. Of course the single test package may have many other test packages and test cases embedded within it. ===== Statistics Generation API <procedure>(stat-compute-statistics RESULT-TREE)</procedure> This function will compute and return a vector of result statistics. Use the procedures below to access the elements by name. <procedure>(stat-packages-ref STATISTICS)</procedure> <procedure>(stat-package-warnings-ref STATISTICS)</procedure> <procedure>(stat-packages-passed-ref STATISTICS)</procedure> <procedure>(stat-packages-failed-ref STATISTICS)</procedure> <procedure>(stat-packages-timing-ref STATISTICS)</procedure> <procedure>(stat-packages-terminated-ref STATISTICS)</procedure> <procedure>(stat-cases-ref STATISTICS)</procedure> <procedure>(stat-case-warnings-ref STATISTICS)</procedure> <procedure>(stat-cases-passed-ref STATISTICS)</procedure> <procedure>(stat-cases-failed-ref STATISTICS)</procedure> <procedure>(stat-cases-timing-ref STATISTICS)</procedure> <procedure>(stat-cases-terminated-ref STATISTICS)</procedure> <procedure>(stat-all-expectations-ref STATISTICS)</procedure> <procedure>(stat-all-expectation-warnings-ref STATISTICS)</procedure> <procedure>(stat-all-expectations-passed-ref STATISTICS)</procedure> <procedure>(stat-all-expectations-failed-ref STATISTICS)</procedure> <procedure>(stat-all-expectations-timing-ref STATISTICS)</procedure> <procedure>(stat-single-expectations-ref STATISTICS)</procedure> <procedure>(stat-single-expectation-warnings-ref STATISTICS)</procedure> <procedure>(stat-single-expectations-passed-ref STATISTICS)</procedure> <procedure>(stat-single-expectations-failed-ref STATISTICS)</procedure> <procedure>(stat-single-expectations-timing-ref STATISTICS)</procedure> <procedure>(stat-tol-expectations-ref STATISTICS)</procedure> <procedure>(stat-tol-expectation-warnings-ref STATISTICS)</procedure> <procedure>(stat-tol-expectations-passed-ref STATISTICS)</procedure> <procedure>(stat-tol-expectations-failed-ref STATISTICS)</procedure> <procedure>(stat-tol-expectations-timing-ref STATISTICS)</procedure> <procedure>(stat-equiv-expectations-ref STATISTICS)</procedure> <procedure>(stat-equiv-expectation-warnings-ref STATISTICS)</procedure> <procedure>(stat-equiv-expectations-passed-ref STATISTICS)</procedure> <procedure>(stat-equiv-expectations-failed-ref STATISTICS)</procedure> <procedure>(stat-equiv-expectations-timing-ref STATISTICS)</procedure> <procedure>(stat-todos-ref STATISTICS)</procedure> <procedure>(stat-todo-warnings-ref STATISTICS)</procedure> <procedure>(stat-skips-ref STATISTICS)</procedure> <procedure>(stat-skip-warnings-ref STATISTICS)</procedure> <procedure>(stat-glosses-ref STATISTICS)</procedure> <procedure>(stat-gloss-warnings-ref STATISTICS)</procedure> <procedure>(stat-terminations-ref STATISTICS)</procedure> ===== Output Generation API These procedures help in the printing of test result reports. {{THUNK}} is a zero argument procedure to print a report. {{INDENT}} is the number of spaces to left indent. Use {{test:write-object}} when printing a data object. <procedure>(test:output-apply THUNK [PORT|STRING|#t])</procedure> <procedure>(test:write-object OBJECT)</procedure> <procedure>(test:display-objects [OBJECT ...])</procedure> <procedure>(test:display-objects-newline [OBJECT ...])</procedure> <procedure>(test:display-indent INDENT)</procedure> <procedure>(test:display-indented-objects INDENT [OBJECT ...])</procedure> <procedure>(test:display-indented-objects-newline INDENT [OBJECT ...])</procedure> ===== Output Style API These functions will display a rendering of the {{RESULT-TREE}} and return the toplevel package result. The default destination is the {{(current-output-port)}}. Otherwise the destination specifies how the output is targeted. A {{PORT}} destination will display to the port. A {{STRING}} destination will display to the specified file. Should the file exist the result is implementation dependent. A {{#t}} destination will return the output as a string. <procedure>(output-style-human RESULT-TREE [PORT|STRING|#t])</procedure> <procedure>(output-style-html RESULT-TREE [PORT|STRING|#t])</procedure> <procedure>(output-style-compact RESULT-TREE [PORT|STRING|#t])</procedure> <procedure>(output-style-minimal RESULT-TREE [PORT|STRING|#t])</procedure> ==== Example Usages of the Test Suite Infrastructure This section contains some simple examples of how to author test suites. Here is a simple example: <enscript highlight="scheme"> (let ((result ;; output-style-human function requires a single test package ;; to encapsulate everything. (test-package "Arithmetic Operators" pd pe (test-case "Testing '+'" d e (expect-equal "Adding two positive numbers" 2 (+ 1 1)) (expect-equal "Adding two negative numbers" -2 (+ -1 -1)) (expect-zero "Adding positive and negative" (+ -1 1))) (test-case "Testing '-'" d e (expect-zero "Subtracting two positive numbers" (- 1 1)) (expect-zero "Subtracting two negative numbers" (- -1 -1)) (expect-equal "Subtracting positive and negative" -2 (- -1 1)))))) (output-style-human result)) </enscript> The above example, when evaluated, will produce some human readable output and the a {{#t}} value as the result of the top level package. The {{result}} variable contains the tree of evaluated expectations, test cases, and the package arranged in a hierarchy extremely similar to the nesting of the above macros. If you desire to manipulate the result tree yourself, you may use the various APIs to manipulate the various results. Please see the implementation of {{(output-style-human)}} in the test-infrastructure source to for an example of this. The variables: {{pe}}, {{e}} are the escape functions you may use with the {{(terminate)}} procedure if you wish to abort the above code somewhere. The variables: {{pd}}, {{d}} allow use of a {{"destructor"}} object which allows you to run side effecting functions at the {{"finishing"}} point of the evaluation of the test case or test package. These functions are run no matter if the code succeeded correctly or not, so be careful to manage the destructor object carefully so you don't perform unwanted side effects. The names of the destructor objects you supply are lexically scoped in the bodies of the test case or test package. Now, here is some example output that {{(output-style-human)}} might generate with the above testing code: Test Package: Arithmetic Operators Test Case: Testing '+' Expectation: Adding two positive numbers Expect equal Expected: 2 Unevaluated: (+ 1 1) Evaluated: 2 Pass: Adding two positive numbers Expectation: Adding two negative numbers Expect equal Expected: -2 Unevaluated: (+ -1 -1) Evaluated: -2 Pass: Adding two negative numbers Expectation: Adding positive and negative Expect zero Unevaluated: (+ -1 1) Evaluated: 0 Pass: Adding positive and negative Pass: Testing '+' Test Case: Testing '-' Expectation: Subtracting two positive numbers Expect zero Unevaluated: (- 1 1) Evaluated: 0 Pass: Subtracting two positive numbers Expectation: Subtracting two negative numbers Expect zero Unevaluated: (- -1 -1) Evaluated: 0 Pass: Subtracting two negative numbers Expectation: Subtracting positive and negative Expect equal Expected: -2 Unevaluated: (- -1 1) Evaluated: -2 Pass: Subtracting positive and negative Pass: Testing '-' Pass: Arithmetic Operators #t === Contributions {{output-text-compact}} by [[Patrick Brannan]]. === Changelog * 1.92 'expect-*' timing, see 'test-timing?' macro [Kon Lovett] * 1.91 Helper macros, some testeez-like forms [Kon Lovett] * 1.9 Exports [Kon Lovett] * 1.8 Added test-named-structure [Kon Lovett] * 1.7 Added expect-equiv, expect-ec, test-group, test-apply [Kon Lovett] * 1.6 MESSAGE argument for expectations optional [Kon Lovett] * 1.5 Rename of expect-fail, fix of condition-property bug, added test-it [Kon Lovett] * 1.4 Addition of expect-fail, expect-success [Kon Lovett] * 1.3 Slimming of output, addition of expect, test-continue? [Kon Lovett] * 1.2 Wrapping of expectations in an exception catcher [Kon Lovett] * 1.1 Addition of exception, multi-valued, not-false expectations [Kon Lovett] * 1.0 Initial release === License Copyright (c) 2000-2005, Peter Keller - All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. Neither the name of the author nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Description of your changes:
I would like to authenticate
Authentication
Username:
Password:
Spam control
What do you get when you add 3 to 20?