テストツール

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

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

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

  • 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 の path だけを指定することを覚えておいてください。たとえば、次は正しいです。

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

It requires no arguments at time of construction. However, you can use keyword arguments to specify some default headers. For example, this will send a User-Agent HTTP header in each request:

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

The values from the extra keyword arguments passed to get(), post(), etc. have precedence over the defaults passed to the class constructor.

enforce_csrf_checks 引数を使うと、CSRF プロテクションのテストが実行できます (上の説明を参照)。

The raise_request_exception argument allows controlling whether or not exceptions raised during the request should also be raised in the test. Defaults to True.

The json_encoder argument allows setting a custom JSON encoder for the JSON serialization that's described in post().

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

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

与えられた path に対して GET リクエストを作り、Response オブジェクトを返します。Response オブジェクトについては、下のセクションにドキュメントされています。

data ディクショナリ内の key-value ペアは、GET の URL のデータ部分を構築するのに使われます。例えば、次の例では、

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

...will send the HTTP header HTTP_ACCEPT to the details view, which is a good way to test code paths that use the django.http.HttpRequest.accepts() method.

CGI の仕様

**extra で送信されるヘッダーは、以下の CGI の仕様に従わなければなりません。たとえば、HTTP リクエストの送信時に、ブラウザから異なる "Host" ヘッダーを送信することをエミュレートするためには、HTTP_HOST というヘッダを渡さなければなりません。

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

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

エンコード済みの GET データと data 引数の両方が与えられた場合には、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 リクエストをエミュレートします。

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

If you provide content_type as application/json, the data is serialized using json.dumps() if it's a dict, list, or tuple. Serialization is performed with DjangoJSONEncoder by default, and can be overridden by providing a json_encoder argument to Client. This serialization also happens for put(), patch(), and delete() requests.

If you provide any other content_type (e.g. text/xml for an XML payload), the contents of data are sent as-is in the POST request, using content_type in the HTTP Content-Type header.

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

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

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

You may also provide any file-like object (e.g., StringIO or BytesIO) as a file handle. If you're uploading to an ImageField, the object needs a name attribute that passes the validate_image_file_extension validator. For example:

>>> 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、バイナリ読み込み) モードで開かなければならないということです。

extra 引数は Client.get() と同じように振る舞います。

POST でリクエストした URL にエンコード済みパラメータが含まれている場合には、これらのデータは request.GET データから利用できます。たとえば、次のようなリクエストを行った場合、

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

このリクエストをハンドリングするビューでは、request.POST からはユーザー名とパスワードを取得し、request.GET からはユーザーが visitor であるかどうかを特定することができます。

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

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

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

与えられた path に対して HEAD リクエストを作り、Response オブジェクトを返します。message body を返さない点を除いて、 Client.get() と同じように動作します。 follow 、 secure 、 extra の引数の動作も同様です。

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

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

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

follow 、 secure 、 extra 引数は、 Client.get() と同様に動作します。

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

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

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

follow 、 secure 、 extra 引数は、 Client.get() と同様に動作します。

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

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

follow 、 secure 、 extra 引数は、 Client.get() と同様に動作します。

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

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

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

follow 、 secure 、 extra 引数は、 Client.get() と同様に動作します。

trace(path, follow=False, secure=False, **extra)

与えられた path に対して TRACE リクエストを作り、Response オブジェクトを返します。診断のための調査をシミュレートするときに役に立ちます。

他のリクエストメソッドとは違い、 data がキーワード引数にありません。 RFC 7231#section-4.3.8 に従うためです。そのため、TRACE リクエストには body を含むことが禁止されています。

follow 、 secure 、 extra 引数は、 Client.get() と同様に動作します。

login(**credentials)

あなたのサイトが Django の 認証システム を使っていて、ユーザーのログインをテストしたければ、テストクライアントの login() メソッドを使うことで、ユーザーがサイトにログインしたときの状況をシミュレートできます。

このメソッドを呼ぶ事で、テストクライアントはログインに基づいてビューを形成するテストを行う上で必要なクッキーとセッション情報を全て持ちます。

引数 credentials の形式は利用している (AUTHENTICATION_BACKENDS の設定値に定義されています) 認証バックエンド に依存します。Django によって提供される標準の認証バックエンド (ModelBackend) を用いている場合は、 credentials は利用者のユーザー名とパスワードであり、キーワード引数として渡されます:

>>> c = Client()
>>> c.login(username='fred', password='secret')

# Now you can access a view that's only available to logged-in users.

もし標準以外の認証バックエンドを利用している場合、このメソッドは異なった認証情報を必要とします。この値では利用している認証バックエンドの authenticate() メソッドによって要求される認証情報が必要になります。

認証情報が受け入れられてログインが成功した場合に login() は True を返します。

Finally, you'll need to remember to create user accounts before you can use this method. As we explained above, the test runner is executed using a test database, which contains no users by default. As a result, user accounts that are valid on your production site will not work under test conditions. You'll need to create users as part of the test suite -- either manually (using the Django model API) or with a test fixture. Remember that if you want your test user to have a password, you can't set the user's password by setting the password attribute directly -- you must use the set_password() function to store a correctly hashed password. Alternatively, you can use the create_user() helper method to create a new user with a correctly hashed password.

force_login(user, backend=None)

If your site uses Django's authentication system, you can use the force_login() method to simulate the effect of a user logging into the site. Use this method instead of login() when a test requires a user be logged in and the details of how a user logged in aren't important.

Unlike login(), this method skips the authentication and verification steps: inactive users (is_active=False) are permitted to login and the user's credentials don't need to be provided.

The user will have its backend attribute set to the value of the backend argument (which should be a dotted Python path string), or to settings.AUTHENTICATION_BACKENDS[0] if a value isn't provided. The authenticate() function called by login() normally annotates the user like this.

This method is faster than login() since the expensive password hashing algorithms are bypassed. Also, you can speed up login() by using a weaker hasher while testing.

logout()

If your site uses Django's authentication system, the logout() method can be used to simulate the effect of a user logging out of your site.

After you call this method, the test client will have all the cookies and session data cleared to defaults. Subsequent requests will appear to come from an AnonymousUser.

レスポンスのテスト

get() および post() メソッドは、両方とも Response オブジェクトを返します。この``Response`` オブジェクトは、Django のビューによって返される HttpResponse オブジェクトとは 異なるものです; テストのレスポンスは、テストコードの検証に役立ついくつかの追加データを持ちます。

特に、Response オブジェクトは以下の属性を持ちます:

class Response
client

レスポンスの結果の元となるリクエストを作るために使われた、テストクライアントです。

content

