tornado.testing
— Unit testing support for asynchronous code¶
Support classes for automated testing.
AsyncTestCase
andAsyncHTTPTestCase
: Subclasses of unittest.TestCase with additional support for testing asynchronous (IOLoop
-based) code.ExpectLog
: Make test logs less spammy.main()
: A simple test runner (wrapper around unittest.main()) with support for the tornado.autoreload module to rerun the tests when code changes.
Asynchronous test cases¶
-
class
tornado.testing.
AsyncTestCase
(methodName: str = 'runTest')[source]¶ TestCase
subclass for testingIOLoop
-based asynchronous code.The unittest framework is synchronous, so the test must be complete by the time the test method returns. This means that asynchronous code cannot be used in quite the same way as usual and must be adapted to fit. To write your tests with coroutines, decorate your test methods with
tornado.testing.gen_test
instead oftornado.gen.coroutine
.This class also provides the (deprecated)
stop()
andwait()
methods for a more manual style of testing. The test method itself must callself.wait()
, and asynchronous callbacks should callself.stop()
to signal completion.By default, a new
IOLoop
is constructed for each test and is available asself.io_loop
. If the code being tested requires a globalIOLoop
, subclasses should overrideget_new_ioloop
to return it.The
IOLoop
’sstart
andstop
methods should not be called directly. Instead, useself.stop
andself.wait
. Arguments passed toself.stop
are returned fromself.wait
. It is possible to have multiplewait
/stop
cycles in the same test.Example:
# This test uses coroutine style. class MyTestCase(AsyncTestCase): @tornado.testing.gen_test def test_http_fetch(self): client = AsyncHTTPClient() response = yield client.fetch("http://www.tornadoweb.org") # Test contents of response self.assertIn("FriendFeed", response.body) # This test uses argument passing between self.stop and self.wait. class MyTestCase2(AsyncTestCase): def test_http_fetch(self): client = AsyncHTTPClient() client.fetch("http://www.tornadoweb.org/", self.stop) response = self.wait() # Test contents of response self.assertIn("FriendFeed", response.body)
-
get_new_ioloop
() → tornado.ioloop.IOLoop[source]¶ Returns the
IOLoop
to use for this test.By default, a new
IOLoop
is created for each test. Subclasses may override this method to returnIOLoop.current()
if it is not appropriate to use a newIOLoop
in each tests (for example, if there are global singletons using the defaultIOLoop
) or if a per-test event loop is being provided by another system (such aspytest-asyncio
).
-
stop
(_arg: Any = None, **kwargs: Any) → None[source]¶ Stops the
IOLoop
, causing one pending (or future) call towait()
to return.Keyword arguments or a single positional argument passed to
stop()
are saved and will be returned bywait()
.
-
wait
(condition: Callable[[...], bool] = None, timeout: float = None) → None[source]¶ Runs the
IOLoop
until stop is called or timeout has passed.In the event of a timeout, an exception will be thrown. The default timeout is 5 seconds; it may be overridden with a
timeout
keyword argument or globally with theASYNC_TEST_TIMEOUT
environment variable.If
condition
is notNone
, theIOLoop
will be restarted afterstop()
untilcondition()
returnsTrue
.Changed in version 3.1: Added the
ASYNC_TEST_TIMEOUT
environment variable.
-
-
class
tornado.testing.
AsyncHTTPTestCase
(methodName: str = 'runTest')[source]¶ A test case that starts up an HTTP server.
Subclasses must override
get_app()
, which returns thetornado.web.Application
(or otherHTTPServer
callback) to be tested. Tests will typically use the providedself.http_client
to fetch URLs from this server.Example, assuming the “Hello, world” example from the user guide is in
hello.py
:import hello class TestHelloApp(AsyncHTTPTestCase): def get_app(self): return hello.make_app() def test_homepage(self): response = self.fetch('/') self.assertEqual(response.code, 200) self.assertEqual(response.body, 'Hello, world')
That call to
self.fetch()
is equivalent toself.http_client.fetch(self.get_url('/'), self.stop) response = self.wait()
which illustrates how AsyncTestCase can turn an asynchronous operation, like
http_client.fetch()
, into a synchronous operation. If you need to do other asynchronous operations in tests, you’ll probably need to usestop()
andwait()
yourself.-
get_app
() → tornado.web.Application[source]¶ Should be overridden by subclasses to return a
tornado.web.Application
or otherHTTPServer
callback.
-
fetch
(path: str, raise_error: bool = False, **kwargs: Any) → tornado.httpclient.HTTPResponse[source]¶ Convenience method to synchronously fetch a URL.
The given path will be appended to the local server’s host and port. Any additional keyword arguments will be passed directly to
AsyncHTTPClient.fetch
(and so could be used to passmethod="POST"
,body="..."
, etc).If the path begins with http:// or https://, it will be treated as a full URL and will be fetched as-is.
If
raise_error
isTrue
, atornado.httpclient.HTTPError
will be raised if the response code is not 200. This is the same behavior as theraise_error
argument toAsyncHTTPClient.fetch
, but the default isFalse
here (it’sTrue
inAsyncHTTPClient
) because tests often need to deal with non-200 response codes.Changed in version 5.0: Added support for absolute URLs.
Changed in version 5.1: Added the
raise_error
argument.Deprecated since version 5.1: This method currently turns any exception into an
HTTPResponse
with status code 599. In Tornado 6.0, errors other thantornado.httpclient.HTTPError
will be passed through, andraise_error=False
will only suppress errors that would be raised due to non-200 response codes.
-
get_httpserver_options
() → Dict[str, Any][source]¶ May be overridden by subclasses to return additional keyword arguments for the server.
-
-
class
tornado.testing.
AsyncHTTPSTestCase
(methodName: str = 'runTest')[source]¶ A test case that starts an HTTPS server.
Interface is generally the same as
AsyncHTTPTestCase
.
-
tornado.testing.
gen_test
(func: Callable[[...], Union[collections.abc.Generator, Coroutine]] = None, timeout: float = None) → Union[Callable[[...], None], Callable[[Callable[[...], Union[collections.abc.Generator, Coroutine]]], Callable[[...], None]]][source]¶ Testing equivalent of
@gen.coroutine
, to be applied to test methods.@gen.coroutine
cannot be used on tests because theIOLoop
is not already running.@gen_test
should be applied to test methods on subclasses ofAsyncTestCase
.Example:
class MyTest(AsyncHTTPTestCase): @gen_test def test_something(self): response = yield self.http_client.fetch(self.get_url('/'))
By default,
@gen_test
times out after 5 seconds. The timeout may be overridden globally with theASYNC_TEST_TIMEOUT
environment variable, or for each test with thetimeout
keyword argument:class MyTest(AsyncHTTPTestCase): @gen_test(timeout=10) def test_something_slow(self): response = yield self.http_client.fetch(self.get_url('/'))
Note that
@gen_test
is incompatible withAsyncTestCase.stop
,AsyncTestCase.wait
, andAsyncHTTPTestCase.fetch
. Useyield self.http_client.fetch(self.get_url())
as shown above instead.New in version 3.1: The
timeout
argument andASYNC_TEST_TIMEOUT
environment variable.Changed in version 4.0: The wrapper now passes along
*args, **kwargs
so it can be used on functions with arguments.
Controlling log output¶
-
class
tornado.testing.
ExpectLog
(logger: Union[logging.Logger, str], regex: str, required: bool = True)[source]¶ 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.
The attribute
logged_stack
is set toTrue
if any exception stack trace was logged.Usage:
with ExpectLog('tornado.application', "Uncaught exception"): error_response = self.fetch("/some_page")
Changed in version 4.3: Added the
logged_stack
attribute.Constructs an ExpectLog context manager.
- Parameters
logger – Logger object (or name of logger) to watch. Pass an empty string to watch the root logger.
regex – Regular expression to match. Any log entries on the specified logger that match this regex will be suppressed.
required – If true, an exception will be raised if the end of the
with
statement is reached without matching any log entries.
Test runner¶
-
tornado.testing.
main
(**kwargs: Any) → None[source]¶ 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. It is not necessary to use thismain
function to run tests usingAsyncTestCase
; these tests are self-contained and can run with any test runner.The easiest way to run a test is via the command line:
python -m tornado.testing tornado.test.web_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 methodall()
which returns a test suite and then calltornado.testing.main()
. Note that even when a test script is used, theall()
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.web_test
Additional keyword arguments passed through to
unittest.main()
. For example, usetornado.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.Changed in version 5.0: This function produces no output of its own; only that produced by the
unittest
module (previously it would add a PASS or FAIL log message).