--- title: "测试工具" version: 5.2 locale: zh-hans source: https://docs.djangoproject.com/zh-hans/5.2/topics/testing/tools/ canonical: https://djangodocs.dev/zh-hans/5.2/topics/testing/tools/ --- # 测试工具 Django 提供了一小组在编写测试时会派上用场的工具。 ## 测试客户端测试客户端是一个 Python 类，它充当虚拟的网络浏览器，允许你以编程方式测试你的视图并与你的基于 Django 的应用程序进行交互。你可以使用测试客户端执行以下操作： - 模拟 URL 上的 GET 和 POST 请求并观察响应——从低级 HTTP（结果头和状态码）到页面内容，应有尽有。 - 查看重定向链（如果有的话），并检查每个步骤的 URL 和状态码。 - 测试给定的请求是否由给定的包含某些值以及模板上下文的 Django 模板渲染。请注意，测试客户端并不是要取代 [Selenium](https://www.selenium.dev/) 或其他“浏览器内”框架。Django 的测试客户端有不同的侧重点。简而言之： - 使用 Django 的测试客户端来确定要渲染的模板正确，并且模板已传递了正确的上下文数据。 - 使用 [`RequestFactory`](/zh-hans/5.2/topics/testing/advanced/#django.test.RequestFactory) 直接测试视图函数，绕过路由和中间件层。 - 使用像 [Selenium](https://www.selenium.dev/) 这样的浏览器框架来测试 *渲染的* HTML 和网页的 *行为*，即 JavaScript 功能。Django 还为这些框架提供了特殊的支持；请参阅 [`LiveServerTestCase`](#django.test.LiveServerTestCase) 部分以获取更多详细信息。一个全面的测试套件应该使用所有这些测试类型的组合。 ### 概述和一个简单的例子要使用测试客户端，请实例化 `django.test.Client` 并获取 web 页面： ```pycon >>> from django.test import Client >>> c = Client() >>> response = c.post("/login/", {"username": "john", "password": "smith"}) >>> response.status_code 200 >>> response = c.get("/customer/details/") >>> response.content b'>> c.get("/login/") ``` 这是不正确的： ```pycon >>> c.get("https://www.example.com/login/") ``` 测试客户端无法获取不由你的 Django 项目提供支持的网页。如果你需要获取其他网页，使用 Python 标准库模块如 [`urllib`](https://docs.python.org/3/library/urllib.html#module-urllib)。 - 为了解析 URL，测试客户端使用你的 [`ROOT_URLCONF`](/zh-hans/5.2/ref/settings/#std-setting-ROOT_URLCONF) 配置指向的任何 URLconf。 - 虽然上面的例子可以在 Python 交互式解释器中工作，但是测试客户端的一些功能，尤其是与模板相关的功能，只有在 *测试运行时* 才可以使用。原因是 Django 的测试运行器为了确定哪个模板被给定的视图加载，执行了一点黑魔法。这个黑魔法（本质上是内存中 Django 模板系统的补丁）只发生在测试运行期间。 - 默认情况下，测试客户端将禁用站点执行的任何 CSRF 检查。如果出于某种原因，你 *想要* 测试客户端执行 CSRF 检查，你可以创建一个强制执行 CSRF 检查的测试客户端实例。要做到这一点，构建客户端时传入 `enforce_csrf_checks` 参数： ```pycon >>> from django.test import Client >>> csrf_client = Client(enforce_csrf_checks=True) ``` ### 发出请求使用 `django.test.Client` 类发出请求。 #### `class Client(enforce_csrf_checks=False, raise_request_exception=True, json_encoder=DjangoJSONEncoder, * (Keyword-only parameters separator (PEP 3102)), headers=None, query_params=None, **defaults)` 一个用于测试的 HTTP 客户端。接受多个参数，可以自定义其行为。 `headers` 允许你指定默认头信息，这些头信息将与每个请求一起发送。例如，要设置一个 `User-Agent` 头信息： ``` client = Client(headers={"user-agent": "curl/7.79.1"}) ``` `query_params` 允许你指定将在每个请求上设置的默认查询字符串。在 `**defaults` 中的任意关键字参数设置了 WSGI [**environ 变量**](https://peps.python.org/pep-3333/#environ-variables)。例如，要设置脚本名称： ``` client = Client(SCRIPT_NAME="/app/") ``` > **Note** > > 以 `HTTP_` 前缀开头的关键字参数将被设置为头信息，但为了可读性，应该优先使用 `headers` 参数。传递给 [`get()`](#django.test.Client.get)、[`post()`](#django.test.Client.post) 等的 `headers`、`query_params` 和 `extra` 关键字参数的值优先于传递给类构造函数的默认值。 `enforce_csrf_checks` 参数可用于测试 CSRF 保护（见上文）。 `raise_request_exception` 参数允许控制是否在请求过程中引出的异常也应该在测试中引出。默认值为 `True`。 `json_encoder` 参数允许为 [`post()`](#django.test.Client.post) 中描述的 JSON 序列化设置一个自定义 JSON 编码器。 > **Changed in Django 5.1** > > 增加了 `query_params` 参数。一旦有了 `Client` 实例，就可以调用以下任何一种方法： #### `get(path, data=None, follow=False, secure=False, * (Keyword-only parameters separator (PEP 3102)), headers=None, query_params=None, **extra)` 对提供的 `path` 上发出 GET 请求，并返回一个 `Response` 对象，如下所述。 `query_params` 字典中的键值对用于设置查询字符串。例如： ```pycon >>> c = Client() >>> c.get("/customers/details/", query_params={"name": "fred", "age": 7}) ``` ...将导致等同于以下 GET 请求的评估： ```text /customers/details/?name=fred&age=7 ``` 也可以将这些参数传递给 `data` 参数。但是，`query_params` 是首选，因为它适用于任何 HTTP 方法。 `headers` 参数可用于指定要在请求中发送的头信息。例如： ```pycon >>> c = Client() >>> c.get( ... "/customers/details/", ... query_params={"name": "fred", "age": 7}, ... headers={"accept": "application/json"}, ... ) ``` ......会将 HTTP 头 `HTTP_ACCEPT` 发送到 detail 视图，这是测试使用 [`django.http.HttpRequest.accepts()`](/zh-hans/5.2/ref/request-response/#django.http.HttpRequest.accepts) 方法的代码路径的好方法。任意关键字参数设置了 WSGI [**environ 变量**](https://peps.python.org/pep-3333/#environ-variables)。例如，设置脚本名称的头信息： ```pycon >>> c = Client() >>> c.get("/", SCRIPT_NAME="/app/") ``` 如果你已经有了 URL 编码形式的 GET 参数，你可以使用该编码而不是使用 data 参数。例如，之前的 GET 请求也可以这样表示： ```pycon >>> c = Client() >>> c.get("/customers/details/?name=fred&age=7") ``` 如果你提供的 URL 同时包含编码的 GET 数据和 `query_params` 或 `data` 参数，这些参数将优先。如果将 `follow` 设置为 `True`，客户端将遵循所有重定向，并且将在响应对象中设置 `redirect_chain` 属性，该属性是包含中间 URL 和状态码的元组。如果你有一个 URL `/redirect_me/`，它重定向到 `/next/`，然后重定向到 `/final/`，你会看到以下内容： ```pycon >>> response = c.get("/redirect_me/", follow=True) >>> response.redirect_chain [('http://testserver/next/', 302), ('http://testserver/final/', 302)] ``` 如果你把 `secure` 设置为 `True`，则客户端将模拟 HTTPS 请求。 > **Changed in Django 5.1** > > 增加了 `query_params` 参数。 #### `post(path, data=None, content_type=MULTIPART_CONTENT, follow=False, secure=False, * (Keyword-only parameters separator (PEP 3102)), headers=None, query_params=None, **extra)` 在提供的 `path` 上发出一个 POST 请求，并返回一个 `Response` 对象，如下所述。 `data` 字典中的键值对用于提交 POST 数据。例如： ```pycon >>> c = Client() >>> c.post("/login/", {"name": "fred", "passwd": "secret"}) ``` ...将导致对该 URL 发起 POST 请求的评估： ```text /login/ ``` ...使用以下 POST 数据： ```text name=fred&passwd=secret ``` 如果你提供 `application/json` 为 `content_type`，则如果 `data` 是一个字典、列表或元组时，使用 [`json.dumps()`](https://docs.python.org/3/library/json.html#json.dumps) 进行序列化。序列化默认是通过 [`DjangoJSONEncoder`](/zh-hans/5.2/topics/serialization/#django.core.serializers.json.DjangoJSONEncoder)，可以通过为 [`Client`](#django.test.Client) 提供 `json_encoder` 参数覆盖。这个序列化也会发生在 [`put()`](#django.test.Client.put)、[`patch()`](#django.test.Client.patch) 和 [`delete()`](#django.test.Client.delete) 请求中。如果你要提供任何其他的 `content_type` （例如 `text/xml` 用于 XML 有效载荷），使用HTTP `Content-Type` 头中的 `content_type`，`data` 的内容在 POST 请求中按原样发送。如果你没有为 `content_type` 提供一个值，`data` 中的值将以 `multipart/form-data` 的内容类型进行传输。在这种情况下，`data` 中的键值对将被编码为多部分消息，并用于创建 POST 数据有效载荷。要为一个给定的键提交多个值——例如，要指定 `', '', ) ``` `html1` 和 `html2` 必须包含 HTML。如果其中一个不能被解析，将产生一个 `AssertionError`。错误时的输出可以用 `msg` 参数自定义。 #### `SimpleTestCase.assertHTMLNotEqual(html1, html2, msg=None)` 断言字符串 `html1` 和 `html2` *不* 相等。比较是基于 HTML 语义的。详见 [`assertHTMLEqual()`](#django.test.SimpleTestCase.assertHTMLEqual)。 `html1` 和 `html2` 必须包含 HTML。如果其中一个不能被解析，将产生一个 `AssertionError`。错误时的输出可以用 `msg` 参数自定义。 #### `SimpleTestCase.assertXMLEqual(xml1, xml2, msg=None)` 断言字符串 `xml1` 和 `xml2` 相等。比较是基于 XML 语义的。与 [`assertHTMLEqual()`](#django.test.SimpleTestCase.assertHTMLEqual) 类似，比较是在解析内容上进行的，因此只考虑语义差异，而不是语法差异。当任何参数中传递了无效的 XML 时，即使两个字符串相同，也总是会引发一个 `AssertionError`。忽略 XML 声明、文档类型、处理指令和注释。只有根元素和它的子元素被比较。错误时的输出可以用 `msg` 参数自定义。 #### `SimpleTestCase.assertXMLNotEqual(xml1, xml2, msg=None)` 断言字符串 `xml1` 和 `xml2` *不* 相等。比较是基于 XML 语义的，参见 [`assertXMLEqual()`](#django.test.SimpleTestCase.assertXMLEqual)。错误时的输出可以用 `msg` 参数自定义。 #### `SimpleTestCase.assertInHTML(needle, haystack, count=None, msg_prefix='')` 断言 HTML 片段 `needle` 在 `haystack` 中出现一次。如果指定了 `count` 整数参数，则将严格核查 `needle` 的出现次数。在大多数情况下，空白是被忽略的，属性排序并不重要。参见 [`assertHTMLEqual()`](#django.test.SimpleTestCase.assertHTMLEqual) 以了解更多细节。 > **Changed in Django 5.1** > > 在旧版本中，错误消息不包含 `haystack`。 #### `SimpleTestCase.assertNotInHTML(needle, haystack, msg_prefix='')` > **New in Django 5.1** 断言 HTML 片段 `needle` *不* 包含在 `haystack` 中。在大多数情况下，空白是被忽略的，属性排序并不重要。参见 [`assertHTMLEqual()`](#django.test.SimpleTestCase.assertHTMLEqual) 以了解更多细节。 #### `SimpleTestCase.assertJSONEqual(raw, expected_data, msg=None)` 断言 JSON 片段 `raw` 和 `expected_data` 相等。通常的 JSON 非显性空格规则适用，因为重量级是委托给 [`json`](https://docs.python.org/3/library/json.html#module-json) 库的。错误时的输出可以用 `msg` 参数自定义。 #### `SimpleTestCase.assertJSONNotEqual(raw, expected_data, msg=None)` 断言 JSON 片段 `raw` 和 `expected_data` *不* 相等。详见 [`assertJSONEqual()`](#django.test.SimpleTestCase.assertJSONEqual)。错误时的输出可以用 `msg` 参数自定义。 #### `TransactionTestCase.assertQuerySetEqual(qs, values, transform=None, ordered=True, msg=None)` 断言一个查询集 `qs` 与一个特定的可迭代对象 `values` 的值匹配。如果提供了 `transform`，`values` 将与应用 `transform` 于 `qs` 而产生的列表中每个成员进行比较。默认情况下，比较也是依赖于顺序的。如果 `qs` 不提供隐式排序，你可以将 `ordered` 参数设置为 `False`，这将使比较变成 `collections.Counter` 比较。如果顺序是未定义的（如果给定的 `qs` 不是有序的，并且比较的对象是一个以上的有序值），会产生一个 `ValueError`。错误时的输出可以用 `msg` 参数自定义。 #### `TransactionTestCase.assertNumQueries(num, func, *args, **kwargs)` 断言当 `func` 与 `*args` 和 `**kwargs` 一起调用时，会执行 `num` 次数据库查询。如果 `kwargs` 中存在 `"using"` 键，则使用该键作为数据库别名，以检查查询次数： ``` self.assertNumQueries(7, my_function, using="non_default_db") ``` 如果你想调用一个带有 `using` 参数的函数，你可以通过用 `lambda` 包装调用来增加一个额外的参数： ``` self.assertNumQueries(7, lambda: my_function(using=7)) ``` 你也可以用它作为上下文管理器: ``` with self.assertNumQueries(2): Person.objects.create(name="Aaron") Person.objects.create(name="Daniel") ``` ### 标记测试你可以给你的测试打上标签，这样你就可以轻松地运行一个特定的子集。例如，你可以标记快速或慢速测试： ``` from django.test import tag class SampleTestCase(TestCase): @tag("fast") def test_fast(self): ... @tag("slow") def test_slow(self): ... @tag("slow", "core") def test_slow_but_core(self): ... ``` 你还可以给一个测试用例类打上标签： ``` @tag("slow", "core") class SampleTestCase(TestCase): ... ``` 子类从超类继承标签，方法从其类继承标签。如： ``` @tag("foo") class SampleTestCaseChild(SampleTestCase): @tag("bar") def test(self): ... ``` `SampleTestCaseChild.test` 将用 `'slow'`、`'core'`、`'bar'` 和 `'foo'` 来标注。然后你可以选择要运行的测试。例如，只运行快速测试： ```console $ ./manage.py test --tag=fast ``` *Windows* ```doscon ...\> manage.py test --tag=fast ``` 或者运行快速测试和核心测试（即使它很慢）： ```console $ ./manage.py test --tag=fast --tag=core ``` *Windows* ```doscon ...\> manage.py test --tag=fast --tag=core ``` 你也可以通过标签来排除测试。如果要运行不慢的核心测试： ```console $ ./manage.py test --tag=core --exclude-tag=slow ``` *Windows* ```doscon ...\> manage.py test --tag=core --exclude-tag=slow ``` `test --exclud-tag` 优先于 [`test --tag`](/zh-hans/5.2/ref/django-admin/#cmdoption-test-tag)，所以如果一个测试有两个标签，你选择了其中一个而排除了另一个，测试就不会被运行。 ## 测试异步代码如果你只是想测试异步视图的输出，标准测试客户端将在自己的异步循环中运行它们，而不需要你做任何额外的工作。但是，如果你想为 Django 项目编写完全异步的测试，你需要考虑到几个问题。首先，你的测试必须是测试类上的 `async def` 方法（为了给它们一个异步的上下文）。Django 会自动检测到任何 `async def` 的测试，并将它们封装在自己的事件循环中运行。如果你从一个异步函数进行测试，你也必须使用异步测试客户端。这在任何测试中都可以作为 `django.test.AsyncClient` 或 `self.async_client` 使用。 #### `class AsyncClient(enforce_csrf_checks=False, raise_request_exception=True, * (Keyword-only parameters separator (PEP 3102)), headers=None, query_params=None, **defaults)` `AsyncClient` 具有与同步（普通）测试客户端相同的方法和签名，除了以下异常情况： - 在初始化中，`defaults` 中的任意关键字参数都直接添加到 ASGI 作用域中。 - 作为 `extra` 关键字参数传递的头部不应该具有同步客户端所需的 `HTTP_` 前缀（参见 [`Client.get()`](#django.test.Client.get)）。例如，以下是如何设置 HTTP `Accept` 头部的方法： ```pycon >>> c = AsyncClient() >>> c.get("/customers/details/", {"name": "fred", "age": 7}, ACCEPT="application/json") ``` > **Changed in Django 5.1** > > 增加了 `query_params` 参数。使用 `AsyncClient` 任何提出请求的方法都必须被等待： ``` async def test_my_thing(self): response = await self.async_client.get("/some-url/") self.assertEqual(response.status_code, 200) ``` 异步客户端也可以调用同步视图；它通过 Django 的 [异步请求路径](/zh-hans/5.2/topics/async/) 运行，它支持这两种方式。任何通过 `AsyncClient` 调用的视图都会得到一个 `ASGIRequest` 对象作为它的 `request`，而不是普通客户端创建的 `WSGIRequest`。 > **Warning** > > 如果你使用的是测试装饰器，它们必须是异步兼容的，以确保它们正确工作。Django 内置的装饰器会正常工作，但第三方的装饰器可能会出现无法执行的情况（它们会“包装”执行流程中错误的部分，而不是你的测试）。 > > 如果你需要使用这些装饰器，那么你应该用 [`async_to_sync()`](/zh-hans/5.2/topics/async/#asgiref.sync.async_to_sync) 来装饰你的测试方法: > > ``` > from asgiref.sync import async_to_sync > from django.test import TestCase > > > class MyTests(TestCase): > @mock.patch(...) > @async_to_sync > async def test_my_thing(self): ... > ``` ## 邮件服务如果你的任何 Django 视图使用 [Django 的邮件功能](/zh-hans/5.2/topics/email/) 发送电子邮件，你可能不想每次使用该视图运行测试时都发送电子邮件。出于这个原因，Django 的测试运行器会自动将所有 Django 发送的邮件重定向到一个虚拟的发件箱。这让你可以测试发送邮件的每一个方面——从发送邮件的数量到每封邮件的内容——而不用实际发送邮件。测试运行器通过透明的将正常的邮件后端替换为测试后端来实现。（别担心——这对 Django 之外的其他邮件发送器没有影响，比如你机器的邮件服务器，如果你正在运行一个的话。） #### `django.core.mail.outbox` 在测试运行过程中，每一封发出的邮件都会保存在 `django.core.mail.outbox` 中。这是所有已经发送的 [`EmailMessage`](/zh-hans/5.2/topics/email/#django.core.mail.EmailMessage) 实例的列表。 `outbox` 属性是一个特殊的属性，只有在使用 `locmem` 邮件后端时才会创建。它通常不作为 [`django.core.mail`](/zh-hans/5.2/topics/email/#module-django.core.mail) 模块的一部分存在，你也不能直接导入它。下面的代码展示了如何正确访问这个属性。下面是一个检查 `django.core.mail.outbox` 长度和内容的测试示例： ``` from django.core import mail from django.test import TestCase class EmailTest(TestCase): def test_send_email(self): # Send message. mail.send_mail( "Subject here", "Here is the message.", "from@example.com", ["to@example.com"], fail_silently=False, ) # Test that one message has been sent. self.assertEqual(len(mail.outbox), 1) # Verify that the subject of the first message is correct. self.assertEqual(mail.outbox[0].subject, "Subject here") ``` 正如 [之前](#emptying-test-outbox)，在 Django `*TestCase` 中的每个测试开始时，测试发件箱都会被清空。要手动清空发件箱，将空列表分配给 `mail.outbox`： ``` from django.core import mail # Empty the test outbox mail.outbox = [] ``` ## 管理命令管理命令可以用 [`call_command()`](/zh-hans/5.2/ref/django-admin/#django.core.management.call_command) 函数来测试。输出可以重定向到 `StringIO` 实例中： ``` from io import StringIO from django.core.management import call_command from django.test import TestCase class ClosepollTest(TestCase): def test_command_output(self): out = StringIO() call_command("closepoll", poll_ids=[1], stdout=out) self.assertIn('Successfully closed poll "1"', out.getvalue()) ``` ## 忽略测试 unittest 库提供了 [`@skipIf`](https://docs.python.org/3/library/unittest.html#unittest.skipIf) 和 [`@skipUnless`](https://docs.python.org/3/library/unittest.html#unittest.skipUnless) 装饰器，允许你跳过测试，如果你事先知道这些测试在某些条件下会失败。例如，如果你的测试需要一个特定的可选库才能成功，你可以用 [`@skipIf`](https://docs.python.org/3/library/unittest.html#unittest.skipIf) 来装饰测试用例。然后，测试运行器将报告测试没有被执行以及原因，而不是测试失败或完全省略测试。为了补充这些测试跳过行为，Django 提供了两个额外的跳过装饰器。这些装饰器不是测试一个通用的布尔值，而是检查数据库的能力，如果数据库不支持一个特定的命名特性，则跳过测试。装饰器使用一个字符串标识符来描述数据库特征。这个字符串对应于数据库连接特征类的属性。参见 [django.db.backends.base.features.BaseDatabaseFeatures 类](https://github.com/django/django/blob/stable/5.2.x/django/db/backends/base/features.py) 以获得可作为跳过测试基础的数据库特征的完整列表。 #### `skipIfDBFeature(*feature_name_strings)` 如果支持某个命名的数据库功能，则跳过装饰测试或 `TestCase`。例如，如果数据库支持事务，下面的测试将不会被执行（例如，在PostgreSQL 下，它将 *不* 会运行，但在 MySQL 的 MyISAM 表下却可以）： ``` class MyTests(TestCase): @skipIfDBFeature("supports_transactions") def test_transaction_behavior(self): # ... conditional test code pass ``` #### `skipUnlessDBFeature(*feature_name_strings)` 如果 *不* 支持某个命名的数据库功能，则跳过装饰测试或 `TestCase`。例如，接下来的测试仅在支持事务的数据库下执行(如：可以是PostgreSQL，但不可以是使用MyISAM数据库引擎的MySQL): ``` class MyTests(TestCase): @skipUnlessDBFeature("supports_transactions") def test_transaction_behavior(self): # ... conditional test code pass ```