chk: a minimal tester

This package defines a minimal testing library with a simple
implementation, sensible defaults, useful flexibilty, and beautiful
failure reporting. It is independent of all other Racket testing
libraries, but it does cooperate with raco test and raco
cover for displaying summary information.

A #:te test is a special case of a #:?pe test,
where chk ensures that e evaluates to
exactly one value and that the predicate p does not return
#f on it. This form is robust to errors in p, which
must evaluate to exactly one value that is a procedure of one
argument.

2Expected Value Tests

An #:=actualexpected test compares an actual evaluation
with an expected evaluation. If expected raises an
exception, then actual must also, with the same
exn-message. Otherwise, the two expression must return the
same number of values, which must be equal?.

An #:=actualexpected test is a special case of a
#:eqequalactualexpected test where equal is
equal?. equal must evaluate to exactly one value,
which is a procedure of two arguments. If equal does not
evaluate as expected, then the test is considered a failure.

3Expected Exception Tests

An #:xactualexn-pred test is form when you expect
actual to evaluate to an exception, but cannot (or do not
want to) predict the exact error message. exn-pred must
evaluate to exactly one value. If that value is a string, then it must
be appear in the message of the exception that actual
raises. If that value is a regular expression, then it must match the
message of exception that actual raises. If the value is not
a string or regular expression, it must be a procedure of one argument
that does not return #f on the exception that
actual raises.

A special key for use with with-chk that is not printed, but
instead must be matched with a value that is a procedure of one
argument. If there is an error, then the function will be called with
all of the failure details.

8Filtering Tests with Command-line Arguments

The key/value pairs specified in the current context by
with-chk can also be used to group tests into catagories
which can be selected and run by supplying command-line arguments to
the module running the tests. Before each test is run,
chk will use the value of
current-command-line-arguments to construct a list of names
and key/value pairs.

Key/value pairs are specified by arguments of the form key=value.
If a non-zero amount of key/value pairs are specified, then only tests
which match the set of key/value pairs specified on the command line
will be executed. The command-line argument "foo=bar", for
example, corresponds with the racket pair ('foo. "bar").

In the above example, the former test runs because it has been called
inside of an expression where the key 'foo matches the value
"bar", but the latter test is skipped.

Keys read from the command line are always treated as symbols and
compared using eq?. Values are treated as strings, and the
runtime values that they are compared against are cast to string with
~a before the comparison. Because of this, it is simple to
filter against values of any transparent data type, not just strings.

In the above example, the former test does not run because it is
defined in a context in which only the key 'foo has a value.
The latter test runs because its context contains the correct values
for both 'foo and 'number.

The keys 'file and 'line are special cases when
present in the command-line arguments. They are case insensitive and
are matched against the file name and line number of current test.
Files are treated as regular expressions. Multiple file names and
line numbers may be specified on the command line to allow more tests
through in a single test run.

Any command-line arguments which do not fit the name=value pattern
are treated as regular expressions and used as a set of names to run.
In the execution context of the test, these names are compared against
the value corresponding with the 'name key. Unlike with
key/value pairs, a test’s name needs only to match against one of the
names specified on the command line in order to be run. This way,
multiple tests can be specified to be run. Tests with no
'name key specified will only be run in the case that no
names are present in the command-line arguments.

In the above example, the command-line arguments are specifying that
only tests which match the name "name1"and the key/value pair
('foo. "bar") should be run. Neither test satisfies both conditions, so
neither test is run.

9Controlling Source Location and Syntax Display

Everywhere in the preceeding discussion where we referred to an
expression evaluating to something, that position may be replaced with
(#:stxstxe) or (#:srcsrce). In both cases,
the expression evaluated is e. However, if there is an
error, then a different syntax (stx, which is simply a
datum) or source location (src which is evaluate to
something that is a source-location?) is reported.