cherrypy.test package


cherrypy.test._test_decorators module

Test module for the @-decorator syntax, which is version-specific

class cherrypy.test._test_decorators.ExposeExamples

Bases: object

class cherrypy.test._test_decorators.ToolExamples

Bases: object


cherrypy.test._test_states_demo module

class cherrypy.test._test_states_demo.Root

cherrypy.test.benchmark module

CherryPy Benchmark Tool

Usage: [options]

–null: use a null Request object (to bench the HTTP server only) –notests: start the server but do not run the tests; this allows

you to check the tested pages with a browser

–help: show this help message –cpmodpy: run tests via apache on 54583 (with the builtin _cpmodpy) –modpython: run tests via apache on 54583 (with modpython_gateway) –ab=path: Use the ab script/executable at ‘path’ (see below) –apache=path: Use the apache script/exe at ‘path’ (see below)

To run the benchmarks, the Apache Benchmark tool “ab” must either be on your system path, or specified via the –ab=path option.

To run the modpython tests, the “apache” executable or script must be on your system path, or provided via the –apache=path option. On some platforms, “apache” may be called “apachectl” or “apache2ctl”–create a symlink to them if needed.

class cherrypy.test.benchmark.ABSession(path='/cpbench/users/rdelon/apps/blog/hello', requests=1000, concurrency=10)

A session of ‘ab’, the Apache HTTP server benchmarking tool.

Example output from ab:

This is ApacheBench, Version 2.0.40-dev <$Revision: $> apache-2.0 Copyright (c) 1996 Adam Twiss, Zeus Technology Ltd, Copyright (c) 1998-2002 The Apache Software Foundation,

Benchmarking (be patient) Completed 100 requests Completed 200 requests Completed 300 requests Completed 400 requests Completed 500 requests Completed 600 requests Completed 700 requests Completed 800 requests Completed 900 requests

Server Software: CherryPy/3.1beta Server Hostname: Server Port: 54583

Document Path: /static/index.html Document Length: 14 bytes