Bytestring としてのレスポンスの本文です。ビューないしエラーメッセージによってレンダリングされる際の最終的なページコンテンツです。

context

テンプレートの Context インスタンスです。レスポンスの content を生成するテンプレートをレンダリングする際に使われます。

描画されたページが複数のテンプレートを使っていた場合、context は``Context`` オブジェクトのリストとなり、その順序はレンダリングされた順となります。

レンダリングに使われるテンプレートの数にかかわらず、[] オペレータを使ってコンテキストの値を取り出すことができます。たとえば、コンテキストの変数 name は以下のように取り出せます:

>>> response = client.get('/foo/')
>>> response.context['name']
'Arthur'

Django のテンプレートを使っていない?

この属性は、DjangoTemplates バックエンドを使用しているときのみ格納されます。他のテンプレートエンジンを使っている場合、context_data がこの属性を扱うレスポンスの適切な選択肢となるでしょう。

exc_info

A tuple of three values that provides information about the unhandled exception, if any, that occurred during the view.

The values are (type, value, traceback), the same as returned by Python's sys.exc_info(). Their meanings are:

  • type: The type of the exception.
  • value: The exception instance.
  • traceback: A traceback object which encapsulates the call stack at the point where the exception originally occurred.

If no exception occurred, then exc_info will be None.

json(**kwargs)

JSON としてパースされた、レスポンスの本文です。追加のキーワード引数が json.loads() に渡されます。たとえば:

>>> response = client.get('/foo/')
>>> response.json()['name']
'Arthur'

Content-Type ヘッダが "application/json" ではない場合、レスポンスをパースする際に ValueError が投げられます。

request

レスポンスを機能させるリクエストデータです。

wsgi_request

レスポンスにより生成されたテストヘッダーが生成する WSGIRequest インスタンスです。

status_code

レスポンスの HTTP ステータスで、数値です。 定義済みのコードの全リストは、IANA status code registry を参照してください。

templates

最終コンテンツをレンダリングするときに使われる Template インスタンスのリストで、 レンダリングされる順となります。テンプレートがファイルから読み込まれる場合、テンプレートのファイル名を取得するためには、リスト内の各テンプレートに対して template.name を使ってください (名前は 'admin/index.html' のような文字列となります)。

Django のテンプレートを使っていない?

この属性は、DjangoTemplates バックエンドを使用しているときのみ格納されます。他のテンプレートを知使っている場合、template_name が、レンダリングに使われるテンプレートの名前のみが必要な場合の適切な代替策となるでしょう。

resolver_match

レスポンスに対する ResolverMatch のインスタンスです。func 属性を使うことができます。たとえば、レスポンスを提供するビューを検証するために使えます:

# my_view here is a function based view.
self.assertEqual(response.resolver_match.func, my_view)

# Class-based views need to compare the view_class, as the
# functions generated by as_view() won't be equal.
self.assertIs(response.resolver_match.func.view_class, MyView)

指定された URL が見つからない場合、この属性にアクセスすると Resolver404 例外が投げられます。

As with a normal response, you can also access the headers through HttpResponse.headers. For example, you could determine the content type of a response using response.headers['Content-Type'].

例外

If you point the test client at a view that raises an exception and Client.raise_request_exception is True, that exception will be visible in the test case. You can then use a standard try ... except block or assertRaises() to test for exceptions.

The only exceptions that are not visible to the test client are Http404, PermissionDenied, SystemExit, and SuspiciousOperation. Django catches these exceptions internally and converts them into the appropriate HTTP response codes. In these cases, you can check response.status_code in your test.

If Client.raise_request_exception is False, the test client will return a 500 response as would be returned to a browser. The response has the attribute exc_info to provide information about the unhandled exception.

Persistent state

テストクライアントはステートフルです。レスポンスがクッキーを返す場合、そのクッキーはテストクライアント内に保持され、以降すべての get() および post() リクエストともに送信されます。

クッキーに対する有効期限ポリシーは使えません。クッキーを期限切れにしたい場合、手動で削除するか、新たに (すべてのクッキーを削除するために) Client を作成してください。

A test client has attributes that store persistent state information. You can access these properties as part of a test condition.

Client.cookies

Python の SimpleCookie オブジェクトで、すべてのクライアントのクッキーの現在の値を含みます。より詳しくは、http.cookies のドキュメントを参照してください。

Client.session

辞書形式のようなオブジェクトで、セッション情報を含みます。セッションのドキュメント に網羅的情報があります。

セッションを修正し保存するためには、まず変数に格納される必要があります (新しい SessionStore は、この属性がアクセスされるたびに作られるためです):

def test_something(self):
    session = self.client.session
    session['somekey'] = 'test'
    session.save()

言語の設定

国際化とローカルかをサポートしているアプリケーションをテストする際、テストクライアントのリクエストに対して言語を設定するのがよいでしょう。その方法は、LocaleMiddleware が有効化されているか否かによって異なります。

ミドルウェアが有効化されている場合、LANGUAGE_COOKIE_NAME の名前でクッキーを作成することでセットすることができ、言語コードの値は:

from django.conf import settings

def test_language_using_cookie(self):
    self.client.cookies.load({settings.LANGUAGE_COOKIE_NAME: 'fr'})
    response = self.client.get('/')
    self.assertEqual(response.content, b"Bienvenue sur mon site.")

もしくは、Accept-Language HTTP ヘッダをリクエスト内に含めます:

def test_language_using_header(self):
    response = self.client.get('/', HTTP_ACCEPT_LANGUAGE='fr')
    self.assertEqual(response.content, b"Bienvenue sur mon site.")

注釈

When using these methods, ensure to reset the active language at the end of each test:

def tearDown(self):
    translation.activate(settings.LANGUAGE_CODE)

さらなる詳細は How Django discovers language preference にあります。

ミドルウェアが有効化されていない場合、アクティブな言語は translation.override() を使って設定できます:

from django.utils import translation

def test_language_using_override(self):
    with translation.override('fr'):
        response = self.client.get('/')
    self.assertEqual(response.content, b"Bienvenue sur mon site.")

さらなる詳細は 明示的にアクティブな言語をセットする にあります。

カスタマイズ例

The following is a unit test using the test client:

import unittest
from django.test import Client

class SimpleTest(unittest.TestCase):
    def setUp(self):
        # Every test needs a client.
        self.client = Client()

    def test_details(self):
        # Issue a GET request.
        response = self.client.get('/customer/details/')

        # Check that the response is 200 OK.
        self.assertEqual(response.status_code, 200)

        # Check that the rendered context contains 5 customers.
        self.assertEqual(len(response.context['customers']), 5)

参考

django.test.RequestFactory

提供されるテストケースのクラス

