测试工具

Django 提供了一小组在编写测试时会派上用场的工具。

测试客户端

The test client is a Python class that acts as a dummy web browser, allowing you to test your views and interact with your Django-powered application programmatically.

你可以使用测试客户端执行以下操作：

  • 模拟 URL 上的 GET 和 POST 请求并观察响应——从低级 HTTP（结果头和状态码）到页面内容，应有尽有。
  • 查看重定向链（如果有的话），并检查每个步骤的 URL 和状态码。
  • 测试给定的请求是否由给定的包含某些值以及模板上下文的 Django 模板渲染。

请注意，测试客户端并不是要取代 Selenium 或其他“浏览器内”框架。Django 的测试客户端有不同的侧重点。简而言之：

  • 使用 Django 的测试客户端来确定要渲染的模板正确，并且模板已传递了正确的上下文数据。
  • Use RequestFactory to test view functions directly, bypassing the routing and middleware layers.
  • Use in-browser frameworks like Selenium to test rendered HTML and the behavior of web pages, namely JavaScript functionality. Django also provides special support for those frameworks; see the section on LiveServerTestCase for more details.

A comprehensive test suite should use a combination of all of these test types.

概述和一个简单的例子

To use the test client, instantiate django.test.Client and retrieve web pages:

>>> 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'<!DOCTYPE html...'

如本例所示，你可以从 Python 交互式解释器的会话中实例化 Client。

请注意测试客户端如何工作的一些重要事项：

  • The test client does not require the web server to be running. In fact, it will run just fine with no web server running at all! That's because it avoids the overhead of HTTP and deals directly with the Django framework. This helps make the unit tests run quickly.

  • When retrieving pages, remember to specify the path of the URL, not the whole domain. For example, this is correct:

    >>> c.get("/login/")

    This is incorrect:

    >>> c.get("https://www.example.com/login/")

    The test client is not capable of retrieving web pages that are not powered by your Django project. If you need to retrieve other web pages, use a Python standard library module such as urllib.

  • 为了解析 URL，测试客户端使用你的 ROOT_URLCONF 配置指向的任何 URLconf。

  • 虽然上面的例子可以在 Python 交互式解释器中工作，但是测试客户端的一些功能，尤其是与模板相关的功能，只有在 测试运行时 才可以使用。

    原因是 Django 的测试运行器为了确定哪个模板被给定的视图加载，执行了一点黑魔法。这个黑魔法（本质上是内存中 Django 模板系统的补丁）只发生在测试运行期间。

  • 默认情况下，测试客户端将禁用站点执行的任何 CSRF 检查。

    If, for some reason, you want the test client to perform CSRF checks, you can create an instance of the test client that enforces CSRF checks. To do this, pass in the enforce_csrf_checks argument when you construct your client:

    >>> 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, *, headers=None, **defaults)

A testing HTTP client. Takes several arguments that can customize behavior.

headers allows you to specify default headers that will be sent with every request. For example, to set a User-Agent header:

client = Client(headers={"user-agent": "curl/7.79.1"})

Arbitrary keyword arguments in **defaults set WSGI environ variables. For example, to set the script name:

client = Client(SCRIPT_NAME="/app/")

备注

Keyword arguments starting with a HTTP_ prefix are set as headers, but the headers parameter should be preferred for readability.

The values from the headers and extra keyword arguments passed to get(), post(), etc. have precedence over the defaults passed to the class constructor.

enforce_csrf_checks 参数可用于测试 CSRF 保护（见上文）。

raise_request_exception 参数允许控制是否在请求过程中引出的异常也应该在测试中引出。默认值为 True。

json_encoder 参数允许为 post() 中描述的 JSON 序列化设置一个自定义 JSON 编码器。

一旦有了 Client 实例，就可以调用以下任何一种方法：

Changed in Django 4.2:

The headers parameter was added.

get(path, data=None, follow=False, secure=False, *, headers=None, **extra)

对提供的 path 上发出 GET 请求，并返回一个 Response 对象，如下所述。

The key-value pairs in the data dictionary are used to create a GET data payload. For example:

>>> c = Client()
>>> c.get("/customers/details/", {"name": "fred", "age": 7})

...will result in the evaluation of a GET request equivalent to:

/customers/details/?name=fred&age=7

The headers parameter can be used to specify headers to be sent in the request. For example:

>>> c = Client()
>>> c.get(
...     "/customers/details/",
...     {"name": "fred", "age": 7},
...     headers={"accept": "application/json"},
... )

......会将 HTTP 头 HTTP_ACCEPT 发送到 detail 视图，这是测试使用 django.http.HttpRequest.accepts() 方法的代码路径的好方法。

Arbitrary keyword arguments set WSGI environ variables. For example, headers to set the script name:

>>> c = Client()
>>> c.get("/", SCRIPT_NAME="/app/")

If you already have the GET arguments in URL-encoded form, you can use that encoding instead of using the data argument. For example, the previous GET request could also be posed as:

>>> c = Client()
>>> c.get("/customers/details/?name=fred&age=7")

如果你提供的 URL 同时包含编码的 GET 数据和数据参数，数据参数将优先。

如果将 follow 设置为 True，客户端将遵循所有重定向，并且将在响应对象中设置 redirect_chain 属性，该属性是包含中间 URL 和状态码的元组。

If you had a URL /redirect_me/ that redirected to /next/, that redirected to /final/, this is what you'd see:

>>> response = c.get("/redirect_me/", follow=True)
>>> response.redirect_chain
[('http://testserver/next/', 302), ('http://testserver/final/', 302)]

如果你把 secure 设置为 True，则客户端将模拟 HTTPS 请求。

Changed in Django 4.2:

The headers parameter was added.

post(path, data=None, content_type=MULTIPART_CONTENT, follow=False, secure=False, *, headers=None, **extra)

在提供的 path 上发出一个 POST 请求，并返回一个 Response 对象，如下所述。

The key-value pairs in the data dictionary are used to submit POST data. For example:

>>> c = Client()
>>> c.post("/login/", {"name": "fred", "passwd": "secret"})

...will result in the evaluation of a POST request to this URL:

/login/

...with this POST data:

name=fred&passwd=secret

如果你提供 application/json 为 content_type，则如果 data 是一个字典、列表或元组时，使用 json.dumps() 进行序列化。序列化默认是通过 DjangoJSONEncoder，可以通过为 Client 提供 json_encoder 参数覆盖。这个序列化也会发生在 put()、patch() 和 delete() 请求中。

如果你要提供任何其他的 content_type （例如 text/xml 用于 XML 有效载荷），使用HTTP Content-Type 头中的 content_type，data 的内容在 POST 请求中按原样发送。

如果你没有为 content_type 提供一个值，data 中的值将以 multipart/form-data 的内容类型进行传输。在这种情况下，data 中的键值对将被编码为多部分消息，并用于创建 POST 数据有效载荷。

要为一个给定的键提交多个值——例如，要指定 <select multiple> 的选择——为所需键提供一个列表或元组的值。例如，这个 data 的值将为名为 choices 的字段提交三个选择值：

{"choices": ["a", "b", "d"]}

Submitting files is a special case. To POST a file, you need only provide the file field name as a key, and a file handle to the file you wish to upload as a value. For example, if your form has fields name and attachment, the latter a FileField:

>>> c = Client()
>>> with open("wishlist.doc", "rb") as fp:
...     c.post("/customers/wishes/", {"name": "fred", "attachment": fp})
...