Concurrency Level: 10 Time taken for tests: 9.643867 seconds Complete requests: 1000 Failed requests: 0 Write errors: 0 Total transferred: 189000 bytes HTML transferred: 14000 bytes Requests per second: 103.69 [#/sec] (mean) Time per request: 96.439 [ms] (mean) Time per request: 9.644 [ms] (mean, across all concurrent requests) Transfer rate: 19.08 [Kbytes/sec] received

Connection Times (ms)
min mean[+/-sd] median max

Connect: 0 0 2.9 0 10 Processing: 20 94 7.3 90 130 Waiting: 0 43 28.1 40 100 Total: 20 95 7.3 100 130

Percentage of the requests served within a certain time (ms)
50% 100 66% 100 75% 100 80% 100 90% 100 95% 100 98% 100 99% 110

100% 130 (longest request)

Finished 1000 requests

parse_patterns = [('complete_requests', 'Completed', '^Complete requests:\\s*(\\d+)'), ('failed_requests', 'Failed', '^Failed requests:\\s*(\\d+)'), ('requests_per_second', 'req/sec', '^Requests per second:\\s*([0-9.]+)'), ('time_per_request_concurrent', 'msec/req', '^Time per request:\\s*([0-9.]+).*concurrent requests\\)$'), ('transfer_rate', 'KB/sec', '^Transfer rate:\\s*([0-9.]+)')]
class cherrypy.test.benchmark.Root
cherrypy.test.benchmark.size_report(sizes=(10, 100, 1000, 10000, 100000, 100000000), concurrency=50)
cherrypy.test.benchmark.thread_report(path='/cpbench/users/rdelon/apps/blog/hello', concurrency=(25, 50, 100, 200, 400))

cherrypy.test.checkerdemo module

Demonstration app for cherrypy.checker.

This application is intentionally broken and badly designed. To demonstrate the output of the CherryPy Checker, simply execute this module.

class cherrypy.test.checkerdemo.Root

cherrypy.test.helper module

cherrypy.test.logtest module

logtest, a unittest.TestCase helper for testing log output.

class cherrypy.test.logtest.LogCase

Bases: object

unittest.TestCase mixin for testing log messages.

logfile: a filename for the desired log. Yes, I know modes are evil,
but it makes the test functions so much cleaner to set this once.
lastmarker: the last marker in the log. This can be used to search for
messages since the last marker.
markerPrefix: a string with which to prefix log markers. This should be
unique enough from normal log output to use for marker identification.
assertInLog(line, marker=None)

Fail if the given (partial) line is not in the log.

The log will be searched from the given marker to the next marker. If marker is None, self.lastmarker is used. If the log hasn’t been marked (using self.markLog), the entire log will be searched.

assertLog(sliceargs, lines, marker=None)

Fail if log.readlines()[sliceargs] is not contained in ‘lines’.

The log will be searched from the given marker to the next marker. If marker is None, self.lastmarker is used. If the log hasn’t been marked (using self.markLog), the entire log will be searched.

assertNotInLog(line, marker=None)

Fail if the given (partial) line is in the log.

The log will be searched from the given marker to the next marker. If marker is None, self.lastmarker is used. If the log hasn’t been marked (using self.markLog), the entire log will be searched.


Overwrite self.logfile with 0 bytes.

lastmarker = None
logfile = None

Insert a marker line into the log and set self.lastmarker.

markerPrefix = 'test suite marker: '

cherrypy.test.modfastcgi module

cherrypy.test.modfcgid module

cherrypy.test.modpy module

cherrypy.test.modwsgi module

cherrypy.test.sessiondemo module

A session demonstration app.

class cherrypy.test.sessiondemo.Root

Bases: object


cherrypy.test.test_auth_basic module

cherrypy.test.test_auth_digest module

cherrypy.test.test_bus module

class cherrypy.test.test_bus.BusMethodTests(methodName='runTest')


get_listener(channel, index)
class cherrypy.test.test_bus.PublishSubscribeTests(methodName='runTest')


get_listener(channel, index)

cherrypy.test.test_caching module

cherrypy.test.test_compat module

cherrypy.test.test_config module

cherrypy.test.test_config_server module

cherrypy.test.test_conn module

cherrypy.test.test_core module

cherrypy.test.test_dynamicobjectmapping module

cherrypy.test.test_encoding module

cherrypy.test.test_etags module

cherrypy.test.test_http module

cherrypy.test.test_httpauth module

cherrypy.test.test_httplib module

Tests for cherrypy/lib/

class cherrypy.test.test_httplib.UtilityTests(methodName='runTest')



cherrypy.test.test_json module

cherrypy.test.test_logging module

cherrypy.test.test_mime module

cherrypy.test.test_misc_tools module

cherrypy.test.test_objectmapping module

cherrypy.test.test_proxy module

cherrypy.test.test_refleaks module

cherrypy.test.test_request_obj module

cherrypy.test.test_routes module

cherrypy.test.test_session module

cherrypy.test.test_sessionauthenticate module

cherrypy.test.test_states module

cherrypy.test.test_static module

cherrypy.test.test_tools module

cherrypy.test.test_tutorials module

cherrypy.test.test_virtualhost module

cherrypy.test.test_wsgi_ns module

cherrypy.test.test_wsgi_vhost module

cherrypy.test.test_wsgiapps module

cherrypy.test.test_xmlrpc module

cherrypy.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 cherrypy.test.webtest.ReloadingTestLoader

Bases: unittest.loader.TestLoader

loadTestsFromName(name, module=None)

Return a suite of all tests cases given a string specifier.

The name may resolve either to a module, a test case class, a test method within a test case class, or a callable object which returns a TestCase or TestSuite instance.

The method optionally resolves the names relative to a given module.

exception cherrypy.test.webtest.ServerError

Bases: exceptions.Exception

on = False
class cherrypy.test.webtest.TerseTestResult(stream, descriptions, verbosity)

Bases: unittest.runner.TextTestResult

class cherrypy.test.webtest.TerseTestRunner(stream=<open file '<stderr>', mode 'w'>, descriptions=True, verbosity=1, failfast=False, buffer=False, resultclass=None)

Bases: unittest.runner.TextTestRunner

A test runner class that displays results in textual form.


Run the given test case or test suite.

class cherrypy.test.webtest.WebCase(methodName='runTest')


HOST = ''

alias of HTTPConnection

PORT = 8000
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.

assertNotInBody(value, msg=None)

Fail if value in self.body.

assertStatus(status, msg=None)

Fail if self.status != status.

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

Open the url with debugging support. Return status, headers, body.


Return a connection to our HTTP server.

headers = None
interactive = True

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.

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 HTTPConnection (or HTTPS if self.scheme is “https”). This will then persist across requests.

We only allow for a single open connection, so if you call this and we currently have an open connection, it will be closed.

status = None
time = None
url = None
cherrypy.test.webtest.cleanHeaders(headers, method, body, host, port)

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


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.

cherrypy.test.webtest.openURL(url, headers=None, method='GET', body=None, host='', port=8000, http_conn=<class httplib.HTTPConnection>, protocol='HTTP/1.1')

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


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.

Module contents

Regression test suite for CherryPy.

Run ‘nosetests -s test/’ to exercise all tests.

The ‘-s’ flag instructs nose to output stdout messages, wihch is crucial to the ‘interactive’ mode of If you run these tests without the ‘-s’ flag, don’t be surprised if the test seems to hang: it’s waiting for your interactive input.