#lang scribble/doc @; THIS FILE IS GENERATED @(require scribble/manual) @(require (for-label (planet neil/testeez:1:3))) @title[#:version "0.5"]{@bold{Testeez}: Lightweight Unit Test Mechanism for R5RS Scheme} @author{Neil Van Dyke} License: @seclink["Legal" #:underline? #f]{LGPL 3} @(hspace 1) Web: @link["http://www.neilvandyke.org/testeez/" #:underline? #f]{http://www.neilvandyke.org/testeez/} @defmodule[(planet neil/testeez:1:3)] @section{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. @subsection{Example} A series of Testeez tests is listed within the @tt{testeez} syntax. For example: @SCHEMEBLOCK[ (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 evaluated, output like the following (which looks prettier fontified in Emacs's @tt{*scheme*} buffer) is printed: @verbatim[";;; BEGIN \"Foo Station\" TESTS\n\n;; 1. Put two and two together\n(+ 2 2)\n;; ==> 4\n;; Passed.\n\n;; DEFINE: Bar function\n(define bar (lambda (x) (+ x 42)))\n\n;; 2. Bar scene\n(bar 69)\n;; ==> 111\n;; FAILED! Expected:\n;; 0\n\n;; 3. Full circle\n(* (bar -21) 2)\n;; ==> 42\n;; Passed.\n\n;; 4. Multiple\n(values (+ 2 2) (string #\\h #\\i) (char-upcase #\\p))\n;; ==> 4\n;; \"hi\"\n;; #\\P\n;; Passed.\n\n;;; END \"Foo Station\" TESTS: FAILED\n;;; (Total: 4 Passed: 3 Failed: 1)"] @subsection{Shorthand} The @tt{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: @SCHEMEBLOCK[ (testeez ((+ 1 2) 3) ((* 6 7) 42)) ] is equivalent to: @SCHEMEBLOCK[ (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. @subsection{Embedding} By following a simple convention, Testeez tests can be embedded in a Scheme source file with the code that is tested, while permitting the tests to 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 @tt{testeez} like so: @verbatim["(define-syntax %foo:testeez\n (syntax-rules ()\n ((_ X ...)\n ;; Note: Comment-out exactly one of the following two lines.\n ;; (error \"Tests disabled.\")\n (testeez X ...)\n )))"] Then, this wrapper @tt{%foo:testeez} can be used in a procedure that executes the test suite of the ``Foo'' library: @SCHEMEBLOCK[ (define (%foo:test) (%foo:testeez "Foo Station" ....)) ] @section{Interface} The interface consists of the @tt{testeez} syntax. @defform[#:id testeez (testeez title form ...)]{ The @tt{testeez} syntax contains a short string @schemevarfont{title} and one or more @schemevarfont{forms}, of the following syntaxes, which are evaluated in order. @itemize[ @item{@tt{(test/equal @schemevarfont{desc} @schemevarfont{expr} @schemevarfont{expected})} Execute a test case. @schemevarfont{desc} is a short title or description of the test case, @schemevarfont{expr} is a Scheme expression, and @schemevarfont{expected} is an expression for the expected value (or multiple values). The test case passes iff each value of @schemevarfont{expr} is @tt{equal?} to the corresponding value of @schemevarfont{expected}. } @item{@tt{(test/eq @schemevarfont{desc} @schemevarfont{expr} @schemevarfont{expected})} Like @tt{test/equal}, except the equivalence predicate is @tt{eq?} rather than @tt{equal?}. } @item{@tt{(test/eqv @schemevarfont{desc} @schemevarfont{expr} @schemevarfont{expected})} Like @tt{test/equal}, except the equivalence predicate is @tt{eqv?} rather than @tt{equal?}. } @item{@tt{(test-define @schemevarfont{desc} @schemevarfont{name} @schemevarfont{val})} Bind a variable. @schemevarfont{desc} is a short description string, @schemevarfont{name} is the identifier, and @schemevarfont{val} is the value expression. The binding is visible to the remainder of the enclosing @tt{testeez} syntax. } @item{@tt{(test-eval @schemevarfont{desc} @schemevarfont{expr})} Evaluate an expression. } @item{@tt{(@schemevarfont{expr} @schemevarfont{expected})} Shorthand for @tt{(test/equal "" @schemevarfont{expr} @schemevarfont{expected})}. This shorthand is intended for interactive and rapid-prototyping use, not for released code. } ] } @section{History} @itemize[ @item{Version 0.5 --- 2009-05-28 --- PLaneT @tt{(1 3)} Added support for void return values. } @item{Version 0.4 --- 2009-03-02 --- PLaneT @tt{(1 2)} License is now LGPL 3. Minor changes for PLT 4. Changed to new Scheme administration system. There is now a @tt{main.ss}. } @item{Version 0.3 --- 2005-05-30 --- PLaneT @tt{(1 1)} Shorthand syntax added. Minor formatting change to test log output. } @item{Version 0.2 --- 2005-03-07 --- PLaneT @tt{(1 0)} Multiple values are now supported. @tt{test/eq} and @tt{test/eqv} have been added. Minor formatting changes to test log output. } @item{Version 0.1 --- 2005-01-02 Initial release. } ] @section[#:tag "Legal"]{Legal} Copyright (c) 2005--2009 Neil 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 3 of the License (LGPL 3), 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/licenses/ for details. For other licenses and consulting, please contact the author.