Lines ending with a space and the keyword (glob) are matched
with a glob-like syntax. The only special characters supported are
* and ?. Both characters can be escaped using \, and the
backslash can be escaped itself.

Output lines ending with either of the above keywords are always
first matched literally with actual command output.

Lines ending with a space and the keyword (no-eol) will match
actual output that doesn't end in a newline.

Actual output lines containing unprintable characters are escaped
and suffixed with a space and the keyword (esc). Lines matching
unprintable output must also contain the keyword.

Installation

Usage

Cram will print a dot for each passing test. If a test fails, a
unified context diff is printed showing the test's expected output
and the actual output. Skipped tests (empty tests and tests that exit
with return code 80) are marked with s instead of a dot.

Cram will also write the test with its actual output to
examples/fail.t.err.

When you're first writing a test, you might just write the commands
and run the test to see what happens. If you run Cram with -i or
--interactive, you'll be prompted to merge the actual output back
into the test. This makes it easy to quickly prototype new tests.

You can specify a default set of options by creating a .cramrc
file. For example:

[cram]
verbose = True
indent = 4

Is the same as invoking Cram with --verbose and --indent=4.

To change what configuration file Cram loads, you can set the
CRAMRC environment variable. You can also specify command line
options in the CRAM environment variable.

Note that the following environment variables are reset before tests
are run:

TMPDIR, TEMP, and TMP are set to the test runner's
tmp directory.

LANG, LC_ALL, and LANGUAGE are set to C.

TZ is set to GMT.

COLUMNS is set to 80.

CDPATH and GREP_OPTIONS are set to an empty string.

Cram also provides the following environment variables to tests:

CRAMTMP, set to the test runner's temporary directory.

TESTDIR, set to the directory containing the test file.

Also note that care should be taken with commands that close the test shell's
stdin. For example, if you're trying to invoke ssh in a test, try
adding the -n option to prevent it from closing stdin.

News

Version 0.6 (Aug. 1, 2013)

Added the long option --preserve-env for -E.

Added support for specifying options in .cramrc (configurable
with the CRAMRC environment variable).

Added a --shell option to change the shell tests are run
with. Contributed by Kamil Kisiel.

Fixed name clashes in temporary test directories (e.g., when running
two tests with the same name in different folders).

Backwards compatibility: Fixed improper usage of the subprocess
library under Python 3. This fixes Python 3.3 support, but breaks
support for Python 3.1-3.2.3 due to a bug in Python. If you're using
Python 3.0-3.2, you must upgrade to Python 3.2.4 or newer.

Version 0.5 (Jan. 8, 2011)

The test format has changed: Matching output not ending in a
newline now requires the (no-eol) keyword instead of ending the
line in %.

Version 0.3 (Sep. 20, 2010)

Implemented resetting of common environment variables. This behavior
can be disabled using the -E flag.

Changed the test runner to first make its own overall random
temporary directory, make tmp inside of it and set TMPDIR,
etc. to its path, and run each test with a random temporary working
directory inside of that.

Added --keep-tmpdir. Temporary directories are named by test
filename (along with a random string).

Added -i/--interactive to merge actual output back to into
tests interactively.

Added ability to match command output not ending in a newline by
suffixing output in the test with %.

Version 0.2 (Sep. 19, 2010)

Changed the test runner to run tests with a random temporary working
directory.