Support classes for automated testing.
The unittest framework is synchronous, so the test must be complete by the time the test method returns. This class provides the stop() and wait() methods for this purpose. The test method itself must call self.wait(), and asynchronous callbacks should call self.stop() to signal completion. Alternately, the gen_test decorator can be used to use yield points from the tornado.gen module.
By default, a new IOLoop is constructed for each test and is available as self.io_loop. This IOLoop should be used in the construction of HTTP clients/servers, etc. If the code being tested requires a global IOLoop, subclasses should override get_new_ioloop to return it.
The IOLoop‘s start and stop methods should not be called directly. Instead, use self.stop and self.wait. Arguments passed to self.stop are returned from self.wait. It is possible to have multiple wait/stop cycles in the same test.
# This test uses argument passing between self.stop and self.wait. class MyTestCase(AsyncTestCase): def test_http_fetch(self): client = AsyncHTTPClient(self.io_loop) client.fetch("http://www.tornadoweb.org/", self.stop) response = self.wait() # Test contents of response self.assertIn("FriendFeed", response.body) # This test uses an explicit callback-based style. class MyTestCase2(AsyncTestCase): def test_http_fetch(self): client = AsyncHTTPClient(self.io_loop) client.fetch("http://www.tornadoweb.org/", self.handle_fetch) self.wait() def handle_fetch(self, response): # Test contents of response (failures and exceptions here # will cause self.wait() to throw an exception and end the # test). # Exceptions thrown here are magically propagated to # self.wait() in test_http_fetch() via stack_context. self.assertIn("FriendFeed", response.body) self.stop()
A test case that starts up an HTTP server.
Subclasses must override get_app(), which returns the tornado.web.Application (or other HTTPServer callback) to be tested. Tests will typically use the provided self.http_client to fetch URLs from this server.
class MyHTTPTest(AsyncHTTPTestCase): def get_app(self): return Application([('/', MyHandler)...]) def test_homepage(self): # The following two lines are equivalent to # response = self.fetch('/') # but are shown in full here to demonstrate explicit use # of self.stop and self.wait. self.http_client.fetch(self.get_url('/'), self.stop) response = self.wait() # test contents of response
Convenience method to synchronously fetch a url.
The given path will be appended to the local server’s host and port. Any additional kwargs will be passed directly to AsyncHTTPClient.fetch (and so could be used to pass method="POST", body="...", etc).
Returns the port used by the server.
A new port is chosen for each test.
May be overridden by subclasses to return additional keyword arguments for the server.
Returns an absolute url for the given path on the test server.
A test case that starts an HTTPS server.
Interface is generally the same as AsyncHTTPTestCase.
May be overridden by subclasses to select SSL options.
By default includes a self-signed testing certificate.
Testing equivalent of @gen.coroutine, to be applied to test methods.
class MyTest(AsyncHTTPTestCase): @gen_test def test_something(self): response = yield gen.Task(self.fetch('/'))
Context manager to capture and suppress expected log output.
Useful to make tests of error conditions less noisy, while still leaving unexpected log entries visible. Not thread safe.
with ExpectLog('tornado.application', "Uncaught exception"): error_response = self.fetch("/some_page")
Constructs an ExpectLog context manager.
A test case that captures and discards all logging output if the test passes.
Some libraries can produce a lot of logging output even when the test succeeds, so this class can be useful to minimize the noise. Simply use it as a base class for your test case. It is safe to combine with AsyncTestCase via multiple inheritance (class MyTestCase(AsyncHTTPTestCase, LogTrapTestCase):)
This class assumes that only one log handler is configured and that it is a StreamHandler. This is true for both logging.basicConfig and the “pretty logging” configured by tornado.options. It is not compatible with other log buffering mechanisms, such as those provided by some test runners.
Create an instance of the class that will use the named test method when executed. Raises a ValueError if the instance does not have a method with the specified name.
A simple test runner.
This test runner is essentially equivalent to unittest.main from the standard library, but adds support for tornado-style option parsing and log formatting.
The easiest way to run a test is via the command line:
python -m tornado.testing tornado.test.stack_context_test
See the standard library unittest module for ways in which tests can be specified.
Projects with many tests may wish to define a test script like tornado/test/runtests.py. This script should define a method all() which returns a test suite and then call tornado.testing.main(). Note that even when a test script is used, the all() test suite may be overridden by naming a single test on the command line:
# Runs all tests python -m tornado.test.runtests # Runs one test python -m tornado.test.runtests tornado.test.stack_context_test
Additional keyword arguments passed through to unittest.main(). For example, use tornado.testing.main(verbosity=2) to show many test details as they are run. See http://docs.python.org/library/unittest.html#unittest.main for full argument list.
Binds a server socket to an available port on localhost.
Returns a tuple (socket, port).
Returns a (hopefully) unused port number.
This function does not guarantee that the port it returns is available, only that a series of get_unused_port calls in a single process return distinct ports.
Deprecated. Use bind_unused_port instead, which is guaranteed to find an unused port.