tornado.testing — Unit testing support for asynchronous code

支持类的自动化测试.

  • AsyncTestCaseAsyncHTTPTestCase :unittest.TestCase的子类,具有测试异步(基于IOLoop )代码的其他支持.

  • ExpectLog :减少测试日志的垃圾邮件.

  • main() :一个简单的测试运行程序(在unittest.main()周围包装),支持tornado.autoreload模块,以便在代码更改时重新运行测试.

Asynchronous test cases

class tornado.testing.AsyncTestCase(methodName: str = 'runTest')[source]

TestCase子类,用于测试基于IOLoop的异步代码.

单元测试框架是同步的,因此测试必须在测试方法返回之前完成. 这意味着异步代码不能以与通常相同的方式使用,必须进行调整以适合. 要使用协程编写测试,请使用tornado.testing.gen_test而不是tornado.gen.coroutine装饰测试方法.

此类还提供了(不建议使用的) stop()wait()方法,以进行更手动的测试. 测试方法本身必须调用self.wait() ,异步回调应调用self.stop()来表示完成.

默认情况下,将为每个测试构造一个新的IOLoop ,并作为self.io_loop . 如果要测试的代码需要全局IOLoop ,则子类应重写get_new_ioloop以返回它.

不应直接调用IOLoopstartstop方法. 而是使用self.stopself.wait . 传递给self.stop参数从self.wait返回. 同一测试中可能有多个wait / stop周期.

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]

返回用于此测试的IOLoop .

默认情况下,为每个测试创建一个新的IOLoop . 如果不适合在每个测试中使用新的IOLoop (例如,如果使用默认IOLoop全局单例),或者提供了按测试的事件循环,则子类可以重写此方法以返回IOLoop.current()由另一个系统(例如pytest-asyncio ).

stop(_arg: Any = None, **kwargs) → None[source]

停止IOLoop ,导致对wait()一个挂起(或将来)调用返回.

关键字参数或传递给stop()的单个位置参数将被保存,并将由wait()返回.

从版本5.1开始不推荐使用 stopwait都已弃用; 使用@gen_test代替.

wait(condition: Callable[[...], bool] = None, timeout: float = None) → None[source]

运行IOLoop直到调用stop或超时已过去.

如果发生超时,将引发异常. 默认超时为5秒. 可以使用timeout关键字参数来覆盖它,也可以使用ASYNC_TEST_TIMEOUT环境变量来全局地覆盖它.

如果condition不为None ,则IOLoop将在stop()之后重新启动,直到condition()返回True为止.

在版本3.1中进行了更改:添加了ASYNC_TEST_TIMEOUT环境变量.

从版本5.1开始不推荐使用 stopwait都已弃用; 使用@gen_test代替.

class tornado.testing.AsyncHTTPTestCase(methodName: str = 'runTest')[source]

启动HTTP服务器的测试用例.

子类必须重写get_app() ,该方法返回要测试的tornado.web.Application (或其他HTTPServer回调). 测试通常将使用提供的self.http_client从此服务器获取URL.

例如,假设用户指南中的" Hello,world"示例位于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')

self.fetch()调用等效于

self.http_client.fetch(self.get_url('/'), self.stop)
response = self.wait()

