doc.txt

Testeez: Lightweight Unit Test Mechanism for R5RS Scheme

Testeez: Lightweight Unit Test Mechanism for R5RS Scheme
********************************************************

Version 0.3, 2005-05-30, `http://www.neilvandyke.org/testeez/'

by Neil W. Van Dyke <neil@neilvandyke.org>

     Copyright (C) 2005 Neil W. Van Dyke.  This program is Free
     Software; you can redistribute it and/or modify it under the terms
     of the GNU Lesser General Public License as published by the Free
     Software Foundation; either version 2.1 of the License, or (at
     your option) any later version.  This program is distributed in
     the hope that it will be useful, but without any warranty; without
     even the implied warranty of merchantability or fitness for a
     particular purpose.  See <http://www.gnu.org/copyleft/lesser.html>
     for details.  For other license options and consulting, contact
     the author.

Introduction
************

Testeez is a simple lightweight unit test mechanism for R5RS Scheme.  It
was written to support regression test suites embedded within the source
code files of the author's portable Scheme libraries.

   A series of Testeez tests is listed within the `testeez' syntax.  By
following a simple convention, these tests can be disabled and the
dependency on Testeez removed for production code.  For example, to use
Testeez in a "Foo" library, one can first add a syntax wrapper around
`testeez' like so:

     (define-syntax %foo:testeez
       (syntax-rules ()
         ((_ X ...)
          ;; Note: Comment-out exactly one of the following two lines.
          ;; (error "Tests disabled.")
          (testeez X ...)
          )))

   Then, this wrapper `%foo:testeez' can be used in a procedure that
executes the test suite of the "Foo" library:

     (define (%foo:test)
       (%foo:testeez
        "Foo Station"

        (test/equal "Put two and two together" (+ 2 2) 4)

        (test-define "Bar function" bar (lambda (x) (+ x 42)))

        (test/equal "Bar scene" (bar 69) 0)

        (test/eqv   "Full circle" (* (bar -21) 2) 42)

        (test/eqv   "Multiple"
                    (values (+ 2 2) (string #\h #\i) (char-upcase #\p))
                    (values 4 "hi" #\P))))

   When the tests are enabled and `(%foo:test)' is evaluated, output
like the following (which looks prettier fontified in Emacs's `*scheme*'
buffer) is printed:

     ;;; BEGIN "Foo Station" TESTS

     ;; 1. Put two and two together
     (+ 2 2)
     ;; ==> 4
     ;; Passed.

     ;; DEFINE: Bar function
     (define bar (lambda (x) (+ x 42)))

     ;; 2. Bar scene
     (bar 69)
     ;; ==> 111
     ;; FAILED!  Expected:
     ;;     0

     ;; 3. Full circle
     (* (bar -21) 2)
     ;; ==> 42
     ;; Passed.

     ;; 4. Multiple
     (values (+ 2 2) (string #\h #\i) (char-upcase #\p))
     ;; ==> 4
     ;;     "hi"
     ;;     #\P
     ;; Passed.

     ;;; END "Foo Station" TESTS: FAILED
     ;;;     (Total: 4  Passed: 3  Failed: 1)

   The `testeez' syntax also supports shorthand or abbreviated forms,
for quick interactive use, such as in an editor buffer while
rapid-prototyping a function, and in a REPL while debugging.  For an
example of shorthand, the Scheme expression:

     (testeez ((+ 1 2) 3) ((* 6 7) 42))

is equivalent to:

     (testeez ""
              (test/equal "" (+ 1 2) 3)
              (test/equal "" (* 6 7) 42))

   Future versions of Testeez will add additional features, such as
custom predicates and handling of errors.

Interface
*********

The interface consists of the `testeez' syntax.

> (testeez [ title ] form ...)
     The `testeez' syntax contains a short string TITLE and one or more
     FORMS, of the following syntaxes, which are evaluated in order.

    `(test/equal DESC EXPR EXPECTED)'
          Execute a test case.  DESC is a short title or description of
          the test case, EXPR is a Scheme expression, and EXPECTED is an
          expression for the expected value (or multiple values).  The
          test case passes iff each value of EXPR is `equal?' to the
          corresponding value of EXPECTED.

    `(test/eq DESC EXPR EXPECTED)'
          Like `test/equal', except the equivalence predicate is `eq?'
          rather than `equal?'.

    `(test/eqv DESC EXPR EXPECTED)'
          Like `test/equal', except the equivalence predicate is `eqv?'
          rather than `equal?'.

    `(test-define DESC NAME VAL)'
          Bind a variable.  DESC is a short description string, NAME is
          the identifier, and VAL is the value expression.  The binding
          is visible to the remainder of the enclosing `testeez' syntax.

    `(test-eval DESC EXPR)'
          Evaluate an expression.

    `(EXPR EXPECTED)'
          Shorthand for `(test/equal "" EXPR EXPECTED)'.  This
          shorthand is intended for interactive and rapid-prototyping
          use, not for released code.


History
*******

Version 0.3 -- 2005-05-30
     Shorthand syntax added.  Minor formatting change to test log
     output.

Version 0.2 -- 2005-03-07
     Multiple values are now supported.  `test/eq' and `test/eqv' have
     been added.  Minor formatting changes to test log output.

Version 0.1 -- 2005-01-02
     Initial release.