標準の Python ユニットテストのクラスは、unittest.TestCase のベースクラスを拡張しています。Django は、このベースクラスのいくつかの拡張を提供します:

Hierarchy of Django unit testing classes (TestCase subclasses)

Hierarchy of Django unit testing classes

You can convert a normal unittest.TestCase to any of the subclasses: change the base class of your test from unittest.TestCase to the subclass. All of the standard Python unit test functionality will be available, and it will be augmented with some useful additions as described in each section below.

SimpleTestCase

class SimpleTestCase

以下の機能を追加する、unittest.TestCase のサブクラスです:

データベースクエリを作る手薄との場合、サブクラス TransactionTestCase や TestCase を使用してください。

SimpleTestCase.databases

SimpleTestCase disallows database queries by default. This helps to avoid executing write queries which will affect other tests since each SimpleTestCase test isn't run in a transaction. If you aren't concerned about this problem, you can disable this behavior by setting the databases class attribute to '__all__' on your test class.

警告

SimpleTestCase とそのサブクラス (例: TestCase, ...) は、setUpClass() と tearDownClass() に依存して、クラス横断的な初期化を実現しています (例: 設定のオーバーライド) これらをオーバーライドする必要があるときは、super 実装を呼び出すのを忘れないでください:

class MyTestCase(TestCase):

    @classmethod
    def setUpClass(cls):
        super().setUpClass()
        ...

    @classmethod
    def tearDownClass(cls):
        ...
        super().tearDownClass()

Be sure to account for Python's behavior if an exception is raised during setUpClass(). If that happens, neither the tests in the class nor tearDownClass() are run. In the case of django.test.TestCase, this will leak the transaction created in super() which results in various symptoms including a segmentation fault on some platforms (reported on macOS). If you want to intentionally raise an exception such as unittest.SkipTest in setUpClass(), be sure to do it before calling super() to avoid this.

TransactionTestCase

class TransactionTestCase

TransactionTestCase は SimpleTestCase を継承し、データベースに特有の機能を追加しています:

Django's TestCase class is a more commonly used subclass of TransactionTestCase that makes use of database transaction facilities to speed up the process of resetting the database to a known state at the beginning of each test. A consequence of this, however, is that some database behaviors cannot be tested within a Django TestCase class. For instance, you cannot test that a block of code is executing within a transaction, as is required when using select_for_update(). In those cases, you should use TransactionTestCase.

TransactionTestCase and TestCase are identical except for the manner in which the database is reset to a known state and the ability for test code to test the effects of commit and rollback:

  • A TransactionTestCase resets the database after the test runs by truncating all tables. A TransactionTestCase may call commit and rollback and observe the effects of these calls on the database.
  • A TestCase, on the other hand, does not truncate tables after a test. Instead, it encloses the test code in a database transaction that is rolled back at the end of the test. This guarantees that the rollback at the end of the test restores the database to its initial state.

警告

TestCase running on a database that does not support rollback (e.g. MySQL with the MyISAM storage engine), and all instances of TransactionTestCase, will roll back at the end of the test by deleting all data from the test database.

Apps will not see their data reloaded; if you need this functionality (for example, third-party apps should enable this) you can set serialized_rollback = True inside the TestCase body.

TestCase

class TestCase

これは、Django でテストを書く際に使われる、最も一般的なクラスです。TransactionTestCase (と拡張による SimpleTestCase) を継承します。あなたの Django アプリケーションがデータベースを使用しない場合は、SimpleTestCase を使ってください。

クラス:

  • 2 つのネストされた atomic() ブロックでテストをラップします: 1 つはテスト全体、もう 1 つは各テストのためです。したがって、特定のデータベーストランザクションの振る舞いをテストしたい場合は、TransactionTestCase を使ってください。
  • 各テストの最後に、deferrable なデータベース制約をチェックします。

さらに追加メソッドを提供します:

classmethod TestCase.setUpTestData()

上述のクラスレベルの atomic ブロックは、全体の TestCase に対して一度、クラスレベルでの初期データの作成を可能にします。 この技法により、setUp() を使うのに比べて高速なテストとなります。

例:

from django.test import TestCase

class MyTests(TestCase):
    @classmethod
    def setUpTestData(cls):
        # Set up data for the whole TestCase
        cls.foo = Foo.objects.create(bar="Test")
        ...

    def test1(self):
        # Some test using self.foo
        ...

    def test2(self):
        # Some other test using self.foo
        ...

テストがトランザクションサポートのないデータベース (たとえば MyISAM エンジンの MySQL) で実行される場合、各テストの前に setUpTestData() が呼ばれ、高速化のメリットはなくなります。

Objects assigned to class attributes in setUpTestData() must support creating deep copies with copy.deepcopy() in order to isolate them from alterations performed by each test methods.

classmethod TestCase.captureOnCommitCallbacks(using=DEFAULT_DB_ALIAS, execute=False)

Returns a context manager that captures transaction.on_commit() callbacks for the given database connection. It returns a list that contains, on exit of the context, the captured callback functions. From this list you can make assertions on the callbacks or call them to invoke their side effects, emulating a commit.

using is the alias of the database connection to capture callbacks for.

If execute is True, all the callbacks will be called as the context manager exits, if no exception occurred. This emulates a commit after the wrapped block of code.

例:

from django.core import mail
from django.test import TestCase


class ContactTests(TestCase):
    def test_post(self):
        with self.captureOnCommitCallbacks(execute=True) as callbacks:
            response = self.client.post(
                '/contact/',
                {'message': 'I like your site'},
            )

        self.assertEqual(response.status_code, 200)
        self.assertEqual(len(callbacks), 1)
        self.assertEqual(len(mail.outbox), 1)
        self.assertEqual(mail.outbox[0].subject, 'Contact Form')
        self.assertEqual(mail.outbox[0].body, 'I like your site')
Changed in Django 4.0:

In older versions, new callbacks added while executing transaction.on_commit() callbacks were not captured.

LiveServerTestCase

class LiveServerTestCase

LiveServerTestCase は TransactionTestCase とほぼ同じですが、追加機能を 1 つ持ちます: セットアップ時に実際の Django サーバーをバックグラウンドでローンチし、 終了時に破棄します。これにより、たとえば Selenium client のような Django ダミークライアント 以外の自動化されたテストクライアントを使えるようになり、ブラウザ内での一連の機能テストを実施して実際のユーザーの行動をシミュレートできます。

The live server listens on localhost and binds to port 0 which uses a free port assigned by the operating system. The server's URL can be accessed with self.live_server_url during the tests.

To demonstrate how to use LiveServerTestCase, let's write a Selenium test. First of all, you need to install the selenium package into your Python path:

