It is licensed under an MIT-style permissive license.
$ git clone https://github.com/pypa/scripttest.git
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
>>> from scripttest import TestFileEnvironment >>> env = TestFileEnvironment('./test-output')
./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
expect_error: (default False)
- Don’t raise an exception in case of errors
- Don’t raise an exception if anything is printed to stderr
- Input to the script
- The working directory to run in (default
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
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:
- What is produced on those streams
- The return code of the script.
- Dictionaries mapping filenames (relative to the
base_dir) to FoundFile or FoundDir objects.
Of course by default
stderr must be empty, and
be zero, since anything else would be considered an error.
Of particular interest are the dictionaries
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
Each file or directory object has useful attributes:
- The path of the file, relative to the
- The full path
- The results of
st_sizeof the stat. (Directories have no
- The contents of the file (does not apply to directories).
fileis true for files,
diris true for directories.
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'