Cram 0.6

A simple testing framework for command-line applications

  Add it to your Download Basket!

 Add it to your Watch List!


Rate it!

What's new in Cram 0.6:

  • 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.
  • Added Arch Linux package metadata (in contrib/). Contributed by Andrey Vlasovskikh.
Read full changelog
send us
an update
GPL (GNU General Public License) 
Brodie Rao
ROOT \ Programming \ Quality Assurance and Testing
Cram is a functional testing framework for command-line applications, based on Mercurial's unified test format.

Here's a snippet from cram.t in Cram's own test suite:

The $PYTHON environment variable should be set when running this
test from Python.

 $ [ -n "$PYTHON" ] || PYTHON=python
 $ if [ -n "$COVERAGE" ]; then
 > coverage erase
 > alias cram='coverage run -a'
 > else
 > alias cram="$PYTHON"
 > fi
 $ command -v md5 || alias md5=md5sum


 $ cram -h
 [Uu]sage: cram \[OPTIONS\] TESTS\.\.\.

 -h, --help show this help message and exit
 -v, --verbose show filenames and test status
 -i, --interactive interactively merge changed test output
 -y, --yes answer yes to all questions
 -n, --no answer no to all questions
 -D DIR, --tmpdir=DIR run tests in DIR
 --keep-tmpdir keep temporary directories
 -E don't reset common environment variables
 $ cram
 [Uu]sage: cram \[OPTIONS\] TESTS\.\.\.

The format in a nutshell:

 * Cram tests use the .t file extension.
 * Lines beginning with two spaces, a dollar sign, and a space are run in the shell.
 * Lines beginning with two spaces, a greater than sign, and a space allow multi-line commands.
 * All other lines beginning with two spaces are considered command output.
 * Command output in the test is first matched literally with the actual output. If it doesn't match, it's then compiled and matched as a Perl-compatible regular expression.
 * Command output in the test that ends with a percent sign will match actual output that doesn't end in a newline.
 * Anything else is a comment.


You can use pip to install Cram:

 sudo pip install cram

Or you can install Cram the old fashioned way:

 tar zxvf cram-0.3.tar.gz
 cd cram-0.3.tar.gz
 sudo python install


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.

For example, if we run cram on its own example tests:

 cram examples
--- examples/fail.t
+++ examples/fail.t.out
@@ -3,11 +3,11 @@
 $ echo 1
 $ echo 1
- 2
+ 1
 $ echo 1

 Invalid regex:

 $ echo 1
- +++
+ 1

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.

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:

 * RUNDIR, set to the directory Cram was run from.
 * TESTDIR, set to the test runner's temporary directory.


Download the official development repository using Mercurial:

hg clone

Test Cram using Cram:

make tests

Get a test coverage report using

make coverage

Visit Bitbucket if you'd like to fork the project, watch for new changes, or report issues.

Last updated on January 9th, 2011


#testing framework #command-line applications #application testing #command-line #testing #framework #Mercurial

Add your review!