$ python -m pip install selenium

...\> py -m pip install selenium

Then, add a LiveServerTestCase-based test to your app's tests module (for example: myapp/tests.py). For this example, we'll assume you're using the staticfiles app and want to have static files served during the execution of your tests similar to what we get at development time with DEBUG=True, i.e. without having to collect them using collectstatic. We'll use the StaticLiveServerTestCase subclass which provides that functionality. Replace it with django.test.LiveServerTestCase if you don't need that.

The code for this test may look as follows:

from django.contrib.staticfiles.testing import StaticLiveServerTestCase
from selenium.webdriver.common.by import By
from selenium.webdriver.firefox.webdriver import WebDriver

class MySeleniumTests(StaticLiveServerTestCase):
    fixtures = ['user-data.json']

    @classmethod
    def setUpClass(cls):
        super().setUpClass()
        cls.selenium = WebDriver()
        cls.selenium.implicitly_wait(10)

    @classmethod
    def tearDownClass(cls):
        cls.selenium.quit()
        super().tearDownClass()

    def test_login(self):
        self.selenium.get('%s%s' % (self.live_server_url, '/login/'))
        username_input = self.selenium.find_element(By.NAME, "username")
        username_input.send_keys('myuser')
        password_input = self.selenium.find_element(By.NAME, "password")
        password_input.send_keys('secret')
        self.selenium.find_element(By.XPATH, '//input[@value="Log in"]').click()

Finally, you may run the test as follows:

$ ./manage.py test myapp.tests.MySeleniumTests.test_login

...\> manage.py test myapp.tests.MySeleniumTests.test_login

This example will automatically open Firefox then go to the login page, enter the credentials and press the "Log in" button. Selenium offers other drivers in case you do not have Firefox installed or wish to use another browser. The example above is just a tiny fraction of what the Selenium client can do; check out the full reference for more details.

注釈

When using an in-memory SQLite database to run the tests, the same database connection will be shared by two threads in parallel: the thread in which the live server is run and the thread in which the test case is run. It's important to prevent simultaneous database queries via this shared connection by the two threads, as that may sometimes randomly cause the tests to fail. So you need to ensure that the two threads don't access the database at the same time. In particular, this means that in some cases (for example, just after clicking a link or submitting a form), you might need to check that a response is received by Selenium and that the next page is loaded before proceeding with further test execution. Do this, for example, by making Selenium wait until the <body> HTML tag is found in the response (requires Selenium > 2.13):

def test_login(self):
    from selenium.webdriver.support.wait import WebDriverWait
    timeout = 2
    ...
    self.selenium.find_element(By.XPATH, '//input[@value="Log in"]').click()
    # Wait until the response is received
    WebDriverWait(self.selenium, timeout).until(
        lambda driver: driver.find_element(By.TAG_NAME, 'body'))

The tricky thing here is that there's really no such thing as a "page load," especially in modern web apps that generate HTML dynamically after the server generates the initial document. So, checking for the presence of <body> in the response might not necessarily be appropriate for all use cases. Please refer to the Selenium FAQ and Selenium documentation for more information.

テストケースの機能

デフォルトのテストクライアント

SimpleTestCase.client

django.test.*TestCase インスタンス内のすべてのテストケースは、Django のテストクライアントにアクセスすることができます。このクライアントは、self.client としてアクセスできます。このクライアントはテストごとに再作成されるため、(クッキーのような) ステートがテスト間で持ち越されることを心配する必要はありません。

つまり、各テスト内で Client をインスタンス化する代わりに:

import unittest
from django.test import Client

class SimpleTest(unittest.TestCase):
    def test_details(self):
        client = Client()
        response = client.get('/customer/details/')
        self.assertEqual(response.status_code, 200)

    def test_index(self):
        client = Client()
        response = client.get('/customer/index/')
        self.assertEqual(response.status_code, 200)

...you can refer to self.client, like so:

from django.test import TestCase

class SimpleTest(TestCase):
    def test_details(self):
        response = self.client.get('/customer/details/')
        self.assertEqual(response.status_code, 200)

    def test_index(self):
        response = self.client.get('/customer/index/')
        self.assertEqual(response.status_code, 200)

テストクライアントをカスタムする

SimpleTestCase.client_class

異なる Client クラスを使用したい場合 (たとえば独自の動作を持つサブクラス)、client_class クラス属性を使ってください:

from django.test import Client, TestCase

class MyTestClient(Client):
    # Specialized methods for your environment
    ...

class MyTest(TestCase):
    client_class = MyTestClient

    def test_my_stuff(self):
        # Here self.client is an instance of MyTestClient...
        call_some_test_code()

フィクスチャーのロード

TransactionTestCase.fixtures

データベースに基づくウェブサイトに対するテストケースは、データベースにデータがないとほとんど意味がありません。テストは、たとえば TestCase.setUpTestData() 内の ORM を使うことでより可読性が高く維持しやすくなりますが、フィクスチャーを使うこともできます。

フィクスチャーは、Django がどうやってデータベースにインポートするか分かっているデータのコレクションです。たとえば、サイトがユーザーアカウントを持つ場合、テスト内でデータベースに格納させるために、フェイクのユーザーアカウントのフィクスチャーをセットアップできます。

フィクスチャーを作成するもっとも分かりやすい方法は、manage.py dumpdata コマンドを使うことです。これは、データベース内にすでに何らかのデータがあるという仮定に基づいています。詳細は、dumpdata のドキュメント 参照してください。

いったんフィクスチャーを作成して INSTALLED_APPS 内ののどれかで fixtures ディクショナリに記述したら、django.test.TestCase サブクラスで fixtures クラス属性を指定することで、ユニットテスト内でこのフィクスチャーを使うことができます:

from django.test import TestCase
from myapp.models import Animal

class AnimalTestCase(TestCase):
    fixtures = ['mammals.json', 'birds']

    def setUp(self):
        # Test definitions as before.
        call_setup_methods()

    def test_fluffy_animals(self):
        # A test that uses the fixtures.
        call_some_test_code()

Here's specifically what will happen:

  • At the start of each test, before setUp() is run, Django will flush the database, returning the database to the state it was in directly after migrate was called.
  • Then, all the named fixtures are installed. In this example, Django will install any JSON fixture named mammals, followed by any fixture named birds. See the loaddata documentation for more details on defining and installing fixtures.

For performance reasons, TestCase loads fixtures once for the entire test class, before setUpTestData(), instead of before each test, and it uses transactions to clean the database before each test. In any case, you can be certain that the outcome of a test will not be affected by another test or by the order of test execution.

By default, fixtures are only loaded into the default database. If you are using multiple databases and set TransactionTestCase.databases, fixtures will be loaded into all specified databases.