You may also provide any file-like object (e.g., StringIO or BytesIO) as a file handle. If you're uploading to an ImageField, the object needs a name attribute that passes the validate_image_file_extension validator. For example:

>>> from io import BytesIO
>>> img = BytesIO(
...     b"GIF89a\x01\x00\x01\x00\x00\x00\x00!\xf9\x04\x01\x00\x00\x00"
...     b"\x00,\x00\x00\x00\x00\x01\x00\x01\x00\x00\x02\x01\x00\x00"
... )
>>> img.name = "myimage.gif"

请注意，如果你想在多次调用 post() 时使用同一个文件句柄，那么你需要在两次调用之间手动重置文件指针。最简单的方法是在向 post() 提供文件后手动关闭文件，如上所示。

你还应确保文件的打开方式允许数据被读取。如果你的文件包含二进制数据，如图像，这意味着你需要以 rb （读取二进制）模式打开文件。

The headers and extra parameters acts the same as for Client.get().

If the URL you request with a POST contains encoded parameters, these parameters will be made available in the request.GET data. For example, if you were to make the request:

>>> c.post("/login/?visitor=true", {"name": "fred", "passwd": "secret"})

......处理这个请求的视图可以询问 request.POST 来检索用户名和密码，也可以询问 request.GET 来确定该用户是否是访客。

如果将 follow 设置为 True，客户端将遵循所有重定向，并且将在响应对象中设置 redirect_chain 属性，该属性是包含中间 URL 和状态码的元组。

如果你把 secure 设置为 True，则客户端将模拟 HTTPS 请求。

Changed in Django 4.2:

The headers parameter was added.

head(path, data=None, follow=False, secure=False, *, headers=None, **extra)

Makes a HEAD request on the provided path and returns a Response object. This method works just like Client.get(), including the follow, secure, headers, and extra parameters, except it does not return a message body.

Changed in Django 4.2:

The headers parameter was added.

options(path, data='', content_type='application/octet-stream', follow=False, secure=False, *, headers=None, **extra)

在提供的 path 上发出一个 OPTIONS 请求并返回一个 Response 对象。用于测试 RESTful 接口。

当提供 data 时，它将被用作请求主体并且 Content-Type 头被设置为 content_type。

The follow, secure, headers, and extra parameters act the same as for Client.get().

Changed in Django 4.2:

The headers parameter was added.

put(path, data='', content_type='application/octet-stream', follow=False, secure=False, *, headers=None, **extra)

在提供的 path 上发出一个 PUT 请求，并返回一个 Response 对象。用于测试 RESTful 接口。

当提供 data 时，它将被用作请求主体并且 Content-Type 头被设置为 content_type。

The follow, secure, headers, and extra parameters act the same as for Client.get().

Changed in Django 4.2:

The headers parameter was added.

patch(path, data='', content_type='application/octet-stream', follow=False, secure=False, *, headers=None, **extra)

在提供的 path 上发出一个 PATCH 请求，并返回一个 Response 对象。用于测试 RESTful 接口。

The follow, secure, headers, and extra parameters act the same as for Client.get().

Changed in Django 4.2:

The headers parameter was added.

delete(path, data='', content_type='application/octet-stream', follow=False, secure=False, *, headers=None, **extra)

在提供的 path 上发出一个 DELETE 请求，并返回一个 Response 对象。用于测试 RESTful 接口。

当提供 data 时，它将被用作请求主体并且 Content-Type 头被设置为 content_type。

The follow, secure, headers, and extra parameters act the same as for Client.get().

Changed in Django 4.2:

The headers parameter was added.

trace(path, follow=False, secure=False, *, headers=None, **extra)

在提供的 path 上发出一个 TRACE 请求，并返回一个 Response 对象。用于模拟诊断探针。

Unlike the other request methods, data is not provided as a keyword parameter in order to comply with RFC 9110#section-9.3.8, which mandates that TRACE requests must not have a body.

The follow, secure, headers, and extra parameters act the same as for Client.get().

Changed in Django 4.2:

The headers parameter was added.

login(**credentials)

如果你的网站使用了 Django 的 认证系统，并且你需要处理登录用户的问题，你可以使用测试客户端的 login() 方法来模拟用户登录网站的效果。

调用此方法后，测试客户端将拥有通过任何可能构成视图一部分的基于登录的测试所需的所有 cookie 和会话数据。

The format of the credentials argument depends on which authentication backend you're using (which is configured by your AUTHENTICATION_BACKENDS setting). If you're using the standard authentication backend provided by Django (ModelBackend), credentials should be the user's username and password, provided as keyword arguments:

>>> c = Client()
>>> c.login(username="fred", password="secret")

# Now you can access a view that's only available to logged-in users.

如果你使用的是不同的认证后端，这个方法可能需要不同的凭证。它需要你的后端 authenticate() 方法所需要的任何凭证。

如果凭证被接受且登录成功，则 login() 返回 True。

最后，在使用这个方法之前，你需要记得创建用户账户。正如我们上面所解释的，测试运行器是使用测试数据库执行的，默认情况下，数据库中不包含用户。因此，在生产站点上有效的用户账户在测试条件下将无法工作。你需要创建用户作为测试套件的一部分--无论是手动创建（使用 Django 模型 API）还是使用测试夹具。记住，如果你想让你的测试用户有一个密码，你不能直接通过设置密码属性来设置用户的密码——你必须使用 set_password() 函数来存储一个正确的哈希密码。或者，你可以使用 create_user() 辅助方法来创建一个具有正确哈希密码的新用户。

force_login(user, backend=None)

如果你的网站使用了 Django 的 认证系统，你可以使用 force_login() 方法来模拟用户登录网站的效果。当测试需要用户登录，而用户如何登录的细节并不重要时，可以使用这个方法代替 login()。

与 login() 不同的是，这个方法跳过了认证和验证步骤：不活跃的用户（is_active=False）被允许登录，并且不需要提供用户凭证。

用户的 backend 属性将被设置为 backend 参数的值（应该是一个点分隔 Python 路径字符串），如果没有提供值，则设置为 settings.AUTHENTICATION_BACKENDS[0]。login() 调用的 authenticate() 函数通常会对用户进行注释。

这个方法比 login() 快，因为它绕过了昂贵的密码散列算法。另外，你也可以通过 在测试时使用较弱的哈希算法 来加快 login() 速度。

logout()

如果你的网站使用了 Django 的 认证系统，logout() 方法可以用来模拟用户注销网站的效果。

调用此方法后，测试客户端的所有 cookie 和会话数据都会被清除为默认值。随后的请求将看起来来自一个 AnonymousUser。

测试响应

get() 和 post() 方法都会返回一个 Response 对象，这个 Response 对象与 Django 视图返回的 HttpResponse 对象是 不 一样的；测试响应对象有一些额外的数据，对测试代码验证很有用。

具体来说，Response 对象具有以下属性：

class Response
client

用于发出请求并得到响应的测试客户端。

content

以字节字符串形式的响应主体。 这是视图或任何错误消息所呈现的最终页面内容。

context

模板 Context 实例，用于渲染产生响应内容的模板。

如果渲染的页面使用了多个模板，那么 context 将是一个按渲染顺序排列的 Context 对象列表。

Regardless of the number of templates used during rendering, you can retrieve context values using the [] operator. For example, the context variable name could be retrieved using:

