获取帮助

1.8
1.10
1.11
2.0
2.1
2.2
3.0
3.1
3.2
4.0
4.1
4.2
5.0
开发人员
文档版本：5.1

测试工具¶

Django 提供了一套在编写测试时非常有用的工具。

测试客户端¶

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

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

模拟对 URL 的 GET 和 POST 请求并观察响应 - 从低级别的 HTTP（结果头和状态代码）到页面内容。
查看重定向链（如果有）并检查每一步的 URL 和状态代码。
测试给定请求是否由给定的 Django 模板呈现，并且模板上下文包含某些值。

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

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

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

概述和快速示例¶

要使用测试客户端，请实例化django.test.Client 并检索网页

>>> 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, query_params=None, **defaults)[source]¶

一个测试 HTTP 客户端。接受几个可以自定义行为的参数。

headers 允许您指定将在每个请求中发送的默认标头。例如，要设置User-Agent 标头

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

query_params 允许您指定将在每个请求中设置的默认查询字符串。

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

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

注意

以HTTP_ 前缀开头的关键字参数将设置为标头，但headers 参数应优先用于可读性。

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

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

raise_request_exception 参数允许控制在请求期间引发的异常是否也应在测试中引发。默认为True。

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

Django 5.1 中的更改

添加了query_params 参数。

获得Client 实例后，您可以调用以下任何方法

get(path, data=None, follow=False, secure=False, *, headers=None, query_params=None, **extra)[source]¶

对提供的path 发出 GET 请求，并返回一个Response 对象，该对象在下面有说明。

query_params 字典中的键值对用于设置查询字符串。例如

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

…将导致评估一个等效于以下GET请求的请求。

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

也可以将这些参数传递到data参数中。但是，query_params更受欢迎，因为它适用于任何HTTP方法。

可以使用headers参数指定要在请求中发送的请求头。例如

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

…将发送HTTP请求头HTTP_ACCEPT到详细信息视图，这是一种测试使用django.http.HttpRequest.accepts()方法的代码路径的好方法。

任意关键字参数设置WSGI 环境变量。例如，设置脚本名称的请求头

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

如果您已经拥有URL编码形式的GET参数，则可以使用该编码而不是使用data参数。例如，前面的GET请求也可以表示为

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

如果您提供了一个URL，该URL同时包含编码的GET数据和query_params或data参数，则这些参数将优先。

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

如果您有一个URL /redirect_me/重定向到/next/，该URL重定向到/final/，这就是您将看到的内容

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

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

Django 5.1 中的更改

添加了query_params 参数。

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

对提供的path发出POST请求，并返回一个Response对象，该对象在下面有说明。

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

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

…将导致评估对该URL的POST请求

/login/

…以及以下POST数据

name=fred&passwd=secret

如果将content_type设置为application/json，则如果data是字典、列表或元组，则使用json.dumps()对其进行序列化。默认情况下，序列化使用DjangoJSONEncoder执行，可以通过向Client提供json_encoder参数来覆盖它。这种序列化也适用于put()、patch()和delete()请求。

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

如果不为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、query_params和extra参数的作用与Client.get()相同。

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

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

…处理此请求的视图可以查询request.POST以检索用户名和密码，并且可以查询request.GET以确定用户是否是访客。

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

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

Django 5.1 中的更改

添加了query_params 参数。

head(path, data=None, follow=False, secure=False, *, headers=None, query_params=None, **extra)[source]¶

对提供的path发出HEAD请求，并返回一个Response对象。此方法的工作方式与Client.get()相同，包括follow、secure、headers、query_params和extra参数，但它不返回消息正文。

Django 5.1 中的更改

添加了query_params 参数。

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

对提供的 path 发起 OPTIONS 请求，并返回一个 Response 对象。这对于测试 RESTful 接口很有用。

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