ScriptTest¶
Status & License¶
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 happens on the Paste mailing list, and bugs should go in the Github issue list.
It is available on pypi or in a git repository. You can get a checkout with:
$ git clone https://github.com/pypa/scripttest.git
Purpose & Introduction¶
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()
:
expect_error
: (default False)- Don’t raise an exception in case of errors
expect_stderr
: (defaultexpect_error
)- Don’t raise an exception if anything is printed to stderr
stdin
: (default""
)- Input to the script
cwd
: (defaultself.cwd
)- The working directory to run in (default
base_dir
)
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:
stdout
,stderr
:- What is produced on those streams
returncode
:- The return code of the script.
files_created
,files_deleted
,files_updated
:- Dictionaries mapping filenames (relative to the
base_dir
) to FoundFile or FoundDir objects.
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:
path
:- The path of the file, relative to the
base_path
full
:- The full path
stat
:- The results of
os.stat
. Alsomtime
andsize
contain the.st_mtime
andst_size
of the stat. (Directories have nosize
) bytes
:- The contents of the file (does not apply to directories).
file
,dir
:file
is true for files,dir
is 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'
in file
.