Imprimatur is a tool for performing automated functional testing on web applications. The tests are described in a simple test script. Along with the standard HTTP methods, Imprimatur handles authentication, file uploads and HTTPS. The responses are validated using regular expressions.
Imprimatur runs on Python 3.5+ on both CPython and PyPy.
Imprimatur is released under the GPL.
It’s a good idea to set up a virtualenv:
virtualenv venv source venv/bin/activate
then install Imprimatur with pip:
pip install imprimatur
To run an example test script save the following as a file called test.py:
[
{
'host': 'www.google.com',
'status_code': 200
}
]
then run it with:
imprimatur test.py
and it should come back saying all tests are passed. Here’s another script with some more examples:
[
{
'name': "Single regex",
'port': 5000,
'host': "localhost",
'path': "/text_2",
'status_code': 200,
'regexes': ['inexhaustible']
},
{
'name': "Basic auth",
'path': "/auth",
'auth': ("conrad", "kurtz"),
'status_code': 200
},
{
'name': "File upload",
'path': "/echo",
'method': "post",
'files': {"yellow": "tests/2/crome-file.txt"},
'regexes': ["yellow", "on the leads"],
'status_code': 200
},
{
'name': "Post name and value with regex.",
'path': "/echo",
'method': "post",
'data': {"quote": "Leisure is the mother of philosophy."},
'status_code': 200,
'regexes': ["Leisure"]
},
{
'name': "Repeat until successful.",
'path': "/counter",
# 'max' is maximum number of times to try
# 'period' is the number of seconds to wait between tries
'tries': {'max': 3, 'period': 1},
'status_code': 200,
'regexes': ["The Decline And Fall Of The Roman Empire"]
},
{
'name': "Regex on header.",
'path': "/redirect?location=http://localhost:5000/here.html",
'status_code': 302,
'regexes': ["here.html"]
},
{
'name': "HTTP HEAD request.",
'path': "/text_1",
'method': "head",
'status_code': 200
},
{
'name': "Allow redirects",
'path': "/text_1",
'allow_redirects': 'True',
'status_code': 200
}
]
The full list of properties for each request is given below. A * after the property name means that it is carried over to subsequent requests.
| Name | Notes |
|---|---|
scheme* |
Can be |
host* |
Default is |
port* |
Default is |
auth* |
Sequence of username and password eg. |
verify* |
For an HTTPS request, verify the certificate. Can be |
name |
Used to label the request. |
path |
End of the URL eg. |
method |
An HTTP method. eg. |
data |
Dictionary of post values eg. |
files |
File name and path to upload. Eg. |
tries |
Maximum number of times to try the URL. Eg. |
regexes |
Sequence of regular expressions
eg. |
status_code |
HTTP status code to
check for, eg. |
headers |
Dictionary of HTTP headers eg. |
unzip |
If |
allow_redirects |
If |
Cookies are always retained between requests.
Imprimatur comes with a very basic web interface. You can try it out using Imprimatur’s built-in web server by doing:
python -m imprimatur.web
Don’t run it on a public facing production web server, as it is entirely unsecure.
-
Drop support for Python 2.
-
The webserver now listens for external connections.
-
Upgrade dependent libraries.
-
Use TravisCI for testing.
-
Have all the docs in the readme.adoc file. This means that the Python Hosted site isn’t used any more, since the readme.adoc file is rendered on GitHub.
-
Fixed bug where one couldn’t send a binary file as part of an Imprimatur request.
-
In the absence of a character encoding in the response, rather than guess assume utf-8 and ignore any errors.
-
Fixed a bug where if a URL is malformed the test is skipped whereas it should fail.
-
Fixes a bug where if there’s no body to a response, and it has to be printed out, then fails.
-
Added the
verifyflag for controlling whether to verify SSL certificates or not. Can beTrueorFalse, the default isFalse.
-
Include 'templates' directory in the distribution, this is necessary for the web server.
-
A list of runs is now shown on the home page.
-
Give a good error message if there’s a syntax error in the script.
-
The wheel format distribution if Imprimatur now has the 'universal' flag set which denotes that it runs on Python 2 and 3.
-
Fixed bug where regex pattern wasn’t searching the headers.
-
Added the re.DOTALL flag so that a
.in regular expressions matches line ending characters. -
Added a rudimentary web interface.
-
Various improvements to the converter from old style XML test scripts to new style ones.
-
Renamed the ‘tries’ attribute ‘number’ to ‘max’ as it’s a better description of what it does.
-
Fixed bug where Imprimatur always retried max times, even when a request was successful.
-
The converter from old style XML test scripts to new style ones now carries over the comments as well.
-
Added a converter to convert from old style XML test scripts to new style Python ones.
-
The
status_codeattribute is now allowed to be either astror anint. Previously it could only be anint. -
The ‘Passed all tests!’ message at the end is now followed by a newline character.
-
The
authattribute is now carried over from previous requests so that it doesn’t have to be specified explicitly in each subsequent request.
-
Imprimatur now requires version 2.5.1 of the ‘requests’ library. It was found that old versions of 'requests' didn’t work.
-
Fixed a bug where the status code check isn’t working.
-
Added in a check for extraneous keys in the test script.
-
Included a lot more examples in the docs.
-
Added make sure dependencies (‘flask’ and ‘requests’) are automatically installed.
-
Added
imprimaturas a command-line script that is automatically installed.
-
Ported to Python.
-
Moved to GitHub.
-
Has the same features as before, but the script format is no longer an XML file, but evaluatable Python.
-
Can be used as a Python library.
-
Gets don’t follow redirects by default.
-
Fixed example given in tests directory.
-
If no arguments are given on the command line, throws an exception saying no file specified.
To run the regression tests, install tox:
pip install tox
then run tox from the imprimatur directory:
tox
The docs are written using Asciidoctor. To build them, install asciidoctor:
apt-get install asciidoctor
Then type:
asciidoctor readme.adoc
and the doc will appear at docs/index.html.