テストツール¶

Django は、テストを書くのに便利なツールをいくつか提供しています。

テストクライアント¶

テストクライアントは、ダミーのウェブブラウザとして振る舞う Python のクラスです。これを使えば、ビューと Django で作ったアプリケーションとの関係をプログラムから自動でテストできるようになります。

テストクライアントでは、次のようなことができます。

ある URL に対する GET および POST リクエストのシミュレートと、その結果の観察。低レベルの HTTP (レスポンスのヘッダーやステータスコードなど) から、ページのコンテンツまで、あらゆるレスポンスの内容を調査できます。
一連の (好きな数の) リダイレクトを見て、その各ステップごとに URL とステータスコードをチェックする。
指定したリクエストが特定の Django テンプレートによってレンダリングされたとき、テンプレートのコンテキストが正しく特定の値を含んでいるかどうかをテストする。

テストクライアントは Selenium や他の "ブラウザ内 (in-browser)" フレームワークの代替を目指すものではないことに注意してください。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...'

この例が示唆しているように、 Client のインスタンスは、Python のインタラクティブなインタプリタ上のセッションからでも作ることができます。

テストクライアントの動作の仕方に関して、いくつか大切な注意点があります。

テストクライアントが動作するために、ウェブサーバーが動作している必要は ありません 。実際、ウェブサーバーを一切起動せずに動作するのです！ HTTP のオーバーヘッドを避けて、Django フレームワークと直接やりとりすることでこれを実現しています。これにより、高速なユニットテストが可能になっています。
ページの取得時には、ドメイン全体ではなく、URL の path だけを指定することを覚えておいてください。たとえば、次は正しいです。
```
>>> c.get("/login/")
```
しかし、これは間違いです。
```
>>> c.get("https://www.example.com/login/")
```
テストクライアントには、自分の Django プロジェクト以外のウェブページを取得する機能はありません。他のウェブページが必要な場合には、 urllib などの Python のスタンダードライブラリモジュールを利用してください。
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 環境変数 を指定します。例えば、スクリプト名の場合:

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エンコーダを指定できます。

Changed in Django 5.1:

query_params 引数が追加されました。

Client インスタンスを一度作れば、以下のメソッドを自由に使うことができます。

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

与えられた path に対して GET リクエストを作り、Response オブジェクトを返します。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 を使用する方が推奨されます。なぜなら、query_params はすべてのHTTPメソッドで動作するからです。

headers 引数は、リクエスト時に送信されるヘッダーの指定に使われます。たとえば、次のコード

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

は、HTTP ヘッダー HTTP_ACCEPT を details ビューに送信します。これは、 django.http.HttpRequest.accepts() メソッドを使ったコードパースのテストのための良い方法です。

任意のキーワード引数には、WSGI 環境変数 を指定します。たとえば、スクリプト名を設定するヘッダの場合:

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

GET の引数がすでに URL エンコードされた形式である場合は、data 引数の代わりにエンコード済みの文字列を使うことができます。たとえば、先ほどの GET リクエストは次のようにも書けます。

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

エンコード済みのGETデータを含むURLと query_params または data 引数の両方を指定した場合、これらの引数が優先されます。

follow を True を与えると、クライアントはすべてのリダイレクトを辿り、途中の URL とステータスコードのタプルが、レスポンスオブジェクトの redirect_chain 属性に追加されてゆきます。

たとえば、URL /redirect_me/ が /next/ にリダイレクトし、それがさらに /final/ にリダイレクトするような場合には、redirect_chain は次のような値になります。

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

secure を True に設定すると、クライアントは HTTPS リクエストをエミュレートします。

Changed in 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 オブジェクトを返します。Response オブジェクトについては、下のセクションにドキュメントされています。

data ディクショナリ内の key-value ペアは、POST データを送信するのに使われます。例えば、次の例では、

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

引数の評価の結果、次の URL へ POST リクエストが行われます。

/login/

リクエストで送られる POST データは次のものになります。

name=fred&passwd=secret

content_type に application/json を指定すると、 data が dict、リスト、タプルの場合、 json.dumps() を使ってシリアライズされます。デフォルトでは DjangoJSONEncoder でシリアライズを行いますが、 Client に json_encoder 引数を指定することでオーバーライドできます。このシリアライズは put(), patch(), delete() リクエストでも行われます。

もし他の content_type (たとえば、XML データの場合は text/xml) を与えると、data のコンテンツは、HTTP の Content-Type ヘッダーの中で content_type を使ったものとして、POST リクエストで送られます。

content_type に値を渡さなかったときは、data 内の値を multipart/form-data のコンテンツタイプとして送信します。この場合は、 data 内のkey-value ペアが multipart メッセージにえんこーどされ、POST データを生成するのに使われます。

たとえば <select multiple> の複数の選択を指定する場合のように、特定のキーに対して複数の値を送信したいときは、必要なキーに対する値をリストまたはタプルとして与えます。たとえば、 data に次の値を与えれば、3つの選択した値を choice という名前のフィールドに対して送信できます。

{"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 にアップロードする場合、オブジェクトには 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 間でファイルポインタを手動でリセットする必要があります。これを一番簡単に扱う方法は、上に示したように、ファイルが post() に与えられた後に手動でファイルを close することです。

データが読み込めるように、正しい方法でファイルを開くようにする必要があります。これはつまり、画像ファイルなどのバイナリデータが含まれている場合には、rb (read binary、バイナリ読み込み) モードで開かなければならないということです。

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 からはユーザーが visitor であるかどうかを特定できます。

secure を True に設定すると、クライアントは HTTPS リクエストをエミュレートします。

Changed in 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 パラメータを含みます。ただし、メッセージボディは返されません。

Changed in Django 5.1:
query_params 引数が追加されました。

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

与えられた path に対して OPTION リクエストを作り、Response オブジェクトを返します。RESTful インターフェイスのテスト時に有用です。

data が与えられると、request body として使われます。 content_type は Content-Type ヘッダーに設定されます。