doctest を書く¶

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

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

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

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

doctest の文字列は models.py の全てのオブジェクトに対して記述できますが、 慣習的には、アプリケーションレベルの doctest はモジュールの docstring に、 モデルレベルの doctest は各モデルの docstring に配置します。

モデル定義で 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 はテストの初期化／終了処理のルーチンをサポートしてい るので、テストケースを実行するときの環境を高い水準でコントロールできま す。

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

テストデータベース¶

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

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

デフォルトでは、 .. _Understanding the test output:

テストの出力を理解する¶

テストを実行すると、まずテストランナ自身の初期化メッセージが表示されます:

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

このメッセージは、テストランナがテストデータベースを作成したことを示してい ます。テストデータベースは、空の、何もない状態から作成したデータベースで、 (モデルテストのような) データベースの必要なテストで使われます。

デフォルトでは、テストデータベースの名前は、 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 です。この仕様は、テス トランナをシェルスクリプト上で動かしたり、テストが成功したかどうかをテスト ランナのレベルで調べたい場合に便利です。

テストクライアント¶

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

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

• ある URL に対する GET や POST をシミュレートでき、低水準の HTTP (レスポ ンスヘッダや状態コード) 情報から、ページの内容まで、リクエストに対するレ スポンスの全てを調べられます。
• 特定の URL に対して正しいビューが呼び出されるかどうかを調べられます。
• 特定のリクエストに対して、特定のテンプレートを使ったレンダリングが行わ れ、その際に特定の値が入ったコンテキストが使われているかどうかを調べら れます。

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

• 正しいビューが呼び出され、ビューが正しいコンテキストデータを生成してい るかどうかは、 Django のテストクライアントを使って調べてください。
• Twill や Selenium は、 レンダリング済みの HTML や、 JavaScript の機能 のような 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 ...'

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クラス¶

Django は拡張用に以下のベースクラスを提供しています:

class TestCase¶

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

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

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)

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)

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

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

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

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

from django.test import TestCase

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

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

メールサービス¶

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

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

django.core.mail.output¶

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

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

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

from django.core import mail

# Empty the test outbox
mail.outbox = []

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

慣習的に、テストランナは 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 を変更してテストデー タベースの名前にするという副作用があります。

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

destroy_test_db(old_database_name, verbosity=1)¶

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

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