cheroot.test.webtest module

Extensions to unittest for web frameworks.

Use the WebCase.getPage() method to request a page from your HTTP server.

Framework Integration

If you have control over your server process, you can handle errors in the server-side of the HTTP conversation a bit better. You must run both the client (your WebCase tests) and the server in the same process (but in separate threads, obviously). When an error occurs in the framework, call server_error. It will print the traceback to stdout, and keep any assertions you have from running (the assumption is that, if the server errors, the page output will not be of further significance to your tests).

class cheroot.test.webtest.NonDataProperty(fget)

Bases: object

Non-data property decorator.

exception cheroot.test.webtest.ServerError

Bases: Exception

Exception for signalling server error.

on = False
class cheroot.test.webtest.WebCase(methodName='runTest')


Helper web test suite base.

HOST = ''

alias of http.client.HTTPConnection

PORT = 8000
property _Conn

Return HTTPConnection or HTTPSConnection based on self.scheme.

assertBody(value, msg=None)

Fail if value != self.body.

assertHeader(key, value=None, msg=None)

Fail if (key, [value]) not in self.headers.

assertHeaderIn(key, values, msg=None)

Fail if header indicated by key doesn’t have one of the values.

assertHeaderItemValue(key, value, msg=None)

Fail if the header does not contain the specified value.

assertInBody(value, msg=None)

Fail if value not in self.body.

assertMatchesBody(pattern, msg=None, flags=0)

Fail if value (a regex pattern) is not in self.body.

assertNoHeader(key, msg=None)

Fail if key in self.headers.

assertNoHeaderItemValue(key, value, msg=None)

Fail if the header contains the specified value.

assertNotInBody(value, msg=None)

Fail if value in self.body.

assertStatus(status, msg=None)

Fail if self.status != status.

status may be integer code, exact string status, or iterable of allowed possibilities.

body = None
console_height = 30
encoding = 'utf-8'
getPage(url, headers=None, method='GET', body=None, protocol=None, raise_subcls=())

Open the url with debugging support.

Return status, headers, body.

url should be the identifier passed to the server, typically a server-absolute path and query string (sent between method and protocol), and should only be an absolute URI if proxy support is enabled in the server.

If the application under test generates absolute URIs, be sure to wrap them first with strip_netloc():

>>> class MyAppWebCase(WebCase):
...     def getPage(url, *args, **kwargs):
...         super(MyAppWebCase, self).getPage(
...             cheroot.test.webtest.strip_netloc(url),
...             *args, **kwargs
...         )

raise_subcls is passed through to openURL().


Return a connection to our HTTP server.

headers = None

Non-data property decorator.


Return an IP address for a client connection.

If the server is listening on ‘’ (INADDR_ANY) or ‘::’ (IN6ADDR_ANY), this will return the proper localhost.

property persistent

Presence of the persistent HTTP connection.

scheme = 'http'
set_persistent(on=True, auto_open=False)

Make our HTTP_CONN persistent (or not).

If the ‘on’ argument is True (the default), then self.HTTP_CONN will be set to an instance of HTTP(S)?Connection to persist across requests. As this class only allows for a single open connection, if self already has an open connection, it will be closed.

ssl_context = None
status = None
property status_code

Integer HTTP status code.


Check whether actual status matches expected.

time = None
url = None
cheroot.test.webtest._open_url_once(url, headers=None, method='GET', body=None, host='', port=8000, http_conn=<class 'http.client.HTTPConnection'>, protocol='HTTP/1.1', ssl_context=None)

Open the given HTTP resource and return status, headers, and body.

cheroot.test.webtest.cleanHeaders(headers, method, body, host, port)

Return request headers, with required headers added (if missing).


Get a key press.


Return an IP address for a client connection given the server host.

If the server is listening on ‘’ (INADDR_ANY) or ‘::’ (IN6ADDR_ANY), this will return the proper localhost.

cheroot.test.webtest.openURL(*args, **kwargs)

Open a URL, retrying when it fails.

Specify raise_subcls (class or tuple of classes) to exclude those socket.error subclasses from being suppressed and retried.


Server debug hook.

Return True if exception handled, False if ignored. You probably want to wrap this, so you can still handle an error using your framework when it’s ignored.


Return status, headers, body the way we like from a response.


Return absolute-URI path from URL.

Strip the scheme and host from the URL, returning the server-absolute portion.

Useful for wrapping an absolute-URI for which only the path is expected (such as in calls to WebCase.getPage()).

>>> strip_netloc('')
>>> strip_netloc('//')
>>> strip_netloc('/foo/bar?bing#baz')