summaryrefslogtreecommitdiffstats
path: root/third_party/python/cram/cram-0.7.dist-info/DESCRIPTION.rst
diff options
context:
space:
mode:
Diffstat (limited to 'third_party/python/cram/cram-0.7.dist-info/DESCRIPTION.rst')
-rw-r--r--third_party/python/cram/cram-0.7.dist-info/DESCRIPTION.rst227
1 files changed, 227 insertions, 0 deletions
diff --git a/third_party/python/cram/cram-0.7.dist-info/DESCRIPTION.rst b/third_party/python/cram/cram-0.7.dist-info/DESCRIPTION.rst
new file mode 100644
index 0000000000..0a6577392c
--- /dev/null
+++ b/third_party/python/cram/cram-0.7.dist-info/DESCRIPTION.rst
@@ -0,0 +1,227 @@
+======================
+ Cram: It's test time
+======================
+
+Cram is a functional testing framework for command line applications.
+Cram tests look like snippets of interactive shell sessions. Cram runs
+each command and compares the command output in the test with the
+command's actual output.
+
+Here's a snippet from `Cram's own test suite`_::
+
+ The $PYTHON environment variable should be set when running this test
+ from Python.
+
+ $ [ -n "$PYTHON" ] || PYTHON="`which python`"
+ $ [ -n "$PYTHONPATH" ] || PYTHONPATH="$TESTDIR/.." && export PYTHONPATH
+ $ if [ -n "$COVERAGE" ]; then
+ > coverage erase
+ > alias cram="`which coverage` run --branch -a $TESTDIR/../scripts/cram"
+ > else
+ > alias cram="$PYTHON $TESTDIR/../scripts/cram"
+ > fi
+ $ command -v md5 > /dev/null || alias md5=md5sum
+
+ Usage:
+
+ $ cram -h
+ [Uu]sage: cram \[OPTIONS\] TESTS\.\.\. (re)
+
+ [Oo]ptions: (re)
+ -h, --help show this help message and exit
+ -V, --version show version information and exit
+ -q, --quiet don't print diffs
+ -v, --verbose show filenames and test status
+ -i, --interactive interactively merge changed test output
+ -d, --debug write script output directly to the terminal
+ -y, --yes answer yes to all questions
+ -n, --no answer no to all questions
+ -E, --preserve-env don't reset common environment variables
+ --keep-tmpdir keep temporary directories
+ --shell=PATH shell to use for running tests (default: /bin/sh)
+ --shell-opts=OPTS arguments to invoke shell with
+ --indent=NUM number of spaces to use for indentation (default: 2)
+ --xunit-file=PATH path to write xUnit XML output
+
+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.
+
+* Output lines ending with a space and the keyword ``(re)`` are
+ matched as `Perl-compatible regular expressions`_.
+
+* 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.
+
+* Anything else is a comment.
+
+.. _Cram's own test suite: https://bitbucket.org/brodie/cram/src/default/tests/cram.t
+.. _Perl-compatible regular expressions: https://en.wikipedia.org/wiki/Perl_Compatible_Regular_Expressions
+
+
+Download
+--------
+
+* `cram-0.7.tar.gz`_ (32 KB, requires Python 2.4-2.7 or Python 3.1 or newer)
+
+.. _cram-0.7.tar.gz: https://bitheap.org/cram/cram-0.7.tar.gz
+
+
+Installation
+------------
+
+Install Cram using make::
+
+ $ wget https://bitheap.org/cram/cram-0.7.tar.gz
+ $ tar zxvf cram-0.7.tar.gz
+ $ cd cram-0.7
+ $ make install
+
+
+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.
+
+For example, if we run Cram on `its own example tests`_::
+
+ .s.!
+ --- examples/fail.t
+ +++ examples/fail.t.err
+ @@ -3,21 +3,22 @@
+ $ echo 1
+ 1
+ $ echo 1
+ - 2
+ + 1
+ $ echo 1
+ 1
+
+ Invalid regex:
+
+ $ echo 1
+ - +++ (re)
+ + 1
+
+ Offset regular expression:
+
+ $ printf 'foo\nbar\nbaz\n\n1\nA\n@\n'
+ foo
+ + bar
+ baz
+
+ \d (re)
+ [A-Z] (re)
+ - #
+ + @
+ s.
+ # Ran 6 tests, 2 skipped, 1 failed.
+
+Cram will also write the test with its actual output to
+``examples/fail.t.err``, allowing you to use other diff tools. This
+file is automatically removed the next time the test passes.
+
+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``. (Note: When using ``--shell=zsh``,
+ this cannot be reset. It will reflect the actual terminal's width.)
+
+* ``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.
+
+* ``TESTFILE``, set to the basename of the current test file.
+
+* ``TESTSHELL``, set to the value specified by ``--shell``.
+
+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``. Similarly, if you invoke a daemon process that inherits
+``stdout`` and fails to close it, it may cause Cram to hang while
+waiting for the test shell's ``stdout`` to be fully closed.
+
+.. _unified context diff: https://en.wikipedia.org/wiki/Diff#Unified_format
+.. _its own example tests: https://bitbucket.org/brodie/cram/src/default/examples/
+
+
+Development
+-----------
+
+Download the official development repository using Mercurial_::
+
+ hg clone https://bitbucket.org/brodie/cram
+
+Or Git_::
+
+ git clone https://github.com/brodie/cram.git
+
+Test Cram using Cram::
+
+ pip install -r requirements.txt
+ make test
+
+Visit Bitbucket_ or GitHub_ if you'd like to fork the project, watch
+for new changes, or report issues.
+
+.. _Mercurial: http://mercurial.selenic.com/
+.. _Git: http://git-scm.com/
+.. _coverage.py: http://nedbatchelder.com/code/coverage/
+.. _Bitbucket: https://bitbucket.org/brodie/cram
+.. _GitHub: https://github.com/brodie/cram
+
+