>>> response = client.get("/foo/")
>>> response.context["name"]
'Arthur'

没有使用 Django 模板？

这个属性只有在使用 DjangoTemplates 后端时才会被填充。如果你正在使用其他模板引擎，在带有该属性的响应上，context_data 可能是一个合适的选择。

exc_info

一个由三个值组成的元组，它提供了关于在视图期间发生的未处理异常（如果有）的信息。

值是（type，value，traceback），与 Python 的 sys.exc_info() 返回的值相同。它们的含义是：

  • type：异常的类型。
  • value：异常的实例。
  • traceback：一个追溯对象，在最初发生异常的地方封装了调用堆栈。

如果没有发生异常，那么 exc_info 将是 None。

json(**kwargs)

The body of the response, parsed as JSON. Extra keyword arguments are passed to json.loads(). For example:

>>> response = client.get("/foo/")
>>> response.json()["name"]
'Arthur'

如果 Content-Type 头不是 "application/json"，那么在试图解析响应时将会出现一个 ValueError。

request

激发响应的请求数据。

wsgi_request

由生成响应的测试处理程序生成的 WSGIRequest 实例。

status_code

整数形式的响应 HTTP 状态。关于定义代码的完整列表，查看 IANA status code registry.

templates

用于渲染最终内容的 Template 实例列表，按渲染顺序排列。对于列表中的每个模板，如果模板是从文件中加载的，则使用 template.name 获得模板的文件名。（名字是一个字符串，如 'admin/index.html'。）

没有使用 Django 模板？

这个属性只有在使用 DjangoTemplates 后端时才会被填充。如果你使用的是其他模板引擎，并且你只需要渲染所用模板的名称，那么 template_name 可能是一个合适的选择。

resolver_match

响应的 ResolverMatch 的实例。你可以使用 func 属性，例如，验证服务于响应的视图：

# my_view here is a function based view.
self.assertEqual(response.resolver_match.func, my_view)

# Class-based views need to compare the view_class, as the
# functions generated by as_view() won't be equal.
self.assertIs(response.resolver_match.func.view_class, MyView)

如果找不到给定的 URL，访问这个属性会引发一个 Resolver404 异常。

和普通的响应一样，你也可以通过 HttpResponse.headers 访问头信息。例如，你可以使用 response.headers['Content-Type'] 来确定一个响应的内容类型。

例外

如果你把测试客户端指向一个会引发异常的视图，并且 Client.raise_request_exception 是 True，那么这个异常将在测试用例中可见。然后你可以使用标准的 try ... except 块或 assertRaises() 来测试异常。

测试客户端看不到的异常只有 Http404、PermissionDenied、SystemExit 和 SuspiciousOperation。Django 在内部捕获这些异常，并将其转换为相应的 HTTP 响应代码。在这些情况下，你可以在测试中检查 response.status_code。

如果 Client.raise_request_exception 为 False，测试客户端将返回一个 500 的响应，就像返回给浏览器一样。响应有属性 exc_info 来提供关于未处理的异常的信息。

持久状态

测试客户端是有状态的。如果一个响应返回一个 cookie，那么这个 cookie 将被存储在测试客户端，并与所有后续的 get() 和 post() 请求一起发送。

不遵循这些 cookie 的过期策略。如果你希望 cookie 过期，请手动删除它或创建一个新的 Client 实例（这将有效地删除所有 cookie）。

A test client has attributes that store persistent state information. You can access these properties as part of a test condition.

Client.cookies

一个 Python SimpleCookie 对象，包含所有客户端 cookie 的当前值。更多信息请参见 http.cookies 模块的文档。

Client.session

一个类似字典的对象，包含会话信息。详细内容请参见 会话文档。

要修改会话然后保存，必须先将其存储在一个变量中（因为每次访问该属性时都会创建一个新的 SessionStore）：

def test_something(self):
    session = self.client.session
    session["somekey"] = "test"
    session.save()

设置语言

在测试支持国际化和本地化的应用程序时，你可能想为测试客户端请求设置语言。这样做的方法取决于 LocaleMiddleware 是否启用。

如果启用了中间件，可以通过创建一个名为 LANGUAGE_COOKIE_NAME 的 cookie 来设置语言，其值为语言代码：。

from django.conf import settings


def test_language_using_cookie(self):
    self.client.cookies.load({settings.LANGUAGE_COOKIE_NAME: "fr"})
    response = self.client.get("/")
    self.assertEqual(response.content, b"Bienvenue sur mon site.")

或在请求中加入 Accept-Language HTTP 头：

def test_language_using_header(self):
    response = self.client.get("/", headers={"accept-language": "fr"})
    self.assertEqual(response.content, b"Bienvenue sur mon site.")

备注

When using these methods, ensure to reset the active language at the end of each test:

def tearDown(self):
    translation.activate(settings.LANGUAGE_CODE)

更多细节请参考 Django 如何发现语言偏好。

如果中间件没有启用，可以使用 translation.override() 设置活动语言：

from django.utils import translation


def test_language_using_override(self):
    with translation.override("fr"):
        response = self.client.get("/")
    self.assertEqual(response.content, b"Bienvenue sur mon site.")

更多细节见 显式设置语言。

例如

以下是使用测试客户端进行的单元测试：

import unittest
from django.test import Client


class SimpleTest(unittest.TestCase):
    def setUp(self):
        # Every test needs a client.
        self.client = Client()

    def test_details(self):
        # Issue a GET request.
        response = self.client.get("/customer/details/")

        # Check that the response is 200 OK.
        self.assertEqual(response.status_code, 200)

        # Check that the rendered context contains 5 customers.
        self.assertEqual(len(response.context["customers"]), 5)

参见

django.test.RequestFactory

提供的测试用例类

一般的 Python 单元测试类都会扩展一个基类 unittest.TestCase。Django 提供了这个基类的一些扩展。

Hierarchy of Django unit testing classes (TestCase subclasses)

Django 单元测试类的层次结构

你可以将一个普通的 unittest.TestCase 转换为任何一个子类：将你的测试基类从 unittest.TestCase 改为子类。所有标准的 Python 单元测试功能都将是可用的，并且它将被一些有用的附加功能所增强，如下面每节所述。

SimpleTestCase

class SimpleTestCase

unittest.TestCase 的一个子类，增加了以下功能：

如果你的测试进行任何数据库查询，请使用子类 TransactionTestCase 或 TestCase。

SimpleTestCase.databases

SimpleTestCase 默认不允许数据库查询。这有助于避免执行写查询而影响其他测试，因为每个 SimpleTestCase 测试不是在事务中运行的。如果你不关心这个问题，你可以通过在你的测试类上设置 databases 类属性为 '__all__' 来禁止这个行为。

警告

SimpleTestCase 和它的子类（如 TestCase）依靠 setUpClass() 和 tearDownClass() 来执行一些全类范围的初始化（如覆盖配置）。如果你需要覆盖这些方法，别忘了调用 super 实现：

class MyTestCase(TestCase):
    @classmethod
    def setUpClass(cls):
        super().setUpClass()
        ...

    @classmethod
    def tearDownClass(cls):
        ...
        super().tearDownClass()

