Djangoアプリケーションのテスト¶

revision-up-to:	11321 (1.1) unfinished

今日の Web 開発者にとって、自動化されたテストはバグ潰しの工程で極めて有用なツールです。複数のテストを集めた テストスイート を使えば、Web開発におけるいくつもの問題を解決したり回避したりできます:

新たなコードを書く際、コードが期待通りに動作するかテストできます。

以前のコードを修正したりリファクタする場合、テストによって、コードの変更がアプリケーションに意図しない影響を及ぼさないか調べられます。

Web アプリケーションは、 HTTP レベルのリクエスト処理、フォームの検証と処理、そしてテンプレートレンダリングまで、複数のロジックレイヤから構成されています。そのため、Webアプリケーションのテストは複雑なタスクです。 Django のテスト実行フレームワークと関連ユーティリティを使えば、仮想的なリクエストを発行したり、テストデータを挿入したり、アプリケーションの出力を調べて、コードが期待通りに動作しているか検証したりできます。

しかも素晴らしいことに、テストはとても簡単なのです。

このドキュメントは前後半の 2 つの節に別れています。前半では Django におけるテストの書き方を、後半ではテストの実行方法を説明します。

テストを書く¶

Django でテストを書く方法は主に 2 つあり、それぞれ Python の標準ライブラリについてくる二つのテストフレームワークに対応しています。フレームワークは以下の 2 つです:

doctest – 関数やクラスの docstring (ドキュメンテーション文字列) に埋め込まれたテストで、例えば以下のように Python の対話インタプリタセッションを模した方法で書かれています:
def my_func(a_list, idx):
    """
    >>> a = ['larry', 'curly', 'moe']
    >>> my_func(a, 0)
    'larry'
    >>> my_func(a, 1)
    'curly'
    """
    return a_list[idx]
