取得協助

el
es
fr
id
it
ja
ko
pl
pt-br
zh-hans
語言: en

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
dev
文件版本: 5.1

測試工具¶

Django 提供一小組方便撰寫測試的工具。

測試客戶端¶

測試客戶端是一個 Python 類別，其作用如同一個虛擬的網頁瀏覽器，讓您能以程式化的方式測試您的檢視並與您的 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。

請注意關於測試客戶端運作方式的幾點重要事項

測試客戶端不需要執行網頁伺服器。事實上，即使完全沒有網頁伺服器執行，它也能正常運作！這是因為它避免了 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)[原始碼]¶

一個測試 HTTP 客戶端。接受數個可用於自訂行為的引數。

headers 允許您指定將隨每個請求傳送的預設標頭。例如，若要設定 User-Agent 標頭

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

query_params 允許您指定將在每個請求上設定的預設查詢字串。

**defaults 中的任意關鍵字引數會設定 WSGI environ 變數。例如，若要設定指令碼名稱

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)[原始碼]¶

在提供的 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 同時具有編碼的 GET 資料以及 query_params 或 data 參數，這些參數將優先處理。

如果您將 follow 設定為 True，客戶端將會追蹤任何重新導向，並且會在回應物件中設定一個 redirect_chain 屬性，其中包含中間 URL 和狀態碼的元組。

如果您有一個 URL /redirect_me/ 重新導向到 /next/，而 /next/ 又重新導向到 /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)[原始碼]¶

在提供的 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() 序列化（如果它是 dict、list 或 tuple）。序列化預設會使用 DjangoJSONEncoder 執行，並且可以透過提供 json_encoder 參數給 Client 來覆寫。此序列化也適用於 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"]}

提交檔案是一種特殊情況。要 POST 檔案，您只需要提供檔案欄位名稱作為鍵，並將您想要上傳的檔案的檔案控制代碼作為值。例如，如果您的表單具有欄位 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 之間手動重設檔案指標。執行此操作最簡單的方法是在將檔案提供給 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)[原始碼]¶: 在提供的 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)[原始碼]¶

對提供的 path 發出 OPTIONS 請求，並返回一個 Response 物件。適用於測試 RESTful 介面。

當提供 data 時，它將被用作請求主體，並且 Content-Type 標頭會被設定為 content_type。