如果在 setUpClass() 过程中出现异常，一定要考虑到 Python 的行为。如果发生这种情况，类中的测试和 tearDownClass() 都不会被运行。在 django.test.TestCase 的情况下，这将会泄露在 super() 中创建的事务，从而导致各种症状，包括在某些平台上的分段故障（在 macOS 上报告）。如果你想在 setUpClass() 中故意引发一个异常，如 unittest.SkipTest，一定要在调用 super() 之前进行，以避免这种情况。

TransactionTestCase

class TransactionTestCase

TransactionTestCase 继承自 SimpleTestCase 以增加一些数据库特有的功能：

Django 的 TestCase 类是 TransactionTestCase 的一个比较常用的子类，它利用数据库事务设施来加快在每次测试开始时将数据库重置到已知状态的过程。然而，这样做的一个后果是，有些数据库行为不能在 Django TestCase 类中进行测试。例如，你不能像使用 select_for_update() 时那样，测试一个代码块是否在一个事务中执行。在这些情况下，你应该使用 TransactionTestCase。

TransactionTestCase 和 TestCase 除了将数据库重设为已知状态的方式和测试与测试提交和回滚效果的相关代码外，其他都是相同的。

  • TransactionTestCase 在测试运行后，通过清空所有表来重置数据库。TransactionTestCase 可以调用提交和回滚，并观察这些调用对数据库的影响。
  • 另一方面，TestCase 在测试后不清空表。相反，它将测试代码包含在数据库事务中，在测试结束后回滚。这保证了测试结束时的回滚能将数据库恢复到初始状态。

警告

在不支持回滚的数据库上运行的 TestCase （例如 MyISAM 存储引擎的 MySQL ），则 TransactionTestCase 的所有实例，将在测试结束时回滚，删除测试数据库中的所有数据。

应用 不会看到他们的数据被重新加载；如果你需要这个功能（例如，第三方应用应该启用这个功能），你可以在 TestCase 中设置 serialized_rollback = True。

TestCase

class TestCase

这是 Django 中最常用的编写测试的类。它继承自 TransactionTestCase （以及扩展自 SimpleTestCase）。如果你的 Django 应用程序不使用数据库，就使用 SimpleTestCase。

此类：

  • 在两个嵌套的 atomic() 块中封装测试：一个用于整个类，一个用于每个测试。因此，如果你想测试一些特定的数据库事务行为，可以使用 TransactionTestCase。
  • 在每次测试结束时检查可延迟的数据库约束。

它还提供了另一种方法：

classmethod TestCase.setUpTestData()

上文所述的类级 atomic 块允许在类级创建初始数据，整个 TestCase 只需一次。与使用 setUp() 相比，这种技术允许更快的测试。

例如：

from django.test import TestCase


class MyTests(TestCase):
    @classmethod
    def setUpTestData(cls):
        # Set up data for the whole TestCase
        cls.foo = Foo.objects.create(bar="Test")
        ...

    def test1(self):
        # Some test using self.foo
        ...

    def test2(self):
        # Some other test using self.foo
        ...

请注意，如果测试是在没有事务支持的数据库上运行（例如，MyISAM 引擎的 MySQL），setUpTestData() 将在每次测试前被调用，从而降低了速度优势。

Objects assigned to class attributes in setUpTestData() must support creating deep copies with copy.deepcopy() in order to isolate them from alterations performed by each test methods.

classmethod TestCase.captureOnCommitCallbacks(using=DEFAULT_DB_ALIAS, execute=False)

返回一个为给定的数据库连接捕获 transaction.on_commit() 回调的上下文管理器。它返回一个列表，其中包含在退出上下文时，捕获的回调函数。从这个列表中，你可以对回调进行断言，或者调用它们来获得其副作用，模拟一个提交。

using 是数据库连接的别名，用于捕获回调。

如果 execute 是 True，并且如果没有发生异常，所有的回调将在上下文管理器退出时被调用。这模拟了在包裹的代码块之后的提交。

例如：

from django.core import mail
from django.test import TestCase


class ContactTests(TestCase):
    def test_post(self):
        with self.captureOnCommitCallbacks(execute=True) as callbacks:
            response = self.client.post(
                "/contact/",
                {"message": "I like your site"},
            )

        self.assertEqual(response.status_code, 200)
        self.assertEqual(len(callbacks), 1)
        self.assertEqual(len(mail.outbox), 1)
        self.assertEqual(mail.outbox[0].subject, "Contact Form")
        self.assertEqual(mail.outbox[0].body, "I like your site")

LiveServerTestCase

class LiveServerTestCase

LiveServerTestCase 和 TransactionTestCase 的功能基本相同，但多了一个功能：它在设置时在后台启动一个实时的 Django 服务器，并在关闭时将其关闭。这就允许使用 Django 虚拟客户端 以外的自动化测试客户端，例如，Selenium 客户端，在浏览器内执行一系列功能测试，并模拟真实用户的操作。

实时服务器在 localhost 上监听，并绑定到 0 号端口，0 号端口使用操作系统分配的一个空闲端口。在测试过程中可以用 self.live_server_url 访问服务器的 URL。

To demonstrate how to use LiveServerTestCase, let's write a Selenium test. First of all, you need to install the selenium package:

$ python -m pip install selenium

...\> py -m pip install selenium

然后，在你的应用程序的测试模块中添加一个基于 LiveServerTestCase 的测试（例如：myapp/tests.py）。在这个例子中，我们将假设你正在使用 staticfiles 应用，并且希望在执行测试时提供类似于我们在开发时使用 DEBUG=True 得到的静态文件，即不必使用 collectstatic 收集它们。我们将使用 StaticLiveServerTestCase 子类，它提供了这个功能。如果不需要的话，可以用 django.test.LiveServerTestCase 代替。

这个测试的代码可能如下：

from django.contrib.staticfiles.testing import StaticLiveServerTestCase
from selenium.webdriver.common.by import By
from selenium.webdriver.firefox.webdriver import WebDriver


class MySeleniumTests(StaticLiveServerTestCase):
    fixtures = ["user-data.json"]

    @classmethod
    def setUpClass(cls):
        super().setUpClass()
        cls.selenium = WebDriver()
        cls.selenium.implicitly_wait(10)

    @classmethod
    def tearDownClass(cls):
        cls.selenium.quit()
        super().tearDownClass()

    def test_login(self):
        self.selenium.get(f"{self.live_server_url}/login/")
        username_input = self.selenium.find_element(By.NAME, "username")
        username_input.send_keys("myuser")
        password_input = self.selenium.find_element(By.NAME, "password")
        password_input.send_keys("secret")
        self.selenium.find_element(By.XPATH, '//input[@value="Log in"]').click()

最后，你可以按以下方式进行测试：

$ ./manage.py test myapp.tests.MySeleniumTests.test_login

...\> manage.py test myapp.tests.MySeleniumTests.test_login

这个例子会自动打开 Firefox，然后进入登录页面，输入凭证并按“登录”按钮。Selenium 提供了其他驱动程序，以防你没有安装 Firefox 或希望使用其他浏览器。上面的例子只是 Selenium 客户端能做的一小部分，更多细节请查看 full reference。

备注

当使用内存 SQLite 数据库运行测试时，同一个数据库连接将由两个线程并行共享：运行实时服务器的线程和运行测试用例的线程。要防止两个线程通过这个共享连接同时进行数据库查询，因为这有时可能会随机导致测试失败。所以你需要确保两个线程不会同时访问数据库。特别是，这意味着在某些情况下（例如，刚刚点击一个链接或提交一个表单之后），你可能需要检查 Selenium 是否收到了响应，并且在继续执行进一步的测试之前，检查下一个页面是否被加载。例如，让 Selenium 等待直到在响应中找到 <body> HTML 标签（需要 Selenium > 2.13）：

