/usr/lib/python3/dist-packages/cram-0.6.egg-info

Metadata-Version: 1.1
Name: cram
Version: 0.6
Summary: A simple testing framework for command line applications
Home-page: https://bitheap.org/cram/
Author: Brodie Rao
Author-email: brodie@bitheap.org
License: GNU GPL
Download-URL: https://bitheap.org/cram/cram-0.6.tar.gz
Description: ======================
Cram: It's test time
======================

Cram is a functional testing framework for command line applications
based on Mercurial_'s `unified test format`_.

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`"
$ if [ -n "$COVERAGE" ]; then
> coverage erase
> alias cram="`which coverage` run --branch -a $TESTDIR/../cram.py"
> else
> alias cram="$PYTHON $TESTDIR/../cram.py"
> 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
-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
--indent=NUM number of spaces to use for indentation

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.

.. _Mercurial: http://mercurial.selenic.com/
.. _unified test format: http://www.selenic.com/blog/?p=663
.. _Cram's own test suite: https://bitbucket.org/brodie/cram/src/tip/tests/cram.t
.. _Perl-compatible regular expressions: https://en.wikipedia.org/wiki/Perl_Compatible_Regular_Expressions

Download
--------

* cram-0.6.tar.gz_ (24 KB, requires Python 2.4-2.7 or Python 3.1-3.2)

.. _cram-0.6.tar.gz: https://bitheap.org/cram/cram-0.6.tar.gz

Installation
------------

You can use pip_ to install Cram::

$ pip install cram

Or you can install Cram using GNU make::

$ wget https://bitheap.org/cram/cram-0.6.tar.gz
$ tar zxvf cram-0.6.tar.gz
$ cd cram-0.6
$ make install

.. _pip: https://pypi.python.org/pypi/pip

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.!
--- /home/brodie/src/cram/examples/fail.t
+++ /home/brodie/src/cram/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``.

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.

.. _unified context diff: https://en.wikipedia.org/wiki/Diff#Unified_format
.. _its own example tests: https://bitbucket.org/brodie/cram/src/tip/examples/

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`_.

* Added Arch Linux package metadata (in ``contrib/``). Contributed by
`Andrey Vlasovskikh`_.

* Fixed shell commands unintentionally inheriting Python's ``SIGPIPE``
handler (causing commands that close pipes to print ``broken pipe``
messages).

* Fixed ``EPIPE`` under PyPy when applying patches in
``--interactive`` mode.

* Added ``TESTFILE`` test environment variable (set to the name of the
current test).

* Fixed GNU patch 2.7 compatibility by using relative paths instead of
absolute paths. Contributed by `Douglas Creager`_.

* 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.

.. _Kamil Kisiel: http://kamilkisiel.net/
.. _Andrey Vlasovskikh: https://twitter.com/vlasovskikh
.. _Douglas Creager: http://dcreager.net/

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 ``%``.

* Matching output containing unprintable characters now requires the
``(esc)`` keyword. Real output containing unprintable characters
will automatically receive ``(esc)``.

* If an expected line matches its real output line exactly, special
matching like ``(re)`` or ``(glob)`` will be ignored.

* Regular expressions ending in a trailing backslash are now
considered invalid.

* Added an ``--indent`` option for changing the default amount of
indentation required to specify commands and output.

* Added support for specifying command line options in the ``CRAM``
environment variable.

* The ``--quiet`` and ``--verbose`` options can now be used together.

* When running Cram under Python 3, Unicode-specific line break
characters will no longer be parsed as newlines.

* Tests are no longer required to end in a trailing newline.

Version 0.4 (Sep. 28, 2010)
```````````````````````````
* **The test format has changed:** Output lines containing regular
expressions must now end in ``(re)`` or they'll be matched
literally. Lines ending with keywords are matched literally first,
however.

* Regular expressions are now matched from beginning to end. In other
words ``\d (re)`` is matched as ``^\d$``.

* In addition to ``(re)``, ``(glob)`` has been added. It supports
``*``, ``?``, and escaping both characters (and backslashes) using
``\``.

* **Environment settings have changed:** The ``-D`` flag has been
removed, ``$TESTDIR`` is now set to the directory containing the
``.t`` file, and ``$CRAMTMP`` is set to the test runner's temporary
directory.

* ``-i``/``--interactive`` now requires ``patch(1)``. Instead of
``.err`` files replacing ``.t`` files during merges, diffs are
applied using ``patch(1)``. This prevents matching regular
expressions and globs from getting clobbered.

* Previous ``.err`` files are now removed when tests pass.

* Cram now exits with return code ``1`` if any tests failed.

* If a test exits with return code ``80``, it's considered a skipped a
test. This is useful for intentionally disabling tests when they
only work on certain platforms or in certain settings.

* The number of tests, the number of skipped tests, and the number of
failed tests are now printed after all tests are finished.

* Added ``-q``/``--quiet`` to suppress diff output.

* Added `contrib/cram.vim`_ syntax file for Vim. Contributed by `Steve
Losh`_.

.. _contrib/cram.vim: https://bitbucket.org/brodie/cram/src/tip/contrib/cram.vim
.. _Steve Losh: http://stevelosh.com/

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.

Version 0.1 (Sep. 19, 2010)
```````````````````````````
* Initial release.

Development
-----------

Download the official development repository using Mercurial_::

hg clone https://bitbucket.org/brodie/cram

Test Cram using Cram::

make tests

Get a test coverage report using coverage.py_::

make coverage

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

.. _Mercurial: http://mercurial.selenic.com/
.. _coverage.py: http://nedbatchelder.com/code/coverage/
.. _Bitbucket: https://bitbucket.org/brodie/cram

Keywords: automatic functional test framework
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License (GPL)
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Unix Shell
Classifier: Topic :: Software Development :: Testing

python3-cram 0.6-1 / usr / lib / python3 / dist-packages / cram-0.6.egg-info