URLconf configuration

If your application provides views, you may want to include tests that use the test client to exercise those views. However, an end user is free to deploy the views in your application at any URL of their choosing. This means that your tests can't rely upon the fact that your views will be available at a particular URL. Decorate your test class or test method with @override_settings(ROOT_URLCONF=...) for URLconf configuration.

Multi-database support

TransactionTestCase.databases

Django sets up a test database corresponding to every database that is defined in the DATABASES definition in your settings and referred to by at least one test through databases.

However, a big part of the time taken to run a Django TestCase is consumed by the call to flush that ensures that you have a clean database at the start of each test run. If you have multiple databases, multiple flushes are required (one for each database), which can be a time consuming activity -- especially if your tests don't need to test multi-database activity.

As an optimization, Django only flushes the default database at the start of each test run. If your setup contains multiple databases, and you have a test that requires every database to be clean, you can use the databases attribute on the test suite to request extra databases to be flushed.

例:

class TestMyViews(TransactionTestCase):
    databases = {'default', 'other'}

    def test_index_page_view(self):
        call_some_test_code()

This test case will flush the default and other test databases before running test_index_page_view. You can also use '__all__' to specify that all of the test databases must be flushed.

The databases flag also controls which databases the TransactionTestCase.fixtures are loaded into. By default, fixtures are only loaded into the default database.

Queries against databases not in databases will give assertion errors to prevent state leaking between tests.

TestCase.databases

By default, only the default database will be wrapped in a transaction during a TestCase's execution and attempts to query other databases will result in assertion errors to prevent state leaking between tests.

Use the databases class attribute on the test class to request transaction wrapping against non-default databases.

例:

class OtherDBTests(TestCase):
    databases = {'other'}

    def test_other_db_query(self):
        ...

This test will only allow queries against the other database. Just like for SimpleTestCase.databases and TransactionTestCase.databases, the '__all__' constant can be used to specify that the test should allow queries to all databases.

Overriding settings

警告

Use the functions below to temporarily alter the value of settings in tests. Don't manipulate django.conf.settings directly as Django won't restore the original values after such manipulations.

SimpleTestCase.settings()

For testing purposes it's often useful to change a setting temporarily and revert to the original value after running the testing code. For this use case Django provides a standard Python context manager (see PEP 343) called settings(), which can be used like this:

from django.test import TestCase

class LoginTestCase(TestCase):

    def test_login(self):

        # First check for the default behavior
        response = self.client.get('/sekrit/')
        self.assertRedirects(response, '/accounts/login/?next=/sekrit/')

        # Then override the LOGIN_URL setting
        with self.settings(LOGIN_URL='/other/login/'):
            response = self.client.get('/sekrit/')
            self.assertRedirects(response, '/other/login/?next=/sekrit/')

This example will override the LOGIN_URL setting for the code in the with block and reset its value to the previous state afterward.

SimpleTestCase.modify_settings()

It can prove unwieldy to redefine settings that contain a list of values. In practice, adding or removing values is often sufficient. Django provides the modify_settings() context manager for easier settings changes:

from django.test import TestCase

class MiddlewareTestCase(TestCase):

    def test_cache_middleware(self):
        with self.modify_settings(MIDDLEWARE={
            'append': 'django.middleware.cache.FetchFromCacheMiddleware',
            'prepend': 'django.middleware.cache.UpdateCacheMiddleware',
            'remove': [
                'django.contrib.sessions.middleware.SessionMiddleware',
                'django.contrib.auth.middleware.AuthenticationMiddleware',
                'django.contrib.messages.middleware.MessageMiddleware',
            ],
        }):
            response = self.client.get('/')
            # ...

For each action, you can supply either a list of values or a string. When the value already exists in the list, append and prepend have no effect; neither does remove when the value doesn't exist.

override_settings(**kwargs)

In case you want to override a setting for a test method, Django provides the override_settings() decorator (see PEP 318). It's used like this:

from django.test import TestCase, override_settings

class LoginTestCase(TestCase):

    @override_settings(LOGIN_URL='/other/login/')
    def test_login(self):
        response = self.client.get('/sekrit/')
        self.assertRedirects(response, '/other/login/?next=/sekrit/')

The decorator can also be applied to TestCase classes:

from django.test import TestCase, override_settings

@override_settings(LOGIN_URL='/other/login/')
class LoginTestCase(TestCase):

    def test_login(self):
        response = self.client.get('/sekrit/')
        self.assertRedirects(response, '/other/login/?next=/sekrit/')
modify_settings(*args, **kwargs)

Likewise, Django provides the modify_settings() decorator:

from django.test import TestCase, modify_settings

class MiddlewareTestCase(TestCase):

    @modify_settings(MIDDLEWARE={
        'append': 'django.middleware.cache.FetchFromCacheMiddleware',
        'prepend': 'django.middleware.cache.UpdateCacheMiddleware',
    })
    def test_cache_middleware(self):
        response = self.client.get('/')
        # ...

The decorator can also be applied to test case classes:

from django.test import TestCase, modify_settings

@modify_settings(MIDDLEWARE={
    'append': 'django.middleware.cache.FetchFromCacheMiddleware',
    'prepend': 'django.middleware.cache.UpdateCacheMiddleware',
})
class MiddlewareTestCase(TestCase):

    def test_cache_middleware(self):
        response = self.client.get('/')
        # ...

注釈

When given a class, these decorators modify the class directly and return it; they don't create and return a modified copy of it. So if you try to tweak the above examples to assign the return value to a different name than LoginTestCase or MiddlewareTestCase, you may be surprised to find that the original test case classes are still equally affected by the decorator. For a given class, modify_settings() is always applied after override_settings().

警告

The settings file contains some settings that are only consulted during initialization of Django internals. If you change them with override_settings, the setting is changed if you access it via the django.conf.settings module, however, Django's internals access it differently. Effectively, using override_settings() or modify_settings() with these settings is probably not going to do what you expect it to do.

We do not recommend altering the DATABASES setting. Altering the CACHES setting is possible, but a bit tricky if you are using internals that make using of caching, like django.contrib.sessions. For example, you will have to reinitialize the session backend in a test that uses cached sessions and overrides CACHES.

Finally, avoid aliasing your settings as module-level constants as override_settings() won't work on such values since they are only evaluated the first time the module is imported.

You can also simulate the absence of a setting by deleting it after settings have been overridden, like this:

@override_settings()
def test_something(self):
    del settings.LOGIN_URL
    ...

When overriding settings, make sure to handle the cases in which your app's code uses a cache or similar feature that retains state even if the setting is changed. Django provides the django.test.signals.setting_changed signal that lets you register callbacks to clean up and otherwise reset state when settings are changed.

