Getting Help

el
en
es
fr
id
it
ja
ko
pl
pt-br
语言： zh-hans

2.0
2.1
2.2
3.0
3.1
3.2
4.0
4.1
5.0
5.1
dev
文档版本： 4.2

测试工具¶

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

测试客户端¶

测试客户端是一个 Python 类，它充当虚拟的网络浏览器，允许你以编程方式测试你的视图并与你的基于 Django 的应用程序进行交互。

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

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

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

使用 Django 的测试客户端来确定要渲染的模板正确，并且模板已传递了正确的上下文数据。
使用 RequestFactory 直接测试视图函数，绕过路由和中间件层。
使用像 Selenium 这样的浏览器框架来测试 渲染的 HTML 和网页的行为，即 JavaScript 功能。Django 还为这些框架提供了特殊的支持；请参阅 LiveServerTestCase 部分以获取更多详细信息。

一个全面的测试套件应该使用所有这些测试类型的组合。

概述和一个简单的例子¶

要使用测试客户端，请实例化 django.test.Client 并获取 web 页面：

>>> 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。

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

测试客户端 不需要 web 服务器正在运行。事实上，它甚至可以在没有任何 web 服务器运行的情况下正常工作！这是因为它避免了 HTTP 的开销，直接与 Django 框架交互。这有助于快速运行单元测试。
在检索页面时，请记住指定 URL 的路径，而不是整个域名。例如，这是正确的：
```
>>> c.get("/login/")
```
这是不正确的：
```
>>> c.get("https://www.example.com/login/")
```
测试客户端无法获取不由你的 Django 项目提供支持的网页。如果你需要获取其他网页，使用 Python 标准库模块如 urllib。
为了解析 URL，测试客户端使用你的 ROOT_URLCONF 配置指向的任何 URLconf。
虽然上面的例子可以在 Python 交互式解释器中工作，但是测试客户端的一些功能，尤其是与模板相关的功能，只有在 测试运行时 才可以使用。

原因是 Django 的测试运行器为了确定哪个模板被给定的视图加载，执行了一点黑魔法。这个黑魔法（本质上是内存中 Django 模板系统的补丁）只发生在测试运行期间。
默认情况下，测试客户端将禁用站点执行的任何 CSRF 检查。

如果出于某种原因，你想要测试客户端执行 CSRF 检查，你可以创建一个强制执行 CSRF 检查的测试客户端实例。要做到这一点，构建客户端时传入 enforce_csrf_checks 参数：
```
>>> 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)¶

一个用于测试的 HTTP 客户端。接受多个参数，可以自定义其行为。

headers 允许你指定默认头信息，这些头信息将与每个请求一起发送。例如，要设置一个 User-Agent 头信息：

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

在 **defaults 中的任意关键字参数设置了 WSGI environ 变量。例如，要设置脚本名称：

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

备注

以 HTTP_ 前缀开头的关键字参数将被设置为头信息，但为了可读性，应该优先使用 headers 参数。

传递给 get()、post() 等的 headers 和 extra 关键字参数的值优先于传递给类构造函数的默认值。

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

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

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

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

Changed in Django 4.2:

已添加 headers 参数。

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

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

data 字典中的键值对用于创建 GET 数据载荷。例如：

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

...将导致等同于以下 GET 请求的评估：

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

headers 参数可用于指定要在请求中发送的头信息。例如：

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

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

任意关键字参数设置了 WSGI environ 变量。例如，设置脚本名称的头信息：

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

如果你已经有了 URL 编码形式的 GET 参数，你可以使用该编码而不是使用 data 参数。例如，之前的 GET 请求也可以这样表示：

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

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

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

如果你有一个 URL /redirect_me/，它重定向到 /next/，然后重定向到 /final/，你会看到以下内容：

>>> 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:

已添加 headers 参数。

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

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

data 字典中的键值对用于提交 POST 数据。例如：

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

...将导致对该 URL 发起 POST 请求的评估：

/login/

...使用以下 POST 数据：

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"]}

提交文件是一个特殊情况。要提交文件，你只需提供文件字段名称作为键，以及要上传的文件的文件句柄作为值。例如，如果你的表单有字段 name 和 attachment，后者是一个 FileField：

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

你也可以提供任何类似文件的对象（例如：StringIO 或 BytesIO）作为文件句柄。如果你要上传到一个 ImageField，这个对象需要一个 name 属性，以通过 validate_image_file_extension 验证器。例如：

>>> 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 （读取二进制）模式打开文件。

headers 和 extra 参数的行为与 Client.get() 相同。

如果你使用 POST 请求的 URL 包含编码的参数，这些参数将在 request.GET 数据中可用。例如，如果你发出请求：

>>> 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:

已添加 headers 参数。

head(path, data=None, follow=False, secure=False, *, headers=None, **extra)¶: 对提供的 path 发起 HEAD 请求并返回一个 Response 对象。这个方法的工作方式与 Client.get() 相同，包括 follow、secure、headers 和 extra 参数，只是它不返回消息主体。

Changed in Django 4.2:
已添加 headers 参数。

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

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

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