https://github.com/sourcefrog/shellliketests

Test command-line programs from Python by giving example input and output
https://github.com/sourcefrog/shellliketests

Last synced: 6 months ago
JSON representation

Test command-line programs from Python by giving example input and output

• Host: GitHub
• URL: https://github.com/sourcefrog/shellliketests
• Owner: sourcefrog
• Created: 2013-06-16T06:49:36.000Z (over 12 years ago)
• Default Branch: master
• Last Pushed: 2013-06-16T23:22:43.000Z (over 12 years ago)
• Last Synced: 2025-04-03T18:36:31.695Z (10 months ago)
• Size: 141 KB
• Stars: 4
• Watchers: 2
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

          
Shell-like tests

================

* Licence: GNU GPL v2+

* Home page: https://github.com/sourcefrog/shelliketests

* Maintainer: Martin Pool 

* Dependencies: Python 2.6..3.3 (nothing else)

`shellliketests` allows users to write tests in a syntax very close to a

shell session, using a restricted and limited set of commands that should

be enough to mimic most of the behaviours.  For example:

```python

    def test_echo(self):

        run_script(self, """

            $ echo hello world

            hello world

            """)

```

Features and benefits:

* Provides a concise way to run commands and check output.

* Commands can either be really run as subprocesses, or selectively

  intercepted and run in-process (eg by calling something like the `main`

  routine of a Python program).  Running in process may be substantially

  faster and can allow more precise control of the test environment.

* Abstracts cross-platform differences: for example `rm` can be used

  across Windows and Unix.

* Sections of output can be ignored if they don't matter (like in Doctests.)

Shell-like tests don't cover every kind of test you should write, but they

do make one class of tests easier.

A script is a set of commands, each command is composed of:

* one mandatory command line,

* one optional set of input lines to feed the command,

* one optional set of output expected lines,

* one optional set of error expected lines.

Input, output and error lines can be specified in any order.

Except for the expected output, all lines start with a special

string (based on their origin when used under a Unix shell):

* `$ ` for the command,

* `<` for input,

* nothing for output,

* `2>` for errors,

Comments can be added anywhere, they start with '#' and end with

the line.

The execution stops as soon as an expected output or an expected error is not

matched.

If output occurs and no output is expected, the execution stops and the

test fails.  If unexpected output occurs on the standard error, then

execution stops and the test fails.

If an error occurs and no expected error is specified, the execution stops.

An error is defined by a returned status different from zero, not by the

presence of text on the error stream.

The matching is done on a full string comparison basis unless `...` is used, in

which case expected output/errors can be less precise.

Examples

--------

(`bzr` here is just an example; there's nothing bzr-specific.)

The following will succeed only if `bzr add` outputs `adding file`:

    $ bzr add file

    adding file

If you want the command to succeed for any output, just use:

    $ bzr add file

    ...

    2>...

The following script will raise an error:

    $ bzr not-a-command

If you want it to succeed, add expected error output matching what the

program will produce for this argument:

    $ bzr not-a-command

    2> bzr: ERROR: unknown command "not-a-command"

You can use ellipsis (...) to replace any piece of text you don't want to be

matched exactly, like in Doctest:

    $ bzr branch not-a-branch

    2>bzr: ERROR: Not a branch...not-a-branch/".

This can be used to ignore entire lines too:

    $ cat

    Really do it? [y/n]: