ScriptTest is an extraction of paste.fixture.TestFileEnvironment from the Paste project. It was originally written to test Paste Script.
It is licensed under an MIT-style permissive license.
Discussion should happen on the Paste mailing list, and bugs should go in the Paste bug tracker.
It is available in an hg repository. You can get a checkout with:
$ hg clone http://bitbucket.org/ianb/scripttest/
This library helps you test command-line scripts. It runs a script and watches the output, looks for non-zero exit codes, output on stderr, and any files created, deleted, or modified.
To start you instantiate TestFileEnvironment, which is the context in which all your scripts are run. You give it a base directory (typically a scratch directory), or if you don’t it will guess call_module_dir/test-output/. Example:
>>> from scripttest import TestFileEnvironment
>>> env = TestFileEnvironment('./test-output')
Note
Everything in ./test-output will be deleted every test run. To make sure you don’t point at an important directory, the scratch directory must be created by ScriptTest (a hidden file is written by ScriptTest to confirm that it created the directory). If the directory already exists, you must delete it manually.
Then you run scripts with env.run(script, arg1, arg2, ...):
>>> print(env.run('echo', 'hey'))
Script result: echo hey
-- stdout: --------------------
hey
There’s several keyword arguments you can use with env.run():
As you can see from the options, if the script indicates anything error-like it is, by default, turned into an exception. This of course includes a non-zero response code. Also any output on stderr also counts as an error (unless turned off with expect_stderr=True).
The object you get back from a run represents what happened during the script. It has a useful str() (as you can see in the previous example) that shows a summary and can be useful in a doctest. It also has several useful attributes:
Of course by default stderr must be empty, and returncode must be zero, since anything else would be considered an error.
Of particular interest are the dictionaries files_created, etc. These show just what files were handled by the script. Each dictionary points to another helper object for inspecting the files (.files_deleted contains the files as they existed before the script ran).
Each file or directory object has useful attributes:
You may use the in operator with the file objects (tested against the contents of the file), and the .mustcontain() method, where file.mustcontain('a', 'b') means assert 'a' in file; assert 'b' in file.