ScriptTest¶
News¶
1.3¶
- Use CRC32 to protect against a race condition where if a run took less than 1 second updates files would not appear to be updated.
1.2¶
- Python 3 support (thanks Marc Abramowitz!)
1.1.1¶
- Python 3 fixes
1.1¶
- Python 3 compatibility, from Hugo Tavares
- More Windows fixes, from Hugo Tavares
1.0.4¶
- Windows fixes (thanks Dave Abrahams); including an option for more careful string splitting (useful when testing a script with a space in the path), and more careful handling of environmental variables.
1.0.3¶
- Added a
capture_temp
argument toscripttest.TestFileEnvironment
andenv.assert_no_temp()
to test that no temporary files are left over.
1.0.2¶
- Fixed regression with
FoundDir.invalid
1.0.1¶
- Windows fix for cleaning up scratch files more reliably
- Allow spaces in the
script
name, e.g.,C:/program files/some-script
(but you must use multiple arguments toenv.run(script, more_args)
). - Remove the resolution of scripts to an absolute path (just allow the OS to do this).
- Don’t fail if there is an invalid symlink
1.0¶
env.run()
now takes a keyword argumentquiet
. If quiet is false, then if there is any error (return code != 0, or stderr output) the complete output of the script will be printed.- ScriptTest puts a marker file in scratch directories it deletes, so that if you point it at a directory not created by ScriptTest it will raise an error. Without this, unwitting developers could point ScriptTest at the project directory, which would cause the entire project directory to be wiped.
- ProcResults now no longer print the absolute path of the script (which is often system dependent, and so not good for doctests).
- Added
scripttest.ProcResults.wildcard_matches()
which returns file objects based on a wildcard expression.
0.9¶
Initial release
License¶
Copyright (c) 2007 Ian Bicking and Contributors
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
scripttest
– test command-line scripts¶
Module Contents¶
Objects that are returned¶
These objects are returned when you use env.run(...)
. The
ProcResult object is returned, and it has .files_updated
,
.files_created
, and .files_deleted
which are dictionaries of
FoundFile and FoundDir. The files in .files_deleted
represent
the pre-deletion state of the file; the other files represent the
state of the files after the command is run.
and.files_deleted
. These objects dictionary
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 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/
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
.