Django itself uses this signal to reset various data:

Overridden settings Data reset
USE_TZ, TIME_ZONE Databases timezone
TEMPLATES Template engines
SERIALIZATION_MODULES Serializers cache
LOCALE_PATHS, LANGUAGE_CODE Default translation and loaded translations
MEDIA_ROOT, DEFAULT_FILE_STORAGE Default file storage

Isolating apps

utils.isolate_apps(*app_labels, attr_name=None, kwarg_name=None)

Registers the models defined within a wrapped context into their own isolated apps registry. This functionality is useful when creating model classes for tests, as the classes will be cleanly deleted afterward, and there is no risk of name collisions.

The app labels which the isolated registry should contain must be passed as individual arguments. You can use isolate_apps() as a decorator or a context manager. For example:

from django.db import models
from django.test import SimpleTestCase
from django.test.utils import isolate_apps

class MyModelTests(SimpleTestCase):

    @isolate_apps("app_label")
    def test_model_definition(self):
        class TestModel(models.Model):
            pass
        ...

… or:

with isolate_apps("app_label"):
    class TestModel(models.Model):
        pass
    ...

The decorator form can also be applied to classes.

Two optional keyword arguments can be specified:

  • attr_name: attribute assigned the isolated registry if used as a class decorator.
  • kwarg_name: keyword argument passing the isolated registry if used as a function decorator.

The temporary Apps instance used to isolate model registration can be retrieved as an attribute when used as a class decorator by using the attr_name parameter:

@isolate_apps("app_label", attr_name="apps")
class TestModelDefinition(SimpleTestCase):
    def test_model_definition(self):
        class TestModel(models.Model):
            pass
        self.assertIs(self.apps.get_model("app_label", "TestModel"), TestModel)

… or alternatively as an argument on the test method when used as a method decorator by using the kwarg_name parameter:

class TestModelDefinition(SimpleTestCase):
    @isolate_apps("app_label", kwarg_name="apps")
    def test_model_definition(self, apps):
        class TestModel(models.Model):
            pass
        self.assertIs(apps.get_model("app_label", "TestModel"), TestModel)

Emptying the test outbox

If you use any of Django's custom TestCase classes, the test runner will clear the contents of the test email outbox at the start of each test case.

For more detail on email services during tests, see Email services below.

Assertions

As Python's normal unittest.TestCase class implements assertion methods such as assertTrue() and assertEqual(), Django's custom TestCase class provides a number of custom assertion methods that are useful for testing web applications:

The failure messages given by most of these assertion methods can be customized with the msg_prefix argument. This string will be prefixed to any failure message generated by the assertion. This allows you to provide additional details that may help you to identify the location and cause of a failure in your test suite.

SimpleTestCase.assertRaisesMessage(expected_exception, expected_message, callable, *args, **kwargs)
SimpleTestCase.assertRaisesMessage(expected_exception, expected_message)

Asserts that execution of callable raises expected_exception and that expected_message is found in the exception's message. Any other outcome is reported as a failure. It's a simpler version of unittest.TestCase.assertRaisesRegex() with the difference that expected_message isn't treated as a regular expression.

If only the expected_exception and expected_message parameters are given, returns a context manager so that the code being tested can be written inline rather than as a function:

with self.assertRaisesMessage(ValueError, 'invalid literal for int()'):
    int('a')
SimpleTestCase.assertWarnsMessage(expected_warning, expected_message, callable, *args, **kwargs)
SimpleTestCase.assertWarnsMessage(expected_warning, expected_message)

Analogous to SimpleTestCase.assertRaisesMessage() but for assertWarnsRegex() instead of assertRaisesRegex().

SimpleTestCase.assertFieldOutput(fieldclass, valid, invalid, field_args=None, field_kwargs=None, empty_value='')

Asserts that a form field behaves correctly with various inputs.

パラメータ:
  • fieldclass -- the class of the field to be tested.
  • valid -- a dictionary mapping valid inputs to their expected cleaned values.
  • invalid -- a dictionary mapping invalid inputs to one or more raised error messages.
  • field_args -- the args passed to instantiate the field.
  • field_kwargs -- the kwargs passed to instantiate the field.
  • empty_value -- the expected clean output for inputs in empty_values.

For example, the following code tests that an EmailField accepts a@a.com as a valid email address, but rejects aaa with a reasonable error message:

self.assertFieldOutput(EmailField, {'a@a.com': 'a@a.com'}, {'aaa': ['Enter a valid email address.']})
SimpleTestCase.assertFormError(form, field, errors, msg_prefix='')

Asserts that a field on a form raises the provided list of errors.

form is a Form instance. The form must be bound but not necessarily validated (assertFormError() will automatically call full_clean() on the form).

field is the name of the field on the form to check. To check the form's non-field errors, use field=None.

errors is a list of all the error strings that the field is expected to have. You can also pass a single error string if you only expect one error which means that errors='error message' is the same as errors=['error message'].

Changed in Django 4.1:

In older versions, using an empty error list with assertFormError() would always pass, regardless of whether the field had any errors or not. Starting from Django 4.1, using errors=[] will only pass if the field actually has no errors.

Django 4.1 also changed the behavior of assertFormError() when a field has multiple errors. In older versions, if a field had multiple errors and you checked for only some of them, the test would pass. Starting from Django 4.1, the error list must be an exact match to the field's actual errors.

バージョン 4.1 で非推奨: Support for passing a response object and a form name to assertFormError() is deprecated and will be removed in Django 5.0. Use the form instance directly instead.

SimpleTestCase.assertFormsetError(formset, form_index, field, errors, msg_prefix='')

Asserts that the formset raises the provided list of errors when rendered.

formset is a Formset instance. The formset must be bound but not necessarily validated (assertFormsetError() will automatically call the full_clean() on the formset).

form_index is the number of the form within the Formset (starting from 0). Use form_index=None to check the formset's non-form errors, i.e. the errors you get when calling formset.non_form_errors(). In that case you must also use field=None.

field and errors have the same meaning as the parameters to assertFormError().

バージョン 4.1 で非推奨: Support for passing a response object and a formset name to assertFormsetError() is deprecated and will be removed in Django 5.0. Use the formset instance directly instead.

SimpleTestCase.assertContains(response, text, count=None, status_code=200, msg_prefix='', html=False)

Asserts that a response produced the given status_code and that text appears in its content. If count is provided, text must occur exactly count times in the response.

Set html to True to handle text as HTML. The comparison with the response content will be based on HTML semantics instead of character-by-character equality. Whitespace is ignored in most cases, attribute ordering is not significant. See assertHTMLEqual() for more details.