def test_login(self):
    from selenium.webdriver.support.wait import WebDriverWait

    timeout = 2
    ...
    self.selenium.find_element(By.XPATH, '//input[@value="Log in"]').click()
    # Wait until the response is received
    WebDriverWait(self.selenium, timeout).until(
        lambda driver: driver.find_element(By.TAG_NAME, "body")
    )

The tricky thing here is that there's really no such thing as a "page load," especially in modern web apps that generate HTML dynamically after the server generates the initial document. So, checking for the presence of <body> in the response might not necessarily be appropriate for all use cases. Please refer to the Selenium FAQ and Selenium documentation for more information.

测试用例特性

默认测试客户端

SimpleTestCase.client

django.test.*TestCase 实例中的每个测试用例都可以访问一个 Django 测试客户端的实例。这个客户端可以用 self.client 来访问。这个客户端在每个测试中都会被重新创建，所以你不必担心状态（比如 cookie）会从一个测试转移到另一个测试中。

这意味着，不必每个测试中实例化一个 Client：

import unittest
from django.test import Client


class SimpleTest(unittest.TestCase):
    def test_details(self):
        client = Client()
        response = client.get("/customer/details/")
        self.assertEqual(response.status_code, 200)

    def test_index(self):
        client = Client()
        response = client.get("/customer/index/")
        self.assertEqual(response.status_code, 200)

......你可以引用 self.client，像这样：

from django.test import TestCase


class SimpleTest(TestCase):
    def test_details(self):
        response = self.client.get("/customer/details/")
        self.assertEqual(response.status_code, 200)

    def test_index(self):
        response = self.client.get("/customer/index/")
        self.assertEqual(response.status_code, 200)

自定义测试客户端

SimpleTestCase.client_class

如果你想使用不同的 Client 类（例如，一个具有自定义行为的子类），使用 client_class 类属性：

from django.test import Client, TestCase


class MyTestClient(Client):
    # Specialized methods for your environment
    ...


class MyTest(TestCase):
    client_class = MyTestClient

    def test_my_stuff(self):
        # Here self.client is an instance of MyTestClient...
        call_some_test_code()

辅助工具加载

TransactionTestCase.fixtures

A test case for a database-backed website isn't much use if there isn't any data in the database. Tests are more readable and it's more maintainable to create objects using the ORM, for example in TestCase.setUpTestData(), however, you can also use fixtures.

辅助工具是 Django 知道如何导入数据库的数据集合。例如，如果你的网站有用户账户，你可能会设置一个假用户账户的辅助工具，以便在测试时填充你的数据库。

创建辅助工具的最直接方法是使用 manage.py dumpdata 命令。这假定你已经在你的数据库中拥有一些数据。参见 dumpdata 文档 了解更多细节。

一旦你创建了一个辅助工具，并把它放在你的 INSTALLED_APPS 中的 fixtures 目录下，你就可以通过在你的 django.test.TestCase 子类上指定一个 fixtures 类属性来在你的单元测试中使用它。

from django.test import TestCase
from myapp.models import Animal


class AnimalTestCase(TestCase):
    fixtures = ["mammals.json", "birds"]

    def setUp(self):
        # Test definitions as before.
        call_setup_methods()

    def test_fluffy_animals(self):
        # A test that uses the fixtures.
        call_some_test_code()

具体来说，将发生以下情况：

  • 在每次测试开始时，在 setUp() 运行之前，Django 会对数据库进行刷新，将数据库直接返回到 migrate 被调用后的状态。
  • Then, all the named fixtures are installed. In this example, Django will install any JSON fixture named mammals, followed by any fixture named birds. See the 辅助工具 topic for more details on defining and installing fixtures.

出于性能方面的考虑， TestCase 在 setUpTestData() 之前为整个测试类加载一次辅助工具，而不是在每次测试之前加载，并且它在每次测试之前使用事务来清理数据库。在任何情况下，你都可以确定一个测试的结果不会受到另一个测试或测试执行顺序的影响。

默认情况下，辅助工具只被加载到 default 数据库中。如果你使用多个数据库并且设置了 TransactionTestCase.databases，辅助工具将被加载到所有指定的数据库中。

URLconf 配置

如果你的应用程序提供了视图，你可能希望包含使用测试客户端来行使这些视图的测试。然而，最终用户可以自由地在他们选择的任何 URL 上部署应用程序中的视图。这意味着你的测试不能依赖于你的视图将在特定的 URL 上可用这一事实。用 @override_settings(ROOT_URLCONF=...) 来装饰你的测试类或测试方法的 URLconf 配置。

多数据库支持

TransactionTestCase.databases

Django 设置了一个测试数据库，对应于你设置中的 DATABASES 定义的并且至少有一个测试引用了 databases 的每个数据库。

然而，运行一个 Django TestCase 所花费的时间很大一部分是被调用 flush 所消耗的，它确保了你在每次测试运行开始时有一个干净的数据库。如果你有多个数据库，就需要多次刷新（每个数据库一个），这可能是一个耗时的活动——特别是当你的测试不需要测试多数据库活动时。

作为一种优化，Django 只在每次测试运行开始时刷新 default 数据库。如果你的设置包含多个数据库，并且你的测试要求每个数据库都是干净的，你可以使用测试套件上的 databases 属性来请求额外的数据库被刷新。

例如：

class TestMyViews(TransactionTestCase):
    databases = {"default", "other"}

    def test_index_page_view(self):
        call_some_test_code()

这个测试用例将在运行 test_index_page_view 之前刷新 default 和 other 测试数据库。你也可以使用 '__all__' 来指定所有的测试数据库必须被刷新。

databases 标志也控制 TransactionTestCase.fixtures 被加载到哪些数据库。默认情况下，辅助工具只被加载到 default 数据库中。

对不在 databases 中的数据库的查询将给出断言错误，以防止测试之间的状态泄露。

TestCase.databases

默认情况下，在 TestCase 期间，仅将 default 数据库包装在事务中，并且尝试查询其他数据库将导致断言错误，以防止测试之间的状态泄漏。

在测试类上使用 databases 类属性来请求对非 default 数据库进行事务包装。

例如：

class OtherDBTests(TestCase):
    databases = {"other"}

    def test_other_db_query(self):
        ...

这个测试只允许对 other 数据库进行查询。就像 SimpleTestCase.databases 和 TransactionTestCase.databases 一样，'__all__' 常量可以用来指定测试应该允许对所有数据库进行查询。

覆盖配置

警告

使用下面的函数可以临时改变测试中的设置值。不要直接操作 django.conf.settings，因为 Django 不会在这种操作后恢复原始值。

SimpleTestCase.settings()

为了测试的目的，经常需要临时改变一个设置，并在运行测试代码后恢复到原始值。对于这个用例，Django 提供了一个标准的 Python 上下文管理器（见 PEP 343），叫做 settings()，可以这样使用：

from django.test import TestCase


class LoginTestCase(TestCase):
    def test_login(self):
        # First check for the default behavior
        response = self.client.get("/sekrit/")
        self.assertRedirects(response, "/accounts/login/?next=/sekrit/")

        # Then override the LOGIN_URL setting
        with self.settings(LOGIN_URL="/other/login/"):
            response = self.client.get("/sekrit/")
            self.assertRedirects(response, "/other/login/?next=/sekrit/")

