
SCARE's source distribution comes with a test suite, intended to help when
verifying a new build or port of the interpreter, and for regression tests
while making interpreter changes.  The test suite contains a mixture of real
Adrift games and contrived simple test examples, along with a 'script' for
each.

SCARE's self-test tool is 'sx'.  This is a specialized build of the SCARE
interpreter.  It reads script files, and compares SCARE's output with the
expected output, also held in the script.

To run a script against a game, give 'sx' the path to the script without any
'.scr' extension.  'sx' will open both the script and its associated game,
run the game against commands in the script, and report any differences from
the script's expectations.  For example, use

    sx test/sccore

to run the test/sccore.taf game using the test/sccore.scr script.  'sx' output
output is terse by default, just a count of tests run and tests passed.  Add
the -v option to have it print details of test errors, or -vv for very verbose
output (mostly useful for debugging game scripts).  You can run several tests
in one call by listing them on the command line; 'sx' will run them one after
another.

The script file format is simple.  Lines beginning '#' are comments, otherwise
the file is composed of sections.  The first section line is one that starts
with either '>' or '~'.  This is the next command, and the following lines, up
to the next '>' or '~' section start, are concatenated to form the expected
output for that command.  Expectations are glob patterns.

Commands starting with '>' are fed to the game; those starting with '~' are
taken to be SCARE debugger commands.  Before the game is running, debugger
commands are valid.  The first non-debugger command starts the game.  An empty
debugger command ("~") following any introductory debugger commands both
starts the game and sets an expectation for the game's introductory text.
After the game has completed or quit, only debugger commands are valid, and
all others are ignored.

For example, the following script verifies part of 'To Hell in a Hamper':

    # Use the debugger to confirm we have the right game release.
    ~ game
    *To Hell in a Hamper* Compiled "02 Aug 2003"* Version 4.00*

    # Ensure that the game's introductory text begins as expected.
    ~
    To Hell in a Hamper By J. J. Guest

    With thanks to my beta-testers, Amby, Liz and Woodfish and to my brother
    Dan for his many suggestions. *

    # Verify that an NPC's basic description works.
    > x hubert
    Hubert is a man of prodigious girth, pasty and unhealthy looking with
    slicked down hair and beady little eyes that follow you about. Hubert is
    wearing a large, bulky overcoat and a shapeless felt hat.

The test suite for SCARE is in the /test subdirectory.  It contains both
released Adrift games and contrived tests specifically designed to verify
parts of SCARE.  The accompanying scripts are built from transcripts captured
from the Adrift Runner.  This makes the test suite suitable for verifying that
SCARE matches the Runner, at least in the most important areas.

Note that some messages from the interpreter may be normal when running
certain tests.  For example, the scmaths test verifies that SCARE can handle
attempted division by zero.  This causes SCARE to print

    scare: expr_eval_action: attempt to divide by zero

For tests that are not from released games, the test suite also contains an
Adrift "module" export of the test, in a file with the extension ".amf".
This is for documentation only, and is not used by 'sx'.  Tests with ALRs also
have an accompanying ".alr" file, again for documentation only.