SimpleTestCase.assertNotContains(response, text, status_code=200, msg_prefix='', html=False)

Asserts that a response produced the given status_code and that text does not appear in its content.

Set html to True to handle text as HTML. The comparison with the response content will be based on HTML semantics instead of character-by-character equality. Whitespace is ignored in most cases, attribute ordering is not significant. See assertHTMLEqual() for more details.

SimpleTestCase.assertTemplateUsed(response, template_name, msg_prefix='', count=None)

Asserts that the template with the given name was used in rendering the response.

response must be a response instance returned by the test client.

template_name should be a string such as 'admin/index.html'.

The count argument is an integer indicating the number of times the template should be rendered. Default is None, meaning that the template should be rendered one or more times.

You can use this as a context manager, like this:

with self.assertTemplateUsed('index.html'):
    render_to_string('index.html')
with self.assertTemplateUsed(template_name='index.html'):
    render_to_string('index.html')
SimpleTestCase.assertTemplateNotUsed(response, template_name, msg_prefix='')

Asserts that the template with the given name was not used in rendering the response.

You can use this as a context manager in the same way as assertTemplateUsed().

SimpleTestCase.assertURLEqual(url1, url2, msg_prefix='')

Asserts that two URLs are the same, ignoring the order of query string parameters except for parameters with the same name. For example, /path/?x=1&y=2 is equal to /path/?y=2&x=1, but /path/?a=1&a=2 isn't equal to /path/?a=2&a=1.

SimpleTestCase.assertRedirects(response, expected_url, status_code=302, target_status_code=200, msg_prefix='', fetch_redirect_response=True)

Asserts that the response returned a status_code redirect status, redirected to expected_url (including any GET data), and that the final page was received with target_status_code.

If your request used the follow argument, the expected_url and target_status_code will be the url and status code for the final point of the redirect chain.

If fetch_redirect_response is False, the final page won't be loaded. Since the test client can't fetch external URLs, this is particularly useful if expected_url isn't part of your Django app.

Scheme is handled correctly when making comparisons between two URLs. If there isn't any scheme specified in the location where we are redirected to, the original request's scheme is used. If present, the scheme in expected_url is the one used to make the comparisons to.

SimpleTestCase.assertHTMLEqual(html1, html2, msg=None)

Asserts that the strings html1 and html2 are equal. The comparison is based on HTML semantics. The comparison takes following things into account:

  • Whitespace before and after HTML tags is ignored.
  • All types of whitespace are considered equivalent.
  • All open tags are closed implicitly, e.g. when a surrounding tag is closed or the HTML document ends.
  • Empty tags are equivalent to their self-closing version.
  • The ordering of attributes of an HTML element is not significant.
  • Boolean attributes (like checked) without an argument are equal to attributes that equal in name and value (see the examples).
  • Text, character references, and entity references that refer to the same character are equivalent.

The following examples are valid tests and don't raise any AssertionError:

self.assertHTMLEqual(
    '<p>Hello <b>&#x27;world&#x27;!</p>',
    '''<p>
        Hello   <b>&#39;world&#39;! </b>
    </p>'''
)
self.assertHTMLEqual(
    '<input type="checkbox" checked="checked" id="id_accept_terms" />',
    '<input id="id_accept_terms" type="checkbox" checked>'
)

html1 and html2 must contain HTML. An AssertionError will be raised if one of them cannot be parsed.

Output in case of error can be customized with the msg argument.

Changed in Django 4.0:

In older versions, any attribute (not only boolean attributes) without a value was considered equal to an attribute with the same name and value.

SimpleTestCase.assertHTMLNotEqual(html1, html2, msg=None)

Asserts that the strings html1 and html2 are not equal. The comparison is based on HTML semantics. See assertHTMLEqual() for details.

html1 and html2 must contain HTML. An AssertionError will be raised if one of them cannot be parsed.

Output in case of error can be customized with the msg argument.

SimpleTestCase.assertXMLEqual(xml1, xml2, msg=None)

Asserts that the strings xml1 and xml2 are equal. The comparison is based on XML semantics. Similarly to assertHTMLEqual(), the comparison is made on parsed content, hence only semantic differences are considered, not syntax differences. When invalid XML is passed in any parameter, an AssertionError is always raised, even if both strings are identical.

XML declaration, document type, processing instructions, and comments are ignored. Only the root element and its children are compared.

Output in case of error can be customized with the msg argument.

SimpleTestCase.assertXMLNotEqual(xml1, xml2, msg=None)

Asserts that the strings xml1 and xml2 are not equal. The comparison is based on XML semantics. See assertXMLEqual() for details.

Output in case of error can be customized with the msg argument.

SimpleTestCase.assertInHTML(needle, haystack, count=None, msg_prefix='')

Asserts that the HTML fragment needle is contained in the haystack once.

If the count integer argument is specified, then additionally the number of needle occurrences will be strictly verified.

Whitespace in most cases is ignored, and attribute ordering is not significant. See assertHTMLEqual() for more details.

SimpleTestCase.assertJSONEqual(raw, expected_data, msg=None)

Asserts that the JSON fragments raw and expected_data are equal. Usual JSON non-significant whitespace rules apply as the heavyweight is delegated to the json library.

Output in case of error can be customized with the msg argument.

SimpleTestCase.assertJSONNotEqual(raw, expected_data, msg=None)

Asserts that the JSON fragments raw and expected_data are not equal. See assertJSONEqual() for further details.

Output in case of error can be customized with the msg argument.

TransactionTestCase.assertQuerysetEqual(qs, values, transform=None, ordered=True, msg=None)

Asserts that a queryset qs matches a particular iterable of values values.

If transform is provided, values is compared to a list produced by applying transform to each member of qs.

By default, the comparison is also ordering dependent. If qs doesn't provide an implicit ordering, you can set the ordered parameter to False, which turns the comparison into a collections.Counter comparison. If the order is undefined (if the given qs isn't ordered and the comparison is against more than one ordered value), a ValueError is raised.

Output in case of error can be customized with the msg argument.

TransactionTestCase.assertNumQueries(num, func, *args, **kwargs)

Asserts that when func is called with *args and **kwargs that num database queries are executed.

If a "using" key is present in kwargs it is used as the database alias for which to check the number of queries:

self.assertNumQueries(7, using='non_default_db')

If you wish to call a function with a using parameter you can do it by wrapping the call with a lambda to add an extra parameter:

self.assertNumQueries(7, lambda: my_function(using=7))

You can also use this as a context manager:

with self.assertNumQueries(2):
    Person.objects.create(name="Aaron")
    Person.objects.create(name="Daniel")

Tagging tests