ユニットテスト (unit test) – 以下の例のように、テストを unittest.TestCase` のサブクラスのメソッドとして表現したものです:
import unittest

class MyFuncTestCase(unittest.TestCase):
    def testBasic(self):
        a = ['larry', 'curly', 'moe']
        self.assertEquals(my_func(a, 0), 'larry')
        self.assertEquals(my_func(a, 1), 'curly')

好みに応じて、どちらのテストを使ってもかまいませんし、両方のテストを組み合わせてもかまいません。また、後でほんの少しだけ説明しますが、他のテストフレームワークを使っても構いません。

doctest を書く¶

doctest は、Python の標準モジュール、 doctest によるテストです。 doctest は docstring (ドキュメンテーション文字列) から、 Python の対話インタプリタセッションの形式をとる部分を探し出して実行します。 doctest の詳しい構造についての解説はこのドキュメントの範囲を超えた話なので、公式ドキュメントを参照してください。

docstring とは?

docstring の詳しい説明 (と、効果的な docstring の書き方) は、 PEP 257 (訳注: PEP 257 の和訳は http://www.python.jp/doc/contrib/peps/pep-0257.txt にあります) に書かれています:

docstring とは、モジュールや関数、クラス、メソッド定義のブロック中の先頭に置かれた文字列リテラルです。 docstring を定義すると、オブジェクトの __doc__ という特殊な属性になります。

例えば、下の関数には、関数の説明の入った docstring があります:

def add_two(num):
    "引数に指定した数に 2 を加えて返します。"
    return num + 2

テストはそれ自体素晴らしいドキュメントになることも多いので、テストをそのまま docstring に入れておけば、ドキュメント化とコードのテストの 両方を 効率的に行えます。

テストランナは、 Django アプリケーションの中の以下のファイルから doctest を探して実行します:

models.py ファイル。モジュールレベル、かつ/またはモデルレベルの doctest を記述します。一般には、アプリケーションレベルの doctest はモジュールの docstring として記述し、モデルレベルの docstring はモデルクラスの docstring として記述します。

アプリケーションディレクトリ、すなわち models.py の入ったディレクトリ下に置かれた tests.py という名前のファイル。このファイルは、モデルに関係しないような doctest を書きたい場合のフックとして使えます。

モデル定義で doctest を使った例を示します:

# models.py

from django.db import models

class Animal(models.Model):
    """
    鳴き声から動物を調べるテスト

    # 動物インスタンスを生成する
    >>> lion = Animal.objects.create(name="lion", sound="roar")
    >>> cat = Animal.objects.create(name="cat", sound="meow")

    # speak() を呼び出す
    >>> lion.speak()
    'The lion says "roar"'
    >>> cat.speak()
    'The cat says "meow"'
    """

    name = models.CharField(max_length=20)
    sound = models.CharField(max_length=20)

    def speak(self):
        return 'The %s says "%s"' % (self.name, self.sound)

テストを実行すると、テストユーティリティは上の docstring を探し出して、Python の対話セッションに見える部分を検出し、そこに書かれた命令を実行して、docstring に書かれた結果と実際の実行結果が一致するかどうかを確かめます。

モデルテストの場合、テストランナが独自にテストデータベースを作成します。すなわち、データベースに対してアクセスするテスト – 例えば、モデルインスタンスを生成して保存するようなテスト – が、実運用のためのデータベースに影響を及ぼすことはありません。 doctest はいずれも「白紙状態」、すなわち、各モデルのデータベーステーブルが空の状態で実行されます (詳しくは、後述のフィクスチャの節を参照してください) 。この機能を使うには、 Django がデータベースに接続するときのユーザに CREATE DATABASE の権限を持たせておかねばならないので注意してください。

doctest の詳しい動作原理は、標準ドキュメントの doctest の項を参照してください。

ユニットテストを書く¶

Django の単体テストもまた、doctest と同様、標準ライブラリモジュールの unittest を使います。このモジュールは、 doctest とは違った、クラスベースのやり方でテストを定義します。

doctest と同様、 Django のテストランナは、以下の二つの場所からユニットテストを探します:

models.py ファイル。テストランナはこのモジュールから unittest.TestCase のサブクラスを探します。

アプリケーションディレクトリ、すなわち models.py の入ったディレクトリ下に置かれた tests.py という名前のファイル。上と同様に、テストランナはこのモジュールから unittest.TestCase のサブクラスを探します。

以下の unittest.TestCase のサブクラスは、前節の doctest と同じテストを実現しています:

import unittest
from myapp.models import Animal

class AnimalTestCase(unittest.TestCase):

    def setUp(self):
        self.lion = Animal.objects.create(name="lion", sound="roar")
        self.cat = Animal.objects.create(name="cat", sound="meow")

    def testSpeaking(self):
        self.assertEquals(self.lion.speak(), 'The lion says "roar"')
        self.assertEquals(self.cat.speak(), 'The cat says "meow"')

テストを実行すると、テストユーティリティはデフォルトの動作として、 models.py と tests.py に入っている全てのテストケース (つまり unittest.TestCase のサブクラス) を捜し出し、そこからテストスイートを自動的に構築して、スイートを実行します。

開発バージョンの Django には、あるモジュールのテストスイートを定義する方法をもう一つ提供しています: models.py や tests.py で suite() メソッドを定義している場合、 Django のテストランナはこのメソッドを使ってテストスイートを構築します。この仕様は、ユニットテストにおいておすすめのテストスイート構築方法に従っています。複雑なテストスイートの構築方法についての詳細は Python のドキュメントを参照してください。

unittest の詳細は標準ライブラリドキュメントの unittest の項を参照してください。

どちらのテストを使うべきか¶

Django は標準的な Python テストフレームワークの両方をサポートしているので、どちらを選ぶかは、開発者個々人の好み次第です。もちろん、両方を同時に使ってもかまいません。

とはいえ、テストを初めて書く開発者にとっては、この選択は混乱のもとになるでしょう。そこで、どちらのテストを使うべきかを決める手がかりになるよう、 doctest と単体テストの主な違いについて示します:

そこそこ Python に慣れているなら、 doctest の方がより「Python的 (pythonic)」に感じることでしょう。 doctest はテストをできるだけ楽に書けるように設計されているので、クラスやメソッドを書くときのオーバヘッドがほとんどありません。単に docstring にテストを書くだけでよいのです。それに、モジュールに対してドキュメントを自動生成させられるという利点もあります。つまり、 doctest を上手に書けば、ドキュメント作成とテストを同時に片付けられて一石二鳥、というわけです。

また、テストにまだ慣れていない開発者は、 doctest を使った方が早くテストについて学べることでしょう。

Java での開発経験のある開発者なら、 unittest フレームワークはとても理解しやすいはずです。 unittest は Java の JUnit に影響を受けているので、他の言語で JUnit から派生したテストフレームワークを使ったことがあるのなら、unittest はかなりしっくりくるはずです。

同じコードを含むような一連のテストを書くときには、 unittest フレームワークのクラスとメソッドによる設計が気に入るでしょう。共通のタスクを抽象化して、メソッド化できるからです。また、 unittest フレームワークは unittest はテストの初期化／終了処理のルーチンをサポートしているので、テストケースを実行するときの環境を高い水準でコントロールできます。

繰り返しになりますが、(一つのアプリケーションの中であっても) 両方のシステムを並べて使えることを忘れないでください。どちらのテストシステムにも、状況に応じて適した部分があるので、大抵のプロジェクトでは、最終的には両方のテストシステムを使うことになるものです。

テストを実行する¶

テストを実行するには、プロジェクトの manage.py ユーティリティを使います:

$ ./manage.py test

特定のアプリケーションに対してテストを実行したければ、コマンドラインにアプリケーションの名前を追加します。例えば、 INSTALLED_APPS に myproject.polls と myproject.animals というアプリケーションが入っており、 animals の単体テストを実行したいだけなら、以下のようにします:

$ ./manage.py test animals

animals ではなく、 myproject.animals なので注意してください。

実行したいテストを選べるようになりました。

単体テストを実行する際、どのテストを実行するかを指定できます。あるアプリケーション用のテストケースを実行する場合 (例えば、上で解説した AnimalTestCase の場合) は、コマンドラインにテストケースの名前を追加してください:

$ ./manage.py test animals.AnimalTestCase

テストケース中の 個別の テストメソッドを実行したければ、メソッド名を指定してください:

$ ./manage.py test animals.AnimalTestCase.testFluffyAnimals

テストデータベース¶

データベースを必要とするテスト (モデルのテスト) に、「本番の (実運用環境の)」データベースは必要ありません。テストの際には、空の別のデータベースが作成されます。

テストがパスするか失敗するかに関わらず、テストデータベースは全てのテストを実行し終えると消去されます。

デフォルトでは、テストデータベースの名前は、 DATABASE_NAME に指定したデータベース名の前に test_ を付けたものです。 SQLite データベースエンジンを使っている場合、デフォルトではテストをメモリ上のデータベースで行います(すなわち、データベースをメモリ上に生成し、ファイルシステムを全く経由しません！) 。テストデータベースの名前をデフォルト意外の値にしたければ、 TEST_DATABASE_NAME 設定を使って指定します。

テスト用に別のデータベースを使うことを除けば、テストランナは設定ファイルのデータベースに関する他の設定、 DATABASE_ENGINE, DATABASE_USER, DATABASE_HOST などをそのまま使います。テストデータベースは DATABASE_USER の権限で作成されるので、このユーザは新たに生成されたデータベースを操作する権限を備えていなければなりません。

リリースノートを参照してください

テスト用データベースの文字セットエンコーディング設定を細かく調整したいのなら、 TEST_DATABASE_CHARSET 設定を使ってください。 MySQL を使っているなら、 TEST_DATABASE_COLLATION でテストデータベースで使うコレーション(collation) を指定できます。これらの設定については、 settings ファイルのドキュメントを参照してください。

その他のテスト条件¶

設定ファイル上の DEBUG の値にかかわらず、 Django は全てのテストを DEBUG=False で動かします。これは、テストコードに実運用環境と同じ内容を出力させるためです。

テストプログラムの出力を理解する¶

テストを実行すると、テストランナ自体が大量に出力するメッセージに出くわすでしょう。コマンドラインの verbosity オプションを使えば、メッセージの詳細レベルを制御できます:

Creating test database...
Creating table myapp_animal
Creating table myapp_mineral
Loading 'initial_data' fixtures...
No fixtures found.

前の節でも述べたように、このメッセージは、テストランナがテストデータベースを作成したことを示しています。

テストデータベースが生成されると、 Django はテストを実行します。全てのテストにパスすると、最後には以下のようなメッセージが表示されます:

----------------------------------------------------------------------
Ran 22 tests in 0.221s

OK

一方、失敗したテストがあると、失敗したテストに関する詳しい情報が表示されます:

======================================================================
FAIL: Doctest: ellington.core.throttle.models
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/dev/django/test/doctest.py", line 2153, in runTest
    raise self.failureException(self.format_failure(new.getvalue()))
AssertionError: Failed doctest test for myapp.models
  File "/dev/myapp/models.py", line 0, in models

----------------------------------------------------------------------
File "/dev/myapp/models.py", line 14, in myapp.models
Failed example:
    throttle.check("actor A", "action one", limit=2, hours=1)
Expected:
    True
Got:
    False

----------------------------------------------------------------------
Ran 2 tests in 0.048s

FAILED (failures=1)

エラー出力の詳細はこのドキュメントの範囲を超えるので解説はしませんが、ほとんど直感的に理解できる内容のはずです。詳しくは、 Python の unittest ライブラリのドキュメントを参照してください。

スクリプトのリターンコードは失敗したテストや出力のおかしかったテストの総数です。全てのテストにパスしていれば、リターンコードは 0 です。この仕様は、テストランナをシェルスクリプト上で動かしたり、テストが成功したかどうかをテストランナのレベルで調べたい場合に便利です。

テスト用のツール¶

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

テストクライアント¶

テストクライアント (test client) は、簡単なダミーブラウザとして動作する Python のクラスです。テストクライアントを使うと、ビューをテストしたり、プログラムを使ってDjango で作られたアプリケーションとやりとりできます。

テストクライアントを使ってできることをいくつか挙げましょう:

ある URL に対する GET や POST をシミュレートでき、低水準の HTTP (レスポンスヘッダや状態コード) 情報から、ページの内容まで、リクエストに対するレスポンスの全てを調べられます。

特定の URL に対して正しいビューが呼び出されるかどうかを調べられます。

特定のリクエストに対して、特定のテンプレートを使ったレンダリングが行われ、その際に特定の値が入ったコンテキストが使われているかどうかを調べられます。

テストクライアントは Twill や Selenium やその他のブラウザ自動化フレームワークを置き換えようとするものではありません。 Django のテストクライアントはもっと別の部分に焦点を当てているのです。すなわち:

正しいビューが呼び出され、ビューが正しいコンテキストデータを生成しているかどうかは、 Django のテストクライアントを使って調べてください。

Twill や Selenium は、 レンダリング済みの HTML や、 JavaScript の機能のような Web ページの ビヘイビア のテストに使ってください。

網羅的なテストスイートでは、両方のタイプのテストを組み合わせて使うはずです。

テストの概要と簡単な例¶

テストクライアントを使うには、 django.test.client.Client をインスタンス化して、 Web ページを取得します:

>>> from django.test.client import Client
>>> c = Client()
>>> response = c.post('/login/', {'username': 'john', 'password': 'smith'})
>>> response.status_code
200
>>> response = c.get('/customer/details/')
>>> response.content
'<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 ...'

上の例でわかるように、 Client は Python 対話インタプリタのセッション中でもインスタンス化できます。

テストクライアントの動作には重要な点がいくつかあります:

テストクライアントを実行するために Web サーバを起動する必要は ありません 。実際、 Web サーバがまったく動いていなくても、テストは何の問題もなく実行できるのです。というのも、テストクライアントは HTTP 通信のオーバヘッドを回避して、 Django フレームワークに直接アクセスしているからです。このからくりによって、ユニットテストを高速に実行できます。
ページを取得するときには、ドメインを含まない パス部分だけ を指定するよう気をつけてください。例えば、以下の呼び出し:
>>> c.get('/login/')
は正しいですが、次の呼び出し:
>>> c.get('http://www.example.com/login/')
は正しくありません。

Django のプロジェクトから生成されていない Web ページは、テストクライアントで取得できません。Django 以外の Web ページを取得したければ、 urllib や urllib2 のような Python 標準ライブラリを使ってください。
テストクライアントは URL の解決に ROOT_URLCONF に指定された URLconf を使います。

上の例は Python の対話インタプリタ中でも動作しますが、一部のテンプレート関連の機能などは テストの実行中だけ でしか使えません。

というのも、 Django のテストランナは、あるビューでどのテンプレートがロードされるかを決定するためにちょっとした黒魔術的なコードを使っているからです。この黒魔術 (実際には、メモリ上のテンプレートシステムに対するパッチ) は、テスト実行時にしか適用されません。

リクエスト生成¶

リクエストの生成には、 django.test.client.Client クラスを使います。 Client は引数なしで生成します。:

class Client¶

Client のインスタンスからは、以下のメソッドを呼び出せます:

get(path, data={}, follow=False, **extra)¶

path に対する GET リクエストを行い、 Response オブジェクトを返します。 Response オブジェクトについては後で説明します。

引数 data は辞書オブジェクトで、キー／値のペアが GET データのペイロードの生成に使われます。例えば:

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

は、以下のような GET リクエストの送信と同じです:

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

The extra keyword arguments parameter can be used to specify headers to be sent in the request. For example:

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

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

リリースノートを参照してください

If you already have the GET arguments in URL-encoded form, you can use that encoding instead of using the data argument. For example, the previous GET request could also be posed as:

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

If you provide URL both an encoded GET data and a data argument, the data argument will take precedence.

If you set follow to True the client will follow any redirects and a redirect_chain attribute will be set in the response object containing tuples of the intermediate urls and status codes.

If you had an url /redirect_me/ that redirected to /next/, that redirected to /final/, this is what you’d see:

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

post(path, data={}, content_type=MULTIPART_CONTENT, follow=False, **extra)¶

path に対する POST リクエストを行い、 Response オブジェクトを返します。

引数 data は辞書オブジェクトで、キー／値のペアが POST データのペイロード生成に使われます。例えば:

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

は、以下のパス:

/login/

への POST リクエストで、以下の POST データ:

name=fred&passwd=secret

を伴います。

content_type を指定した場合 (例えば XML ペイロードの場合には text/xml)、引数 data の中身は POST リクエストそのままで送信され、 Content-Type ヘッダに content_type の値を使います。

content_type を指定しなければ、 data の中身は multipart/form-data で送信されます。この場合、 data の中のキー／値のペアは、マルチパートメッセージにエンコードされ、 POST データのペイロード生成に使われます。

あるキーに対して複数の値を提出 (submit) する場合 (例えば、 <select multiple> の選択結果を指定する場合など) は、キーに対する値をリストやタプルにしてください。例えば、choices という名前のフィールドから 3 つの行を選択して提出したければ:

{'choices': ('a', 'b', 'd')}

のようにします。

ファイルの送信には特別な扱いが必要です。ファイルの POST を行う場合、以下のように、ファイル名フィールドの名前をキーに、アップロードしたいファイルのファイルハンドルを値に設定します:

>>> c = Client()
>>> f = open('wishlist.doc')
>>> c.post('/customers/wishes/', {'name':'fred', 'attachment':f})
>>> f.close()

(attachment という名前には特に意味はありません。ファイルを処理するコードで使いたい名前を指定してください)

送信するファイルのハンドルは、 post() 後に手動で閉じねばならないので注意してください。

The extra argument acts the same as for Client.get().

リリースノートを参照してください

If the URL you request with a POST contains encoded parameters, these parameters will be made available in the request.GET data. For example, if you were to make the request:

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

... the view handling this request could interrogate request.POST to retrieve the username and password, and could interrogate request.GET to determine if the user was a visitor.

If you set follow to True the client will follow any redirects and a redirect_chain attribute will be set in the response object containing tuples of the intermediate urls and status codes.

head(path, data={}, follow=False, **extra)¶

リリースノートを参照してください

Makes a HEAD request on the provided path and returns a Response object. Useful for testing RESTful interfaces. Acts just like Client.get() except it does not return a message body.

If you set follow to True the client will follow any redirects and a redirect_chain attribute will be set in the response object containing tuples of the intermediate urls and status codes.

options(path, data={}, follow=False, **extra)¶

リリースノートを参照してください

Makes an OPTIONS request on the provided path and returns a Response object. Useful for testing RESTful interfaces.

If you set follow to True the client will follow any redirects and a redirect_chain attribute will be set in the response object containing tuples of the intermediate urls and status codes.

The extra argument acts the same as for Client.get().

put(path, data={}, content_type=MULTIPART_CONTENT, follow=False, **extra)¶

リリースノートを参照してください

Makes an PUT request on the provided path and returns a Response object. Useful for testing RESTful interfaces. Acts just like Client.post() except with the PUT request method.

If you set follow to True the client will follow any redirects and a redirect_chain attribute will be set in the response object containing tuples of the intermediate urls and status codes.

delete(path, follow=False, **extra)¶

リリースノートを参照してください

Makes an DELETE request on the provided path and returns a Response object. Useful for testing RESTful interfaces.

If you set follow to True the client will follow any redirects and a redirect_chain attribute will be set in the response object containing tuples of the intermediate urls and status codes.

The extra argument acts the same as for Client.get().

login(**credentials)¶

リリースノートを参照してください

Django の認証システムを使っていて、ログイン済みのユーザを扱う必要がある場合、テストクライアントの login() メソッドを使えば、サイトへログインするユーザをシミュレートできます。

このメソッドを呼び出すと、テストクライアントはログインに必要なクッキーとセッションデータを持つようになり、テスト対象のビューのうち、ログインの必要なテストをパスできるようになります。

credentials 引数の形式は、使っている認証バックエンドによって変わります (認証バックエンドは AUTHENTICATION_BACKENDS で設定します)。 Django が提供している標準の認証バックエンド (ModelBackend) を使う場合、 credentials にはユーザのユーザ名とパスワードをキーワー引数で指定します:

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

# これでログイン保護されたビューに入れるようになりました。

認証バックエンドを変えた場合、このメソッドは違った認証情報を要求するかもしれません。その場合、 login() は、認証バックエンドの authenticate() メソッドが必要とする認証情報をそのまま要求します。

login() は、指定した認証情報が承認され、ログインに成功した場合に True を返します。

このメソッドを使うには、事前にユーザを登録しておかねばなりません。上で説明したように、テストランナはテストデータベースを使ってテストを実行するので、デフォルトではユーザが登録されていません。そのため、運用環境で使えるユーザはテスト環境では使えないのです。テストスイートの一環として、手動で (Django のモデル API を使って) ユーザを作成するか、フィクスチャでユーザを登録してください。 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.

logout()¶

Django の認証システムを使っている場合、 logout() メソッドで、サイトからユーザをログアウトさせる効果をシミュレートできます。

このメソッドを呼び出すと、テストクライアントはクッキーとセッションデータを全て消去して、デフォルトの状態に戻します。それ以降のリクエストは、ビューからは AnonymousUser から送信されたリクエストとみなされます。

レスポンスのテスト¶

get() および post() メソッドは、いずれも Response オブジェクトを返します。 Response オブジェクトは Django のビューが返す HttpResponse オブジェクトと同じ ではありません 。このオブジェクトは検証用のテストコード作成に便利なデータをいくつか備えています。

Response オブジェクトには以下のようなプロパティがあります:

class Response¶

client¶: レスポンス要求の生成に使われたテストクライアントです。

content¶: レスポンスの本体部分 (body) です。ビューがレンダリングによって生成した最終的なページコンテンツか、エラーメッセージです。

context¶

レスポンスのページコンテンツのレンダに使われた Context オブジェクトです。

複数のテンプレートを使ってレンダリングを行った場合、 context は Context オブジェクトをレンダリングで使った順に並べたリストです。

リリースノートを参照してください

Regardless of the number of templates used during rendering, you can retrieve context values using the [] operator. For example, the context variable name could be retrieved using:

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

request¶: レスポンスを得るために使用したリクエストデータです。

status_code¶: レスポンスの HTTP 状態コードです。全ての HTTP 状態コードのリストは RFC2616 を参照してください。

template¶

最終的なページコンテンツのレンダリングに使われた Template のインスタンスです。テンプレートをファイルからロードした場合、テンプレートのファイル名を template.name で調べられます ('admin/index.html' のような形式の文字列です)。

複数のテンプレートをレンダリングしている場合 (例えばテンプレートの継承を使っている場合)、 template はレンダリング順に並んだ Template オブジェクトのリストです。

また、レスポンスオブジェクトを辞書のように扱っても、HTTPヘッダに設定された値にアクセスできます。例えば、レスポンスのコンテンツタイプは response['Content-Type'] でアクセスできます。

例外¶

テストクライアントのアクセス先のビューが例外を送出するような場合、テストケース内で例外にアクセスできます。例外のテストを行うには、通常の try...catch ブロックか、 unittest.TestCase.assertRaises() を使います。

ただし、 Http404 や PermissionDenied, SystemExit といった例外はテストケースからアクセスできません。 Django はこれらの例外を内部的に捕捉して、対応する適切な HTTP 応答コードに変換してしまうからです。これらの例外に対しては、 response.status_code のチェックで対応してください。

セッションの永続性¶

テストクライアントの動作はステートフルです。あるレスポンスにクッキーが入っていると、クッキーはテストクライアント中に保存され、それ以降の get() や post() リクエストで使われます。

テストクライアントは、クッキーの有効期限ポリシを守りません。クッキーを期限切れにしたければ、該当クッキーを client.cookies から手動で削除するか、新たな Client インスタンスを生成してください (全てのクッキーを除去します)。

テストクライアントには、永続セッション情報 (persistent state information) を保存するためのプロパティが二つあります。これらのプロパティは、必要に応じてテスト条件の一部として検査できます。

Client.cookies¶: Python の SimpleCookie 型のオブジェクトで、全てのクライアントクッキーの現在値が入っています。詳しくは Cookie モジュールのドキュメントを参照してください。

Client.session¶: セッション情報の入った辞書ライクなオブジェクトです。詳しくはセッションのドキュメントを参照してください。

ユニットテストの例¶

テストクライアントを使った簡単なユニットテストを以下に示します:

import unittest
from django.test.client import Client

class SimpleTest(unittest.TestCase):
    def setUp(self):
        # unittest を使う場合、毎回 Client を生成する必要があります。
        self.client = Client()

    def test_details(self):
        # GET リクエストを発行します。
        response = self.client.get('/customer/details/')

        # レスポンスが 200 OK であるか調べます。
        self.failUnlessEqual(response.status_code, 200)

        # レンダリングされるコンテキストの customers の長さが 5 である
        # か確かます。
        self.failUnlessEqual(len(response.context['customers']), 5)

TestCaseクラス¶

Normal Python unit test classes extend a base class of unittest.TestCase. Django provides an extension of this base class:

class TestCase¶

このクラスは、Web サイトのテスト時に便利な機能をいくつか追加しています。

通常のユニットテストを unittest.TestCase から Django 独自の TestCase に移行するのは簡単で、単にベースクラスを unittest.TestCase から django.test.TestCase に変更するだけです。 django.test.TestCase は、標準の Python ユニットテスト機能はそのままに、さらに便利な機能を提供しています。

リリースノートを参照してください

class TransactionTestCase¶

Django TestCase classes make use of database transaction facilities, if available, 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 the effects of transaction commit and rollback cannot be tested by a Django TestCase class. If your test requires testing of such transactional behavior, you should use a Django 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 before the test runs by truncating all tables and reloading initial data. 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 and reload initial data at the beginning of a test. Instead, it encloses the test code in a database transaction that is rolled back at the end of the test. It also prevents the code under test from issuing any commit or rollback operations on the database, to ensure that the rollback at the end of the test restores the database to its initial state. In order to guarantee that all TestCase code starts with a clean database, the Django test runner runs all TestCase tests first, before any other tests (e.g. doctests) that may alter the database without restoring it to its original state.

When running on a database that does not support rollback (e.g. MySQL with the MyISAM storage engine), TestCase falls back to initializing the database by truncating tables and reloading initial data.

Note

The TestCase use of rollback to un-do the effects of the test code may reveal previously-undetected errors in test code. For example, test code that assumes primary keys values will be assigned starting at one may find that assumption no longer holds true when rollbacks instead of table truncation are being used to reset the database. Similarly, the reordering of tests so that all TestCase classes run first may reveal unexpected dependencies on test case ordering. In such cases a quick fix is to switch the TestCase to a TransactionTestCase. A better long-term fix, that allows the test to take advantage of the speed benefit of TestCase, is to fix the underlying test problem.

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

リリースノートを参照してください

TestCase.client¶

django.test.TestCase クラスのインスタンス内に入っているテストケースは全て、デフォルトのテストクライアントにアクセスできます。このテストクライアントは self.client で参照できます。テストクライアントはテストごとに再生成されるので、テスト間でクッキーのような状態情報が継承される心配はありません。

例えば、以下のコード:

import unittest
from django.test.client import Client

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

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

では、各テストで Client をインスタンス化していますが、実際は次のコードのように、 self.client を参照するだけでよいのです:

from django.test import TestCase

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

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

フィクスチャの読み込み¶

TestCase.fixtures¶

データベースがバックにあるウェブサイトのテストで、データベース上に何もデータが入っていなければあまり意味はありません。データベースにテストデータを入れやすくするために、 Django の独自 TestCase クラスは フィクスチャ (fixture) の読み込み機能を提供しています。

フィクスチャとは、一群のデータを Django がデータベースに取り込める形式にしたものです。例えば、ユーザアカウントを持つようなサイトを作っている場合、テスト中は仮のユーザアカウントの入ったフィクスチャを作り、データベースに入れておくと便利です。

最も素直なフィクスチャの作成方法は、 manage.py dumpdata コマンドを使うというものです。 dumpdata を使うにはデータベースに既に何らかのデータが入っていなければなりません。詳しくは dumpdata のドキュメント を参照してください。

Note

manage.py syncdb を実行したことがあるなら、あなたの知らないうちにフィクスチャは使われています。最初に syncdb を実行したときに、 Django は initial_data という名前のフィクスチャをインストールします。このメカニズムを使えば、 (カテゴリのデフォルトセットのような) 新たなデータセットをデータベースに組み込めます。

initial_data 以外の名前のフィクスチャは、 django-admin.py loaddata で手動で組み込めます。

単体テストでフィクスチャを使う場合、フィクスチャを作成して Django のプロジェクトディレクトリ下に置き、 dhango.test.TestCase のサブクラスの fixtures クラス属性を指定します:

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

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

    def setUp(self):
        # 従来通りのテスト定義

    def testFluffyAnimals(self):
        # フィクスチャを使うテスト

ユニットテストは、以下のように動作します:

テストケースの開始時で、かつ setUp() の実行前に、 Django はデータベースを一掃して、データベースを syncdb 直後の状態に戻します。

次に、テストケースクラスに指定した全てのフィクスチャをインストールします。上の例では、 mammals という名前の JSON フィクスチャと、 birds という名前のフィクスチャがインストールされます。フィクスチャの定義とインストールに関する詳細は loaddata のドキュメント を参照してください。

このフラッシュ／ロードの作業はテストケースの実行毎に繰り返されるので、テストの結果が他のテストや以前に実行したテストの影響を受けたり、テストの順番に左右されることはありません。

URLconf の設定¶

リリースノートを参照してください

TestCase.urls¶

アプリケーションでビューを定義している場合、テストクライアントを使ってビューを検査するテストを組み込みたいことがあるでしょう。しかし、エンドユーザはアプリケーションのビューを自分の好きな URL でデプロイできるので、テストを行う際には、ビューが特定の URL でアクセスできると期待してはなりません。

テスト用の URL 空間を指定するために、 django.test.TestCase はテストスイート実行中に使われる URLconf をカスタマイズできる仕組みを提供しています。 TestCase インスタンスに urls 属性を指定しておくと、 TestCase はその値をテスト実行中だけ ROOT_URLCONF に使います。

使い方を示しましょう:

from django.test import TestCase

class TestMyViews(TestCase):
    urls = 'myapp.test_urls'

    def testIndexPageView(self):
        #  ``Client`` を使ってビューをテストする

このテストケースは、ケースの実行中だけ、 myapp.test_urls を URLconf として使います。

メール送信箱の内容抹消¶

リリースノートを参照してください

Django 独自の TestCase クラスを使うと、テストランナは各テストケースの開始時にメールの送信箱に入っている内容を消去します。

テスト中のメールサービスの詳細はメールサービスを参照してください。

アサーション¶

リリースノートを参照してください

通常の Python unittest.TestCase クラスが備えている assertTrue や assertEquals のようなアサーションメソッドと同様、 Django 独自の TestCase クラスでも Web アプリケーションをテストする上で便利な様々な独自のアサーションメソッドを提供しています。

TestCase.assertContains(response, text, count=None, status_code=200)¶: status_code に指定した状態コードで Response インスタンスが生成され、レスポンスのコンテンツ内に text が入っているかどうか調べるアサーションです。 count を指定すると、 text は正確に count 回出現せねばなりません。

TestCase.assertNotContains(response, text, status_code=200)¶: status_code に指定した状態コードで Response インスタンスが生成され、レスポンスのコンテンツ内に text が入っていないことを確認するアサーションです。

TestCase.assertFormError(response, form, field, errors)¶

form に指定したフォーム上のフィールド field で、 errors に指定したエラーリストと同じエラーが送出されるかどうか調べるアサーションです。

form はテンプレートコンテキスト上の Form インスタンスの名前です。

field はフォーム内のフィールドの名前です。 field の値が None であれば、非フィールドエラー (特定のフィールドに関連付けられていない、 form.non_field_errors() でアクセスできるエラー) がチェックされます。

errors はエラー文字列か、エラー文字列のリストです。フォームの検証結果として返されるのと同じ形式です。

assertTemplateUsed(response, template_name)¶

template_name に指定したテンプレートがレスポンスのレンダリングに使われていることを確認するアサーションです。

template_name は 'admin/index.html' のような文字列です。

assertTemplateNotUsed(response, template_name)¶: template_name に指定したテンプレートがレスポンスのレンダリングに使われて いない ことを確認するアサーションです。

assertRedirects(response, expected_url, status_code=302, target_status_code=200)¶

レスポンスが status_code に指定したリダイレクト状態コードを持ち、かつ expected_url へのリダイレクトを指示しており、さらにリダイレクト先の内容を HTTP 状態コード 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.

メールサービス¶

リリースノートを参照してください

ビューが Django のメールサービスを使っている場合、ビューをテストするたびにメールが送信されてほしくはないでしょう。 Django のテストランナは、テスト中に Django から送信されたすべてのメールをダミーの送信箱に振り分けます。これによって、送信したメールの数から、各メールのメッセージに至るまで、メール送信機能のすべてを (実際にメールを送らずに) テストできます。

Django は、テストフレームワークを初期化する際、通常の SMTPConnection クラスをダミーの SMTPConnection 実装に切替えます (Django の外部のメール送信機構、例えば Django を動かしているホストで動いているメールサーバには一切影響を及ぼしません)。

django.core.mail.outbox¶

テストの実行中、 Django から送信されたメールは djnago.core.mail.outbox に保存されます。 djnago.core.mail.outbox はその時点で送信された全ての EmailMessage インスタンスからなるリストで、テスト時以外には存在しません。このダミー送信箱は、テストのセットアップ時に、ダミーの SMTPConnection と組で初期化されます。テストが終了すると、通常の SMTPConnection が復帰し、ダミー送信箱は削除されます。

The outbox attribute is a special attribute that is created only when the tests are run. 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.

django.core.mail.outbox を調べて、メール送信数やメールの内容をチェックするコード例を以下に示します:

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.',
            '[email protected]', ['[email protected]'],
            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')

前節で述べたように、テスト用の送信箱の内容は TestCase 内の各テストケースの開始時点で抹消されます。手動で送信箱の内容を空にしたければ、空のリストを mail.outbox に代入してください:

from django.core import mail

# Empty the test outbox
mail.outbox = []

他のテストフレームワークを使う¶

doctest と unittest だけが Python のテストフレームワークではありません。Django は他のテストフレームワークを明にサポートしているわけではありませんが、他のテストフレームワークで作成したテストを Django の通常のテストと同じように呼び出すためのメカニズムは提供しています。

./manage.py test を実行すると、 Django は TEST_RUNNER 設定を探して、実行すべきテストランナを決定します。デフォルトでは、 TEST_RUNNER は django.test.simple.run_tests です。このメソッドは Django のデフォルトのテスト動作を実装しており、以下のように動作します:

テスト前の全体的な準備を行います。

テストデータベースを生成します。

syncdb を実行して、モデルと初期データをデータベースにインストールします。

インストールされている全てのアプリケーションの models.py や tests.py から、単体テストと doctest を探します。

見つかった単体テストと doctest を実行します。

テストデータベースを破壊します。

テスト後の全体的な後始末を行います。

テストランナメソッドを自作して、そのメソッド名を TEST_RUNNER に指定しておき、 ./manage.py test を実行すると、 Django はそのテストランナメソッドを実行します。これによって、 Python コードから任意のテストフレームワークを実行できます。

テストランナを定義する¶

リリースノートを参照してください

慣習的に、テストランナは run_tests と名付けます。テストランナは以下のように Django テストランナと同じ引数をとらねばなりません:

run_tests(test_labels, verbosity=1, interactive=True, extra_tests=[])¶

test_labels には、実行したいテストを表す文字列 (ラベル) のリストを指定します。ラベルは以下の 3 つの形式で指定できます:

app.TestCase.test_method - テストケース中の個別のテストメソッドを実行します。

app.TestCase - テストケース中の全てのテストメソッドを実行します。

app - アプリケーション中の全てのテストを探して実行します。

test_labels が None の場合、テストランナは INSTALLED_APPS に登録されている全てのアプリケーションからテストを探して実行します。

verbosity には、コンソールに出力される通知情報やデバッグ情報の量を指定します。 0 にすると何も出力しません。 1 は通常の出力、 2 は多めの出力です。

interactive を True にすると、テストスイートの実行時に、テストスイートからユーザに質問できるようになります。例えば、テストデータベースを削除してよいか尋ねるといった使い方です。 interactive を False にする場合、テストスイートは手動操作なしで実行できねばなりません。

extra_tests には、このテストランナに追加で実行させたい TestCase インスタンスを指定します。 extra_tests を指定すると、 module_list から発見したテストに加えて、指定したテストを実行します。

このメソッドは失敗したテストの数を返さねばなりません。

テスト用のユーティリティ¶

django.test.utils モジュールには、テストランナの自作に役立つユーティリティメソッドが定義されています。

setup_test_environment()¶: テンプレートレンダリングシステム構成のインストールなど、テスト前の全体的な準備を行い、ダミーの SMTPConnecton をセットアップします。

teardown_test_environment()¶: テンプレートレンダリングシステムに組み込まれた黒魔術的なフックの除去など、テスト後の全体的な後始末を行い、メールサービスを通常の状態に復帰します。

データベースバックエンドの生成モジュール (connection.creation) にも、テスト時に便利なユーティリティがあります。

create_test_db(verbosity=1, autoclobber=False)¶

新たなテストデータベースを生成し、 syncdb を実行します。

verbosity は run_tests() の同名の引数と同じ意味です。

autoclobber には、テストデータベースと同名のデータベースが見つかった際の挙動を指定します:

autoclobber が False なら、既存のデータベースを破壊してもよいかユーザに尋ねます。ユーザが「いいえ」を選択すると、その時点で sys.exit を呼び出して終了します。

autoclobber が True なら、既存のデータベースを破壊するときにユーザに了解を求めません。

生成されたテストデータベースの名前を返します。

create_test_db() には settings.DATABASE_NAME を変更してテストデータベースの名前にするという副作用があります。

create_test_db() 生成されたテストデータベースの名前を返すようになりました。

destroy_test_db(old_database_name, verbosity=1)¶

このメソッドを呼び出した時点で DATABASE_NAME に設定されているデータベースを破壊し、 DATABASE_NAME の値を old_database_name に指定したデータベース名に戻します。

verbosity は run_tests() の同名の引数と同じ意味です。

Django 1.4 documentation

Djangoアプリケーションのテスト¶

テストを書く¶

doctest を書く¶

ユニットテストを書く¶

どちらのテストを使うべきか¶

テストを実行する¶

テストデータベース¶

その他のテスト条件¶

テストプログラムの出力を理解する¶

テスト用のツール¶

テストクライアント¶

テストの概要と簡単な例¶

リクエスト生成¶

レスポンスのテスト¶

例外¶

セッションの永続性¶

ユニットテストの例¶

TestCaseクラス¶

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

フィクスチャの読み込み¶

URLconf の設定¶

メール送信箱の内容抹消¶

アサーション¶

メールサービス¶

他のテストフレームワークを使う¶

テストランナを定義する¶

テスト用のユーティリティ¶

Table Of Contents

前後のページ

現在のページ:

This Page

Last update: