--- title: "テストツール" version: 2.2 locale: ja source: https://docs.djangoproject.com/ja/2.2/topics/testing/tools/ canonical: https://djangodocs.dev/ja/2.2/topics/testing/tools/ --- # テストツール Django は、テストを書くのに便利なツールをいくつか提供しています。 ## テストクライアントテストクライアントは、ダミーのウェブブラウザとして振る舞う Python のクラスです。これを使えば、ビューと Django で作ったアプリケーションとの関係をプログラムから自動でテストできるようになります。テストクライアントでは、次のようなことができます。 - ある URL に対する GET および POST リクエストのシミュレートと、その結果の観察。低レベルの HTTP (レスポンスのヘッダーやステータスコードなど) から、ページのコンテンツまで、あらゆるレスポンスの内容を調査することができます。 - 一連の (好きな数の) リダイレクトを見て、その各ステップごとに URL とステータスコードをチェックする。 - 指定したリクエストが特定の Django テンプレートによってレンダリングされたとき、テンプレートのコンテキストが正しく特定の値を含んでいるかどうかをテストする。テストクライアントは [Selenium](http://seleniumhq.org/) や他の "ブラウザ内 (in-browser)" フレームワークの代替を目指すものではないことに注意してください。Django のテストクライアントの目的は別の点にあります。つまり、 - Django のテストクライアントは、正しいテンプレートがレンダリングされ、そのテンプレートが正しいコンテキストデータをちゃんと渡しているのかをチェックするために使います。 - [Selenium](http://seleniumhq.org/) などのブラウザー内フレームワークは、HTML の *レンダリング* や、Web ページの *振る舞い* 、つまり JavaScript の機能性をテストするために使います。また、Django はこれらのフレームワーク向けの特別なサポートも提供しています。この詳細については、[`LiveServerTestCase`](#django.test.LiveServerTestCase) のセクションを読んでください。包括的なテストスイートを実現するには、これら両タイプのテストを組み合わせて行うべきです。 ### 概要と簡単な例テストクライアントを使うには、`django.test.Client` からインスタンスを作り、次のように Web ページを取得します。 ``` >>> 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'>> c.get('/login/') ``` が、これは間違いです。 ``` >>> c.get('https://www.example.com/login/') ``` テストクライアントには、自分の Django プロジェクト以外の Web ページを取得する機能はありません。他の Web ページが必要な場合には、 [`urllib`](https://docs.python.org/3/library/urllib.html#module-urllib) などのPython のスタンダードライブラリモジュールを利用してください。 - URL を解決するとき、テストクライアントは [`ROOT_URLCONF`](/ja/2.2/ref/settings/#std-setting-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, json_encoder=DjangoJSONEncoder, **defaults)` インスタンスの作成には、引数は必要ありません。しかし、キーワード引数を使ってデフォルトヘッダーを指定することもできます。たとえば、リクエストごとに `User-Agent` HTTP ヘッダーを送信するには、次のようにします。 ``` >>> c = Client(HTTP_USER_AGENT='Mozilla/5.0') ``` [`get()`](#django.test.Client.get) や [`post()`](#django.test.Client.post) などに `extra` キーワード引数で与えられた値は、クラスコンストラクタに渡されたデフォルト値に優先します。 `enforce_csrf_checks` 引数を使うと、CSRF プロテクションのテストが実行できます (上の説明を参照)。 The `json_encoder` argument allows setting a custom JSON encoder for the JSON serialization that's described in [`post()`](#django.test.Client.post). > **Changed in Django 2.1** > > The `json_encoder` argument was added. `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_X_REQUESTED_WITH='XMLHttpRequest') ``` は、HTTP ヘッダー `HTTP_X_REQUESTED_WITH` を details ビューに送信します。これは、 [`django.http.HttpRequest.is_ajax()`](/ja/2.2/ref/request-response/#django.http.HttpRequest.is_ajax) メソッドを使ったコードパースのテストのための良い方法です。 > **CGI の仕様** > > `**extra` で送信されるヘッダーは、以下の [CGI](https://www.w3.org/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()`](https://docs.python.org/3/library/json.html#json.dumps) if it's a dict, list, or tuple. Serialization is performed with [`DjangoJSONEncoder`](/ja/2.2/topics/serialization/#django.core.serializers.json.DjangoJSONEncoder) by default, and can be overridden by providing a `json_encoder` argument to [`Client`](#django.test.Client). This serialization also happens for [`put()`](#django.test.Client.put), [`patch()`](#django.test.Client.patch), and [`delete()`](#django.test.Client.delete) requests. > **Changed in Django 2.1** > > The JSON serialization described above was added. In older versions, > you can call [`json.dumps()`](https://docs.python.org/3/library/json.html#json.dumps) on `data` before passing it to > `post()` to achieve the same thing. > **Changed in Django 2.2** > > The JSON serialization was extended to support lists and tuples. In > older versions, only dicts are serialized. 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 データを生成するのに使われます。たとえば `', '' ) ``` `html1` and `html2` must be valid 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.assertHTMLNotEqual(html1, html2, msg=None)` Asserts that the strings `html1` and `html2` are *not* equal. The comparison is based on HTML semantics. See [`assertHTMLEqual()`](#django.test.SimpleTestCase.assertHTMLEqual) for details. `html1` and `html2` must be valid 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()`](#django.test.SimpleTestCase.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 string are identical. XML declaration 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()`](#django.test.SimpleTestCase.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` one. 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. The passed-in arguments must be valid HTML. #### `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`](https://docs.python.org/3/library/json.html#module-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()`](#django.test.SimpleTestCase.assertJSONEqual) for further details. Output in case of error can be customized with the `msg` argument. #### `TransactionTestCase.assertQuerysetEqual(qs, values, transform=repr, ordered=True, msg=None)` Asserts that a queryset `qs` returns a particular list of values `values`. The comparison of the contents of `qs` and `values` is performed using the function `transform`; by default, this means that the `repr()` of each value is compared. Any other callable can be used if `repr()` doesn't provide a unique or helpful comparison. 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 values), 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. 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'`. > **Changed in Django 2.1** > > In older versions, tagged tests don't inherit tags from classes, and > tagged subclasses don't inherit tags from superclasses. For example, > `SampleTestCaseChild.test` is labeled only with `'bar'`. Then you can choose which tests to run. For example, to run only fast tests: ```console $ ./manage.py test --tag=fast ``` *Windows* ```doscon ...\> manage.py test --tag=fast ``` Or to run fast tests and the core one (even though it's slow): ```console $ ./manage.py test --tag=fast --tag=core ``` *Windows* ```doscon ...\> manage.py test --tag=fast --tag=core ``` You can also exclude tests by tag. To run core tests if they are not slow: ```console $ ./manage.py test --tag=core --exclude-tag=slow ``` *Windows* ```doscon ...\> manage.py test --tag=core --exclude-tag=slow ``` [`test --exclude-tag`](/ja/2.2/ref/django-admin/#cmdoption-test-exclude-tag) has precedence over [`test --tag`](/ja/2.2/ref/django-admin/#cmdoption-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. ## Email services If any of your Django views send email using [Django's email functionality](/ja/2.2/topics/email/), 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 simple list of all [`EmailMessage`](/ja/2.2/topics/email/#django.core.mail.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`](/ja/2.2/topics/email/#module-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](#emptying-test-outbox), 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()`](/ja/2.2/ref/django-admin/#django.core.management.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`](https://docs.python.org/3/library/unittest.html#unittest.skipIf) and [`@skipUnless`](https://docs.python.org/3/library/unittest.html#unittest.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`](https://docs.python.org/3/library/unittest.html#unittest.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.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 ```