check-values

_check-values_
_check-values.plt_
_test_
_values_
_schemeunit_

Version 1.1
Richard Cobbe
January 2007
<cobbe at ccs dot neu dot edu>

This software is distributed under a BSD-style license (see license.txt).

This package provides two files, _check-values.ss_ and
_check-values-tests.ss_.  The former defines two macros, which make it
easier to write SchemeUnit test cases for functions and other forms that
return multiple values.

The second file defines a SchemeUnit test suite for the macros in
check-values.ss.  Note that most of these test cases are *SUPPOSED* to
fail; I'm interested primarily in ensuring that the message is formatted
correctly in case of failure.  These test cases may also be useful examples
of how to use the two macros.

======================================================================

Provided Forms:

> (check-values actual ((same? expected) ...) [msg])

This macro checks an expression that produces multiple values.  The first
argument, actual, is the expression to be tested.  Unlike the other checks
in SchemeUnit, this is a macro, and you should *NOT* wrap actual in a
thunk!  The sequence of (same? expected) lists specify the values that
actual should produce, along with the predicate to be used to compare the
two.

The check

    (check-values actual ((same_1 expected_1) ... (same_n expected_n)))

succeeds if actual produces values v_1 through v_n and if

    (check same_i v_i expected_i)

succeeds for all i between 1 and n.

As with other SchemeUnit checks, this form accepts an optional message
argument.

If the check fails, it fails with a message that contains the original
message, if any, and indicate the cause of the error: if actual produced
the wrong number of values, or which produced value failed to match the
corresponding expected value.

For example,

    (check-values (quotient/remainder 5 2) ([= 2] [= 1]))

should succeed, and

    (check-values (quotient/remainder 5 2) ([= 2]))

will fail with a message indicating that the test case expected 1 value but
got 2.

> (check-values* same? actual (expected ...) [msg])

This macro is an optimization of check-values for the case in which all
values are to be compared with the same equality predicate.

    (check-values* EQ EXPR (V1 ...))

expands (roughly) to

    (check-values EXPR ((EQ V1) ...))

You'd write the two examples above with check-values as follows:

    (check-values = (quotient/remainder 5 2) (2 1))
    (check-values = (quotient/remainder 5 2) (2))

======================================================================

TODO:

  1) Right now, I have to run the test cases by hand and look at the
     resulting messages to make sure they're formatted correctly.  Is it
     possible to write a meta-test-case that would automate this process?

  2) The backtrace in the GUI isn't very helpful; it shows only the call to
     test/graphical-ui.  (This might be because of .zo compilation.)


======================================================================

CHANGES:

  * since version 1.0:

    - documented test cases
    - added keywords, CHANGES, TODO, usage examples to doc.txt
    - fixed bug in calls to raise-syntax-error

======================================================================

ACKNOWLEDGMENTS:

Carl Eastlund suggested (and I think implemented the initial draft of) the
generalization from check-values* to check-values.