This example will override the LOGIN_URL setting for the code in the with block and reset its value to the previous state afterward.

SimpleTestCase.modify_settings()

重新定义包含一系列值的设置可能会很麻烦。在实践中，添加或删除值通常是足够的。Django 提供了 modify_settings() 上下文管理器，以方便更改设置：

from django.test import TestCase


class MiddlewareTestCase(TestCase):
    def test_cache_middleware(self):
        with self.modify_settings(
            MIDDLEWARE={
                "append": "django.middleware.cache.FetchFromCacheMiddleware",
                "prepend": "django.middleware.cache.UpdateCacheMiddleware",
                "remove": [
                    "django.contrib.sessions.middleware.SessionMiddleware",
                    "django.contrib.auth.middleware.AuthenticationMiddleware",
                    "django.contrib.messages.middleware.MessageMiddleware",
                ],
            }
        ):
            response = self.client.get("/")
            # ...

对于每个操作，你可以提供一个值的列表或一个字符串。当值已经存在于列表中时，append 和 prepend 没有效果；当值不存在时，remove 也没有效果。

override_settings(**kwargs)

如果你想覆盖一个测试方法的设置，Django 提供了 override_settings() 装饰器（见 PEP 318）。它的用法是这样的：

from django.test import TestCase, override_settings


class LoginTestCase(TestCase):
    @override_settings(LOGIN_URL="/other/login/")
    def test_login(self):
        response = self.client.get("/sekrit/")
        self.assertRedirects(response, "/other/login/?next=/sekrit/")

装饰器也可以应用于 TestCase 类：

from django.test import TestCase, override_settings


@override_settings(LOGIN_URL="/other/login/")
class LoginTestCase(TestCase):
    def test_login(self):
        response = self.client.get("/sekrit/")
        self.assertRedirects(response, "/other/login/?next=/sekrit/")
modify_settings(*args, **kwargs)

同样，Django 也提供了 modify_settings() 装饰器：

from django.test import TestCase, modify_settings


class MiddlewareTestCase(TestCase):
    @modify_settings(
        MIDDLEWARE={
            "append": "django.middleware.cache.FetchFromCacheMiddleware",
            "prepend": "django.middleware.cache.UpdateCacheMiddleware",
        }
    )
    def test_cache_middleware(self):
        response = self.client.get("/")
        # ...

此装饰器也可以应用于测试用例类：

from django.test import TestCase, modify_settings


@modify_settings(
    MIDDLEWARE={
        "append": "django.middleware.cache.FetchFromCacheMiddleware",
        "prepend": "django.middleware.cache.UpdateCacheMiddleware",
    }
)
class MiddlewareTestCase(TestCase):
    def test_cache_middleware(self):
        response = self.client.get("/")
        # ...

备注

当给定一个类时，这些装饰器直接修改该类并返回它，它们不会创建并返回一个修改后的副本。因此，如果你试图调整上面的例子，将返回值分配给一个不同于 LoginTestCase 或 MiddlewareTestCase 的名称，你可能会惊讶地发现，原来的测试用例类仍然同样受到装饰器的影响。对于一个给定的类，modify_settings() 总是应用在 override_settings() 之后。

警告

配置文件中包含了一些设置，这些设置只有在 Django 内部初始化时才会被使用。如果你用 override_settings 改变它们，当你通过``django.conf.settings`` 模块访问会得到被改变的配置。但是，Django 的内部程序访问它的方式是不同的。实际上，使用 override_settings() 或者 modify_settings() 来使用这些设置，很可能达不到你预期的效果。

我们不建议改变 DATABASES 的设置。改变 CACHES 的设置是可能的，但如果你使用的是内部缓存，比如 django.contrib.session，就有点棘手。例如，你必须在使用缓存会话并覆盖 CACHES 的测试中重新初始化会话后端。

最后，避免将你的配置别名为模块级常量，因为 override_settings() 不会对这些值起作用，它们只在第一次导入模块时才被评估。

你也可以在配置被覆盖后，通过删除配置来模拟没有配置，比如这样：

@override_settings()
def test_something(self):
    del settings.LOGIN_URL
    ...

覆盖配置时，请确保处理你的应用代码使用即使保留配置更改也能保持状态的缓存或类似功能的情况。Django 提供了 django.test.signals.setting_changed 信号，让你在设置被改变时，可以注册回调来清理和重置状态。

Django 自己也使用这个信号来重置各种数据。

覆盖配置 数据重置
USE_TZ，TIME_ZONE 数据库时区
TEMPLATES 模板引擎
SERIALIZATION_MODULES 序列化器缓存
LOCALE_PATHS，LANGUAGE_CODE 默认翻译和加载的翻译
DEFAULT_FILE_STORAGE, STATICFILES_STORAGE, STATIC_ROOT, STATIC_URL, STORAGES Storages configuration

Isolating apps

utils.isolate_apps(*app_labels, attr_name=None, kwarg_name=None)

Registers the models defined within a wrapped context into their own isolated apps registry. This functionality is useful when creating model classes for tests, as the classes will be cleanly deleted afterward, and there is no risk of name collisions.

The app labels which the isolated registry should contain must be passed as individual arguments. You can use isolate_apps() as a decorator or a context manager. For example:

from django.db import models
from django.test import SimpleTestCase
from django.test.utils import isolate_apps


class MyModelTests(SimpleTestCase):
    @isolate_apps("app_label")
    def test_model_definition(self):
        class TestModel(models.Model):
            pass

        ...

… or:

with isolate_apps("app_label"):

    class TestModel(models.Model):
        pass

    ...

The decorator form can also be applied to classes.

Two optional keyword arguments can be specified:

  • attr_name: attribute assigned the isolated registry if used as a class decorator.
  • kwarg_name: keyword argument passing the isolated registry if used as a function decorator.

The temporary Apps instance used to isolate model registration can be retrieved as an attribute when used as a class decorator by using the attr_name parameter:

@isolate_apps("app_label", attr_name="apps")
class TestModelDefinition(SimpleTestCase):
    def test_model_definition(self):
        class TestModel(models.Model):
            pass

        self.assertIs(self.apps.get_model("app_label", "TestModel"), TestModel)

… or alternatively as an argument on the test method when used as a method decorator by using the kwarg_name parameter:

class TestModelDefinition(SimpleTestCase):
    @isolate_apps("app_label", kwarg_name="apps")
    def test_model_definition(self, apps):
        class TestModel(models.Model):
            pass

        self.assertIs(apps.get_model("app_label", "TestModel"), TestModel)

清空测试发件箱

如果你使用任何 Django 的自定义 TestCase 类，测试运行器将在每个测试用例开始时清除测试邮件发件箱的内容。

关于测试期间电子邮件服务的更多细节，请参见下面的 Email services。

断言

As Python's normal unittest.TestCase class implements assertion methods such as assertTrue() and assertEqual(), Django's custom TestCase class provides a number of custom assertion methods that are useful for testing web applications:

大多数这些断言方法给出的失败信息可以用 msg_prefix 参数自定义。这个字符串将被加在断言产生的任何失败信息的前面。这允许你提供额外的细节，以帮助你确定测试套件中失败的位置和原因。

