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.2
5.0
5.1
dev
文档版本： 4.1

测试工具¶

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.
检索页面时，请记住指定 URL 的路径，而不是整个域。例如，这是正确的：
```
>>> c.get('/login/')
```
这是错误的：
```
>>> 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 检查。

如果出于某种原因，你想让测试客户端执行 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, **defaults)¶

它在构造时不需要任何参数。然而，你可以使用关键字参数来指定一些默认头信息。例如，这将在每个请求中发送一个 User-Agent HTTP 头：

>>> c = Client(HTTP_USER_AGENT='Mozilla/5.0')

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

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

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

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

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

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

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

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

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

......将产生等效的 GET 请求：

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

extra 关键词参数可以用来指定请求中要发送的头信息。例如：

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

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

CGI 规范

通过 **extra 发送的头信息应遵循 CGI 规范。例如，在浏览器向服务器发送的 HTTP 请求中，模拟不同的“Host”头，应以 HTTP_HOST 的形式发送。

如果你已经有了 URL 编码形式的 GET 参数，你可以使用该编码代替使用数据参数。例如，之前的 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 请求。

post(path, data=None, content_type=MULTIPART_CONTENT, follow=False, secure=False, **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')}

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})

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

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

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

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

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

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

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