该示例说明了AsyncTestCase如何将异步操作(如http_client.fetch()转换为同步操作. 如果需要在测试中执行其他异步操作,则可能需要自己使用stop()wait() .

get_app() → tornado.web.Application[source]

应该由子类覆盖,以返回tornado.web.Application或其他HTTPServer回调.

fetch(path: str, raise_error: bool = False, **kwargs) → tornado.httpclient.HTTPResponse[source]

同步获取URL的便捷方法.

给定的路径将附加到本地服务器的主机和端口. 任何其他关键字参数都将直接传递到AsyncHTTPClient.fetch (因此可用于传递method="POST"body="..."等).

如果路径以http://https://开头,则将其视为完整URL,并按原样获取.

如果raise_errorTrue ,则如果响应代码不是200,则将引发tornado.httpclient.HTTPError .这与AsyncHTTPClient.fetchraise_error参数相同,但此处的默认值为False (在AsyncHTTPClient True ),因为测试通常需要处理非200的响应代码.

在版本5.0中更改: Added support for absolute URLs.

在版本5.1中更改:添加了raise_error参数.

从5.1版开始不推荐使用:此方法当前将任何异常转换为状态代码为599的HTTPResponse .在Tornado 6.0中,将传递tornado.httpclient.HTTPError以外的错误,而raise_error=False将仅抑制由于以下原因而引起的错误:非200回应码.

get_httpserver_options() → Dict[str, Any][source]

可能会被子类覆盖,以返回服务器的其他关键字参数.

get_http_port() → int[source]

返回服务器使用的端口.

为每个测试选择一个新端口.

get_url(path: str) → str[source]

返回测试服务器上给定路径的绝对URL.

class tornado.testing.AsyncHTTPSTestCase(methodName: str = 'runTest')[source]

启动HTTPS服务器的测试用例.

接口通常与AsyncHTTPTestCase相同.

get_ssl_options() → Dict[str, Any][source]

可以被子类覆盖以选择SSL选项.

默认情况下包括一个自签名的测试证书.

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.

由于IOLoop尚未运行,因此无法在测试中使用@gen.coroutine . @gen_test应该应用于AsyncTestCase子类的测试方法.

Example:

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

默认情况下, @gen_test在5秒后超时. 可以使用ASYNC_TEST_TIMEOUT环境变量全局覆盖超时,也可以使用timeout关键字参数对每个测试覆盖timeout

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

请注意, @gen_testAsyncTestCase.stopAsyncTestCase.waitAsyncHTTPTestCase.fetch不兼容. 如上所示,使用yield self.http_client.fetch(self.get_url()) .

版本3.1中的新增功能: timeout参数和ASYNC_TEST_TIMEOUT环境变量.

在版本4.0中进行了更改:包装器现在通过*args, **kwargs传递*args, **kwargs因此可以在带有参数的函数上使用.

Controlling log output

class tornado.testing.ExpectLog(logger: Union[logging.Logger, str], regex: str, required: bool = True)[source]

上下文管理器,用于捕获和抑制预期的日志输出.

使错误条件的测试噪音较小,同时仍使意外日志条目可见时很有用. 不是线程安全的.

如果记录了任何异常堆栈跟踪,则属性logged_stack设置为True .

Usage:

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

在版本4.3中更改:添加了logged_stack属性.

构造一个ExpectLog上下文管理器.

Parameters
  • 记录器 –要监视的记录器对象(或记录器名称). 传递一个空字符串以查看根记录器.

  • regex-要匹配的正则表达式. 指定记录器上与此正则表达式匹配的所有日志条目都将被隐藏.

  • 必需 –如果为true,则在到达with语句的末尾而没有匹配任何日志条目时,将引发异常.

Test runner

tornado.testing.main(**kwargs) → None[source]

一个简单的测试运行器.

该测试运行程序从本质unittest.main等同于标准库中的unittest.main ,但是增加了对Tornado样式的选项解析和日志格式的支持. 这是没有必要使用这个main函数使用运行测试AsyncTestCase ; 这些测试是独立的,可以与任何测试运行程序一起运行.

运行测试的最简单方法是通过命令行:

python -m tornado.testing tornado.test.web_test

请参阅标准库unittest模块以获取可以指定测试的方式.

具有许多测试的项目可能希望定义一个测试脚本,例如tornado/test/runtests.py . 该脚本应定义一个方法all() ,该方法返回一个测试套件,然后调用tornado.testing.main() . 请注意,即使使用测试脚本,也可以通过在命令行上命名单个测试来覆盖all()测试套件:

# Runs all tests
python -m tornado.test.runtests
# Runs one test
python -m tornado.test.runtests tornado.test.web_test

传递给unittest.main()其他关键字参数. 例如,使用tornado.testing.main(verbosity=2)在运行时显示许多测试详细信息. 有关完整的参数列表,请参见http://docs.python.org/library/unittest.html#unittest.main .

在版本5.0中更改:此函数不产生自己的输出. 仅由unittest模块生成的内容(以前会添加PASS或FAIL日志消息).

Helper functions

tornado.testing.bind_unused_port(reuse_port: bool = False) → Tuple[socket.socket, int][source]

将服务器套接字绑定到本地主机上的可用端口.

Returns a tuple (socket, port).

在版本4.4中更改:始终绑定到127.0.0.1而不解析名称localhost .

tornado.testing.get_async_test_timeout() → float[source]

Get the global timeout setting for async tests.

返回一个浮点数,超时以秒为单位.

3.1版中的新功能.