SimpleTestCase.assertRaisesMessage(expected_exception, expected_message, callable, *args, **kwargs)
SimpleTestCase.assertRaisesMessage(expected_exception, expected_message)

断言执行 callable 引起 expected_exception，并且在异常信息中发现 expected_message。任何其他结果都会被报告为失败。它是 unittest.TestCase.assertRaisesRegex() 的简单版本，不同的是 expected_message 不作为正则表达式处理。

如果只给了 expected_exception 和 expected_message 参数，则返回一个上下文管理器，以便被测试的代码可以内联而不是作为一个函数来写：

with self.assertRaisesMessage(ValueError, "invalid literal for int()"):
    int("a")
SimpleTestCase.assertWarnsMessage(expected_warning, expected_message, callable, *args, **kwargs)
SimpleTestCase.assertWarnsMessage(expected_warning, expected_message)

类似于 SimpleTestCase.assertRaisesMessage()，但是 assertWarnsRegex() 代替 assertRaisesRegex()。

SimpleTestCase.assertFieldOutput(fieldclass, valid, invalid, field_args=None, field_kwargs=None, empty_value='')

断言表单字段在不同的输入情况下表现正确。

参数:
  • fieldclass -- 待测试字段的类。
  • valid -- 一个字典，将有效输入映射到它们的预期干净值。
  • invalid -- 一个字典，将无效输入映射到一个或多个引发的错误信息
  • field_args -- 传递给实例化字段的 args。
  • field_kwargs -- 传递给实例化字段的 kwargs。
  • empty_value -- empty_values 中输入的预期干净输出。

例如，以下代码测试 EmailField 接受 a@a.com 作为有效的电子邮件地址，但拒绝 aaa，并给出合理的错误信息：

self.assertFieldOutput(
    EmailField, {"a@a.com": "a@a.com"}, {"aaa": ["Enter a valid email address."]}
)
SimpleTestCase.assertFormError(form, field, errors, msg_prefix='')

Asserts that a field on a form raises the provided list of errors.

form is a Form instance. The form must be bound but not necessarily validated (assertFormError() will automatically call full_clean() on the form).

field is the name of the field on the form to check. To check the form's non-field errors, use field=None.

errors is a list of all the error strings that the field is expected to have. You can also pass a single error string if you only expect one error which means that errors='error message' is the same as errors=['error message'].

Changed in Django 4.1:

In older versions, using an empty error list with assertFormError() would always pass, regardless of whether the field had any errors or not. Starting from Django 4.1, using errors=[] will only pass if the field actually has no errors.

Django 4.1 also changed the behavior of assertFormError() when a field has multiple errors. In older versions, if a field had multiple errors and you checked for only some of them, the test would pass. Starting from Django 4.1, the error list must be an exact match to the field's actual errors.

4.1 版后已移除: Support for passing a response object and a form name to assertFormError() is deprecated and will be removed in Django 5.0. Use the form instance directly instead.

SimpleTestCase.assertFormSetError(formset, form_index, field, errors, msg_prefix='')

断言 formset 在渲染时，会引发所提供的错误列表。

formset is a FormSet instance. The formset must be bound but not necessarily validated (assertFormSetError() will automatically call the full_clean() on the formset).

form_index is the number of the form within the FormSet (starting from 0). Use form_index=None to check the formset's non-form errors, i.e. the errors you get when calling formset.non_form_errors(). In that case you must also use field=None.

field and errors have the same meaning as the parameters to assertFormError().

4.1 版后已移除: Support for passing a response object and a formset name to assertFormSetError() is deprecated and will be removed in Django 5.0. Use the formset instance directly instead.

4.2 版后已移除: The assertFormsetError() assertion method is deprecated. Use assertFormSetError() instead.

SimpleTestCase.assertContains(response, text, count=None, status_code=200, msg_prefix='', html=False)

Asserts that a response produced the given status_code and that text appears in its content. If count is provided, text must occur exactly count times in the response.

将 html 设置为 True，将 text 作为 HTML 处理。与响应内容的比较将基于 HTML 语义，而不是逐个字符的平等。在大多数情况下，空格会被忽略，属性排序并不重要。详见 assertHTMLEqual()。

SimpleTestCase.assertNotContains(response, text, status_code=200, msg_prefix='', html=False)

Asserts that a response produced the given status_code and that text does not appear in its content.

将 html 设置为 True，将 text 作为 HTML 处理。与响应内容的比较将基于 HTML 语义，而不是逐个字符的平等。在大多数情况下，空格会被忽略，属性排序并不重要。详见 assertHTMLEqual()。

SimpleTestCase.assertTemplateUsed(response, template_name, msg_prefix='', count=None)

断言给定名称的模板被用于渲染响应。

response must be a response instance returned by the test client.

template_name``应当是一个字符串，如'admin/index.html'``。

The count argument is an integer indicating the number of times the template should be rendered. Default is None, meaning that the template should be rendered one or more times.

你可以把它作为一个上下文管理器，比如：

with self.assertTemplateUsed("index.html"):
    render_to_string("index.html")
with self.assertTemplateUsed(template_name="index.html"):
    render_to_string("index.html")
SimpleTestCase.assertTemplateNotUsed(response, template_name, msg_prefix='')

断言给定名称的模板在渲染响应时 没有 被使用。

你可以用 assertTemplateUsed() 一样的方式将其作为上下文管理器。

SimpleTestCase.assertURLEqual(url1, url2, msg_prefix='')

断言两个 URL 是相同的，忽略查询字符串参数的顺序，但同名参数除外。例如，/path/?x=1&y=2 等于 /path/?y=2&x=1，但 /path/?a=1&a=2 不等于 /path/?a=2&a=1。

SimpleTestCase.assertRedirects(response, expected_url, status_code=302, target_status_code=200, msg_prefix='', fetch_redirect_response=True)

Asserts that the response returned a status_code redirect status, redirected to expected_url (including any GET data), and that the final page was received with target_status_code.

如果你的请求使用了 follow 参数，expected_url 和 target_status_code 将是重定向链最后一点的网址和状态码。

如果 fetch_redirect_response 为 False，则最终页面不会被加载。由于测试客户端不能获取外部 URL，所以如果 expected_url 不是 Django 应用的一部分，这一点就特别有用。

在两个 URL 之间进行比较时，可以正确处理协议。如果在我们被重定向到的位置没有指定任何协议，则使用原始请求的协议。如果存在，expected_url 中的协议就是用来进行比较的。

SimpleTestCase.assertHTMLEqual(html1, html2, msg=None)

断言字符串 html1 和 html2 相等。比较是基于 HTML 语义的。比较时考虑到以下因素：

  • HTML 标签前后的空白会被忽略。
  • 所有类型的空白都被认为是等价的。
  • 所有打开的标签都是隐式关闭的，例如当周围的标签关闭或 HTML 文档结束时。
  • 空标签相当于其自动闭合版。
  • HTML 元素的属性排序并不重要。
  • Boolean attributes (like checked) without an argument are equal to attributes that equal in name and value (see the examples).
  • 引用同一字符的文本、字符引用和实体引用是等价的。

下面的例子是有效的测试，并且没有引起任何 AssertionError:

self.assertHTMLEqual(
    "<p>Hello <b>&#x27;world&#x27;!</p>",
    """<p>
        Hello   <b>&#39;world&#39;! </b>
    </p>""",
)
self.assertHTMLEqual(
    '<input type="checkbox" checked="checked" id="id_accept_terms" />',
    '<input id="id_accept_terms" type="checkbox" checked>',
)

