tornado.testing — Unit testing support for asynchronous code

优质

小牛编辑

133浏览

2023-12-01

Support classes for automated testing.

and : Subclasses of unittest.TestCase with additional support for testing asynchronous ( based) code.
and : Make test logs less spammy.
: 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='runTest')

subclass for testing -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. To write test functions that use the same yield-based patterns used with the module, decorate your test methods with instead of . This class also provides the and methods for a more manual style of testing. The test method itself must call self.wait(), and asynchronous callbacks should call self.stop() to signal completion.

By default, a new is constructed for each test and is available as self.io_loop. This should be used in the construction of HTTP clients/servers, etc. If the code being tested requires a global , subclasses should override to return it.

The ‘s start and stop methods should not be called directly. Instead, use and . Arguments passed to self.stop are returned from self.wait. It is possible to have multiple wait/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(self.io_loop)
        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(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 MyTestCase3(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()

get_new_ioloop(): Creates a new for this test. May be overridden in subclasses for tests that require a specific (usually the singleton ).

stop(_arg=None, **kwargs)

Stops the , causing one pending (or future) call to to return.

Keyword arguments or a single positional argument passed to are saved and will be returned by .

wait(condition=None, timeout=None)

Runs the 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 the ASYNC_TEST_TIMEOUT environment variable.

If condition is not None, the will be restarted after until condition() returns true.

在 3.1 版更改: Added the ASYNC_TEST_TIMEOUT environment variable.

class tornado.testing.AsyncHTTPTestCase(methodName='runTest')

A test case that starts up an HTTP server.

Subclasses must override , which returns the (or other callback) to be tested. Tests will typically use the provided self.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 to

self.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 use stop() and wait() yourself.

fetch(path, **kwargs)

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 (and so could be used to pass method="POST", body="...", etc).

get_app(): Should be overridden by subclasses to return a or other callback.

get_http_port()

Returns the port used by the server.

A new port is chosen for each test.

get_httpserver_options(): May be overridden by subclasses to return additional keyword arguments for the server.

get_url(path): Returns an absolute url for the given path on the test server.

class tornado.testing.AsyncHTTPSTestCase(methodName='runTest')

A test case that starts an HTTPS server.

Interface is generally the same as .

get_ssl_options()

May be overridden by subclasses to select SSL options.

By default includes a self-signed testing certificate.

tornado.testing.gen_test(func=None, timeout=None)

Testing equivalent of @gen.coroutine, to be applied to test methods.

@gen.coroutine cannot be used on tests because the is not already running. @gen_test should be applied to test methods on subclasses of .

Example:

class MyTest(AsyncHTTPTestCase):
    @gen_test
    def test_something(self):
        response = yield gen.Task(self.fetch('/'))

By default, @gen_test times out after 5 seconds. The timeout may be overridden globally with the ASYNC_TEST_TIMEOUT environment variable, or for each test with the timeout keyword argument:

class MyTest(AsyncHTTPTestCase):
    @gen_test(timeout=10)
    def test_something_slow(self):
        response = yield gen.Task(self.fetch('/'))

3.1 新版功能: The timeout argument and ASYNC_TEST_TIMEOUT environment variable.

在 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, regex, required=True)

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 to true if any exception stack trace was logged.

Usage:

with ExpectLog('tornado.application', "Uncaught exception"):
    error_response = self.fetch("/some_page")

在 4.3 版更改: Added the logged_stack attribute.

Constructs an ExpectLog context manager.

参数:	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 exeption will be raised if the end of the `with` statement is reached without matching any log entries.

class tornado.testing.LogTrapTestCase(methodName='runTest')

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 . This is true for both and the “pretty logging” configured by . It is not compatible with other log buffering mechanisms, such as those provided by some test runners.

4.1 版后已移除: Use the unittest module’s --buffer option instead, or .

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.

Test runner

tornado.testing.main(**kwargs)

A simple test runner.

This test runner is essentially equivalent to 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 . 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 for full argument list.

Helper functions

tornado.testing.bind_unused_port(reuse_port=False)

Binds a server socket to an available port on localhost.

Returns a tuple (socket, port).

在 4.4 版更改: Always binds to 127.0.0.1 without resolving the name localhost.

tornado.testing.get_unused_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.

Use 版后已移除: bind_unused_port instead, which is guaranteed to find an unused port.

tornado.testing.get_async_test_timeout()

Get the global timeout setting for async tests.

Returns a float, the timeout in seconds.

3.1 新版功能.