You can tag your tests so you can easily run a particular subset. For example, you might label fast or slow tests:

from django.test import tag

class SampleTestCase(TestCase):

    @tag('fast')
    def test_fast(self):
        ...

    @tag('slow')
    def test_slow(self):
        ...

    @tag('slow', 'core')
    def test_slow_but_core(self):
        ...

You can also tag a test case:

@tag('slow', 'core')
class SampleTestCase(TestCase):
    ...

Subclasses inherit tags from superclasses, and methods inherit tags from their class. Given:

@tag('foo')
class SampleTestCaseChild(SampleTestCase):

    @tag('bar')
    def test(self):
        ...

SampleTestCaseChild.test will be labeled with 'slow', 'core', 'bar', and 'foo'.

Then you can choose which tests to run. For example, to run only fast tests:

$ ./manage.py test --tag=fast

...\> manage.py test --tag=fast

Or to run fast tests and the core one (even though it's slow):

$ ./manage.py test --tag=fast --tag=core

...\> manage.py test --tag=fast --tag=core

You can also exclude tests by tag. To run core tests if they are not slow:

$ ./manage.py test --tag=core --exclude-tag=slow

...\> manage.py test --tag=core --exclude-tag=slow

test --exclude-tag has precedence over test --tag, so if a test has two tags and you select one of them and exclude the other, the test won't be run.

Testing asynchronous code

If you merely want to test the output of your asynchronous views, the standard test client will run them inside their own asynchronous loop without any extra work needed on your part.

However, if you want to write fully-asynchronous tests for a Django project, you will need to take several things into account.

Firstly, your tests must be async def methods on the test class (in order to give them an asynchronous context). Django will automatically detect any async def tests and wrap them so they run in their own event loop.

If you are testing from an asynchronous function, you must also use the asynchronous test client. This is available as django.test.AsyncClient, or as self.async_client on any test.

class AsyncClient(enforce_csrf_checks=False, raise_request_exception=True, **defaults)

AsyncClient has the same methods and signatures as the synchronous (normal) test client, with two exceptions:

  • In the initialization, arbitrary keyword arguments in defaults are added directly into the ASGI scope.

  • The follow parameter is not supported.

  • Headers passed as extra keyword arguments should not have the HTTP_ prefix required by the synchronous client (see Client.get()). For example, here is how to set an HTTP Accept header:

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

Using AsyncClient any method that makes a request must be awaited:

async def test_my_thing(self):
    response = await self.async_client.get('/some-url/')
    self.assertEqual(response.status_code, 200)

The asynchronous client can also call synchronous views; it runs through Django's asynchronous request path, which supports both. Any view called through the AsyncClient will get an ASGIRequest object for its request rather than the WSGIRequest that the normal client creates.

警告

If you are using test decorators, they must be async-compatible to ensure they work correctly. Django's built-in decorators will behave correctly, but third-party ones may appear to not execute (they will "wrap" the wrong part of the execution flow and not your test).

If you need to use these decorators, then you should decorate your test methods with async_to_sync() inside of them instead:

from asgiref.sync import async_to_sync
from django.test import TestCase

class MyTests(TestCase):

    @mock.patch(...)
    @async_to_sync
    async def test_my_thing(self):
        ...

Email services

If any of your Django views send email using Django's email functionality, you probably don't want to send email each time you run a test using that view. For this reason, Django's test runner automatically redirects all Django-sent email to a dummy outbox. This lets you test every aspect of sending email -- from the number of messages sent to the contents of each message -- without actually sending the messages.

The test runner accomplishes this by transparently replacing the normal email backend with a testing backend. (Don't worry -- this has no effect on any other email senders outside of Django, such as your machine's mail server, if you're running one.)

django.core.mail.outbox

During test running, each outgoing email is saved in django.core.mail.outbox. This is a list of all EmailMessage instances that have been sent. The outbox attribute is a special attribute that is created only when the locmem email backend is used. It doesn't normally exist as part of the django.core.mail module and you can't import it directly. The code below shows how to access this attribute correctly.

Here's an example test that examines django.core.mail.outbox for length and contents:

from django.core import mail
from django.test import TestCase

class EmailTest(TestCase):
    def test_send_email(self):
        # Send message.
        mail.send_mail(
            'Subject here', 'Here is the message.',
            'from@example.com', ['to@example.com'],
            fail_silently=False,
        )

        # Test that one message has been sent.
        self.assertEqual(len(mail.outbox), 1)

        # Verify that the subject of the first message is correct.
        self.assertEqual(mail.outbox[0].subject, 'Subject here')

As noted previously, the test outbox is emptied at the start of every test in a Django *TestCase. To empty the outbox manually, assign the empty list to mail.outbox:

from django.core import mail

# Empty the test outbox
mail.outbox = []

管理コマンド

Management commands can be tested with the call_command() function. The output can be redirected into a StringIO instance:

from io import StringIO
from django.core.management import call_command
from django.test import TestCase

class ClosepollTest(TestCase):
    def test_command_output(self):
        out = StringIO()
        call_command('closepoll', stdout=out)
        self.assertIn('Expected output', out.getvalue())

Skipping tests

The unittest library provides the @skipIf and @skipUnless decorators to allow you to skip tests if you know ahead of time that those tests are going to fail under certain conditions.

For example, if your test requires a particular optional library in order to succeed, you could decorate the test case with @skipIf. Then, the test runner will report that the test wasn't executed and why, instead of failing the test or omitting the test altogether.

To supplement these test skipping behaviors, Django provides two additional skip decorators. Instead of testing a generic boolean, these decorators check the capabilities of the database, and skip the test if the database doesn't support a specific named feature.

The decorators use a string identifier to describe database features. This string corresponds to attributes of the database connection features class. See django.db.backends.base.features.BaseDatabaseFeatures class for a full list of database features that can be used as a basis for skipping tests.

skipIfDBFeature(*feature_name_strings)

Skip the decorated test or TestCase if all of the named database features are supported.

For example, the following test will not be executed if the database supports transactions (e.g., it would not run under PostgreSQL, but it would under MySQL with MyISAM tables):

class MyTests(TestCase):
    @skipIfDBFeature('supports_transactions')
    def test_transaction_behavior(self):
        # ... conditional test code
        pass
skipUnlessDBFeature(*feature_name_strings)

Skip the decorated test or TestCase if any of the named database features are not supported.

For example, the following test will only be executed if the database supports transactions (e.g., it would run under PostgreSQL, but not under MySQL with MyISAM tables):

class MyTests(TestCase):
    @skipUnlessDBFeature('supports_transactions')
    def test_transaction_behavior(self):
        # ... conditional test code
        pass
Back to Top