html1 和 html2 必须包含 HTML。如果其中一个不能被解析，将产生一个 AssertionError。

错误时的输出可以用 msg 参数自定义。

SimpleTestCase.assertHTMLNotEqual(html1, html2, msg=None)

断言字符串 html1 和 html2 不 相等。比较是基于 HTML 语义的。详见 assertHTMLEqual()。

html1 和 html2 必须包含 HTML。如果其中一个不能被解析，将产生一个 AssertionError。

错误时的输出可以用 msg 参数自定义。

SimpleTestCase.assertXMLEqual(xml1, xml2, msg=None)

断言字符串 xml1 和 xml2 相等。比较是基于 XML 语义的。与 assertHTMLEqual() 类似，比较是在解析内容上进行的，因此只考虑语义差异，而不是语法差异。当任何参数中传递了无效的 XML 时，即使两个字符串相同，也总是会引发一个 AssertionError。

忽略 XML 声明、文档类型、处理指令和注释。只有根元素和它的子元素被比较。

错误时的输出可以用 msg 参数自定义。

SimpleTestCase.assertXMLNotEqual(xml1, xml2, msg=None)

断言字符串 xml1 和 xml2 不 相等。比较是基于 XML 语义的，参见 assertXMLEqual()。

错误时的输出可以用 msg 参数自定义。

SimpleTestCase.assertInHTML(needle, haystack, count=None, msg_prefix='')

Asserts that the HTML fragment needle is contained in the haystack once.

如果指定了 count 整数参数，则将严格核查 needle 的出现次数。

在大多数情况下，空白是被忽略的，属性排序并不重要。参见 assertHTMLEqual() 以了解更多细节。

SimpleTestCase.assertJSONEqual(raw, expected_data, msg=None)

断言 JSON 片段 raw 和 expected_data 相等。通常的 JSON 非显性空格规则适用，因为重量级是委托给 json 库的。

错误时的输出可以用 msg 参数自定义。

SimpleTestCase.assertJSONNotEqual(raw, expected_data, msg=None)

断言 JSON 片段 raw 和 expected_data 不 相等。详见 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 参数自定义。

4.2 版后已移除: The assertQuerysetEqual() assertion method is deprecated. Use assertQuerySetEqual() instead.

TransactionTestCase.assertNumQueries(num, func, *args, **kwargs)

断言当 func 与 *args 和 **kwargs 一起调用时，会执行 num 次数据库查询。

如果 kwargs 中存在 "using" 键，则使用该键作为数据库别名，以检查查询次数：

self.assertNumQueries(7, 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' 来标注。

然后你可以选择要运行的测试。例如，只运行快速测试：

$ ./manage.py test --tag=fast

...\> manage.py test --tag=fast

或者运行快速测试和核心测试（即使它很慢）：

$ ./manage.py test --tag=fast --tag=core

...\> manage.py test --tag=fast --tag=core

你也可以通过标签来排除测试。如果要运行不慢的核心测试：

$ ./manage.py test --tag=core --exclude-tag=slow

...\> manage.py test --tag=core --exclude-tag=slow

test --exclud-tag 优先于 test --tag，所以如果一个测试有两个标签，你选择了其中一个而排除了另一个，测试就不会被运行。

测试异步代码

如果你只是想测试异步视图的输出，标准测试客户端将在自己的异步循环中运行它们，而不需要你做任何额外的工作。

但是，如果你想为 Django 项目编写完全异步的测试，你需要考虑到几个问题。

首先，你的测试必须是测试类上的 async def 方法（为了给它们一个异步的上下文）。Django 会自动检测到任何 async def 的测试，并将它们封装在自己的事件循环中运行。

如果你从一个异步函数进行测试，你也必须使用异步测试客户端。这在任何测试中都可以作为 django.test.AsyncClient 或 self.async_client 使用。

class AsyncClient(enforce_csrf_checks=False, raise_request_exception=True, *, headers=None, **defaults)

AsyncClient 具有与同步（普通）测试客户端相同的方法和签名，但有两个例外：

  • In the initialization, arbitrary keyword arguments in defaults are added directly into the ASGI scope.

  • 不支持 follow 参数。

  • Headers passed as extra keyword arguments should not have the HTTP_ prefix required by the synchronous client (see Client.get()). For example, here is how to set an HTTP Accept header:

    >>> c = AsyncClient()
>>> c.get("/customers/details/", {"name": "fred", "age": 7}, ACCEPT="application/json")
Changed in Django 4.2:

The headers parameter was added.

使用 AsyncClient 任何提出请求的方法都必须被等待：

async def test_my_thing(self):
    response = await self.async_client.get("/some-url/")
    self.assertEqual(response.status_code, 200)

异步客户端也可以调用同步视图；它通过 Django 的 异步请求路径 运行，它支持这两种方式。任何通过 AsyncClient 调用的视图都会得到一个 ASGIRequest 对象作为它的 request，而不是普通客户端创建的 WSGIRequest。

警告

如果你使用的是测试装饰器，它们必须是异步兼容的，以确保它们正确工作。Django 内置的装饰器会正常工作，但第三方的装饰器可能会出现无法执行的情况（它们会“包装”执行流程中错误的部分，而不是你的测试）。

如果你需要使用这些装饰器，那么你应该用 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 的邮件功能 发送电子邮件，你可能不想每次使用该视图运行测试时都发送电子邮件。出于这个原因，Django 的测试运行器会自动将所有 Django 发送的邮件重定向到一个虚拟的发件箱。这让你可以测试发送邮件的每一个方面——从发送邮件的数量到每封邮件的内容——而不用实际发送邮件。

测试运行器通过透明的将正常的邮件后端替换为测试后端来实现。（别担心——这对 Django 之外的其他邮件发送器没有影响，比如你机器的邮件服务器，如果你正在运行一个的话。）

django.core.mail.outbox

在测试运行过程中，每一封发出的邮件都会保存在 django.core.mail.outbox 中。这是所有已经发送的 EmailMessage 实例的列表。 outbox 属性是一个特殊的属性，只有在使用 locmem 邮件后端时才会创建。它通常不作为 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")

正如 之前，在 Django *TestCase 中的每个测试开始时，测试发件箱都会被清空。要手动清空发件箱，将空列表分配给 mail.outbox：

from django.core import mail

# Empty the test outbox
mail.outbox = []

管理命令

管理命令可以用 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", stdout=out)
        self.assertIn("Expected output", out.getvalue())

忽略测试

unittest 库提供了 @skipIf 和 @skipUnless 装饰器，允许你跳过测试，如果你事先知道这些测试在某些条件下会失败。

例如，如果你的测试需要一个特定的可选库才能成功，你可以用 @skipIf 来装饰测试用例。然后，测试运行器将报告测试没有被执行以及原因，而不是测试失败或完全省略测试。

为了补充这些测试跳过行为，Django 提供了两个额外的跳过装饰器。这些装饰器不是测试一个通用的布尔值，而是检查数据库的能力，如果数据库不支持一个特定的命名特性，则跳过测试。

装饰器使用一个字符串标识符来描述数据库特征。这个字符串对应于数据库连接特征类的属性。参见 django.db.backends.base.features.BaseDatabaseFeatures 类 以获得可作为跳过测试基础的数据库特征的完整列表。

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
« previous | up | next »