Django 5.2.9 ドキュメント

Home | Table of contents | Index | Modules

« previous | up | next »

テストを書いて実行する

参考

テストチュートリアル、 テストツールリファレンス、 テストに関する応用的なトピック も参照

ドキュメントは2つの大きなセクションに分けられます。前半のパートでは、Django でのテストの書き方を説明します。後半では、テストの実行の仕方について説明します。

テストを書く

Django のユニットテストには、Python スタンダードライブラリのモジュール、unittest を使用します。このモジュールは、テストをクラスベースのアプローチで定義します。

次の例では、 unittest.TestCase のサブクラスである django.test.TestCase から、テスト用の新しいサブクラスを作っています。各テストをトランザクションの内側で実行することで、独立性を実現しています。

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


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

    def test_animals_can_speak(self):
        """Animals that can speak are correctly identified"""
        lion = Animal.objects.get(name="lion")
        cat = Animal.objects.get(name="cat")
        self.assertEqual(lion.speak(), 'The lion says "roar"')
        self.assertEqual(cat.speak(), 'The cat says "meow"')

テストを実行する と、テストユーティリティのデフォルトの動作として、ファイル名が test で始まるファイル内のすべてのテストケースクラス (つまり unittest.TestCase のサブクラス) を見つけ、それらのテストケースクラスから自動的にテストスイートを構築し、そのテストスイートを実行します。

unittest の詳細については、Python のドキュメントを読んでください。

どこにテストを書くべき？

デフォルトの startapp テンプレートは、新しいアプリケーション内に tests.py ファイルを作成します。テストの数が少ないうちは、ここに書くのがいいかもしれません。しかし、テストスイートが大きくなってきたら、テストを複数のパッケージに再構成して、test_models.py 、 test_views.py 、 test_forms.py などの異なるサブモジュールに分離すると良いでしょう。ファイル名には、ちゃんと組織的な命名規則になっていれば、自由に好きな名前をつけて構いません。

Django テストランナーを使って再利用可能なアプリケーションをテストする も参照してください。

警告

作成したテストが、データの新規作成やモデルのクエリなどのデータベースアクセスを必要とするときは、unittest.TestCase ではなく、 django.test.TestCase のサブクラスを作るようにしてください。

unittest.TestCase を使えば、各テストでデータベースのトランザクションとフラッシュに必要な実行コストを避けることができます。しかし、データベースと相互作用するテストの場合、テストランナーがテストを実行する順番によっては、異なる動作をすることがあります。そのため、孤立した環境では成功するテストユニットでも、一連のテストスイートの中で実行した時には失敗してしまうという状況が発生することがあります。

テストの実行

テストが書けたら、プロジェクトの manage.py ユーティリティの test コマンドでテストが実行できます。

$ ./manage.py test

Test discovery is based on the unittest module's built-in test discovery. By default, this will discover tests in any file named test*.py under the current working directory.

/manage.py test に好きな数の「テストラベル」を与えることで、特定のテストを指定することもできます。各テストラベルには、パッケージ、モジュール、 TestCase サブクラス、テストメソッドへのドット区切りの Python パスを指定します。たとえば、以下のように指定します。

# Run all the tests in the animals.tests module
$ ./manage.py test animals.tests

# Run all the tests found within the 'animals' package
$ ./manage.py test animals

# Run just one test case class
$ ./manage.py test animals.tests.AnimalTestCase

# Run just one test method
$ ./manage.py test animals.tests.AnimalTestCase.test_animals_can_speak

ディレクトリ下に置かれたテストを探索するために、ディレクトリのパスを指定することもできます。

$ ./manage.py test animals/

-p (または --pattern) オプションを使って、カスタムのファイル名のパターンマッチを指定すれば、テストファイルの名前が test*.py というパターンとは違っていても実行できます。

$ ./manage.py test --pattern="tests_*.py"

テストの実行中に Ctrl-C を押すと、テストランナーは現在実行中のテストが完了するのを待って、gracefully にテストを終了します。graceful な終了では、テストランナーは失敗したテストの詳細を出力し、実行したテストの数と、エラーおよび失敗したテストの数をレポートし、通常通りにテストデータベースを破棄します。そのため、 Ctrl-C を押すのは、たとえば、 --failfast オプションを付けるのを忘れて、一部のテストが予期せず失敗して、すべてのテストが終わるのを待たずにすぐにその失敗の詳細を知りたいような場合に大変役に立ちます。

現在実行中のテストの終了も待ちたくないときは、もう一度 Ctrl-C を押すことで、テストを graceful ではなく、すぐに強制終了できます。その場合、強制終了前に実行していたテストの詳細はリポートされず、実行中に作られたテストデータベースも破棄されません。

警告を有効にしてテストする

python -Wa manage.py test というように、Python の警告表示を有効にしてテストを実行するのは良い考えです。-Wa フラグをセットすると、Python に deprecation 警告を表示するように伝えます。Django などの Python ライブラリは、機能の廃止を知らせるフラグとして、この警告を利用しています。また、この機能は、厳密には間違いではないがあまり良くないコードを知らせてくれることがあるので、実装を改善できることがあります。

test データベース

データベースを必要とするテスト (すなわち、モデルテスト) には、"実際の" (production) 環境のデータベースは使用しません。代わりに、テスト用の空のデータベースを用意します。

テストが成功したかどうかにかかわらず、すべてのテストの実行が終わった時点で、テストデータベースは破棄されます。

test --keepdb オプションを指定すれば、テストデータベースの破棄を防ぐことができます。これにより、複数回テストを実行しても、テストデータベースを保存できます。データベースが存在しないときは、最初に新しく作成され、そしてデータベースが最新の状態になるように、マイグレーションが順番に実行されます。

前のセクションで説明したように、テストの実行が強制的に中断された場合、テストデータベースが破棄されない可能性があります。次の実行では、データベースを再利用するか破棄するかを尋ねられるでしょう。test --noinput オプションを使用すると、プロンプトを抑制し、データベースを自動的に破棄できます。このオプションは、たとえばタイムアウトでテスト中断される可能性がある継続的インテグレーションサーバー上でのテストの実行時などに役に立ちます。

テストデータベースのデフォルトの名前は、 DATABASES 設定内の各 NAME の値の前に test_ を付けたものになります。SQLite を使っているときは、デフォルトでは、テストにはインメモリのデータベースを使います (つまり、データベースはメモリ内に作成されるため、ファイルシステムへのアクセスを完全になくすことができるのです！)。設定の DATABASES 内の TEST ディクショナリには、テストデータベースに対するいろいろな設定を書くことができます。例えば、別のデータベース名を指定したければ、 TEST ディクショナリの NAME に、 DATABASES の中から好きなデータベースを選んで指定できます。

PostgreSQL では、 USER が、ビルトインの postgres データベースへの読み取りアクセス権も持っている必要があります。

テストランナーの使うデータベースは、独立したデータベースだけでなく、設定ファイルで指定した通りのデータベースを使用させることもできます: ENGINE, USER, HOST, などです。テストデータベースは、USER で指定されたユーザによって作成されるため、そのユーザアカウントがシステム上で新しくデータベースを作成できる権限を持っている必要があります。

テストデータベースの文字エンコーディングに対するきめ細かい対応をするために、CHARSET TEST オプションを使用してください。MySQL を使用している場合は、COLLATION オプションを使用してテストデータベースが使用する特別な照合順序をコントロールできます。 これらおよびより進歩的な設定の詳細については、設定のドキュメント を参照してください。

SQLite で SQLite インメモリデータベースを使用する場合、 共有キャッシュ が有効になるため、スレッド間でデータベースを共有することが可能なテストを書くことができます。

テストの実行中に本番データベースからデータを見つけるには？

モジュールのコンパイル時にデータベースへのアクセスを試みると、 テスト用データベースがセットアップされる前にアクセスが発生し、予期しない結果になる可能性があります。例えば、モジュールレベルのコードにデータベースクエリがあり、実際のデータベースが存在する場合、実稼働データがテストを汚染する可能性があります。いかなる場合でも、 コードにこのようなインポート時のデータベースクエリを含めるのは良くないことです 。そのようなことをしないようにコードを書き直してください。

This also applies to customized implementations of ready().

参考

応用的なマルチデータベースのテスト トピック も参考にしてください。

テストの実行順序

すべての TestCase コードがクリーンなデータベースで実行されることを保証するために、Django のテストランナーは次の方法でテストの実行順序を決定します。

• すべての TestCase サブクラスが最初に実行されます。

• そして、他のすべての Django ベースのテスト (SimpleTestCase をベースとしたテストケースクラス、 TransactionTestCase を含む) が、特定の順序を保証も強制もしない状態で実行されます。

• 最後に、その他の unittest.TestCase テスト (doctests を含む) が実行されます。このテストの中には、データベースを変更し、そのまま元の状態に戻さないようなテストがあることもあります。

注釈

この新しいテスト順序は、テストケース順序の予期しない依存関係を明らかにするかもしれません。これは、TransactionTestCase によってデータベース内に記述された宣言に依存する doctests のケースで、これらは独立的に実行できるように修正する必要があります。

注釈

テストを読み込む際に検出された失敗は、上記のすべての前に配置され、迅速にフィードバックされます。これには、テストモジュールが見つからなかったり、構文エラーのために読み込めなかったりしたものが含まれます。

test --shuffle と --reverse オプションを使用すると、グループ内の実行順序をランダムにしたり逆にしたりすることができます。これは、テストが互いに独立していることを保証するのに役立ちます。

ロールバックのエミュレーション

マイグレーションで呼び出されるあらゆる初期データは、TestCase テスト内のみで有効で、 TransactionTestCase 内では無効です。加えて、トランザクションがサポートされるバックエンドのみで有効です (最も重要な例外は MyISAM です)。これは、LiveServerTestCase や StaticLiveServerTestCase といった TransactionTestCase に依存するテストに関しても同様です。

Djangoは、 TestCase や TransactionTestCase の本文で serialized_rollback オプションを True に設定することで、テストケースごとにデータを再読み込みできますが、これによりテストスイートの実行速度が約3倍遅くなることに注意してください。

サードパーティのアプリや MyISAM に対して開発する場合は、通常この設定が必要です。しかし、独自のプロジェクトをトランザクションデータベースに対して開発する場合は、ほとんどのテストで TestCase を使用するはずです。したがって、この設定は不要です。

初期シリアライズは通常、非常に高速ですが、このプロセスからいくつかのアプリを除外してテストの実行を少しでも高速にしたい場合は、それらのアプリを TEST_NON_SERIALIZED_APPS に追加します。

シリアライズされたデータが二度読み込まれるのを防ぐために、 serialized_rollback=True を設定すると、テストデータベースを flush するときに post_migrate シグナルを無効にします。

Changed in Django 5.2:

TransactionTestCase では、シリアライズされたマイグレーションデータは setUpClass() の実行中に利用可能になります。

その他のテストに関する条件

設定ファイルで指定した DEBUG の値にかかわらず、Django のテストは DEBUG=False を指定したものとして実行されます。これは、表示されるコードの出力が、実際の環境設定で見られるものと同じになるようにするためです。

各テスト後にキャッシュはクリアされません。そのため、manage.py test fooapp を実行すると、テストで挿入されたデータが実働環境のシステムのキャッシュに残り続ける可能性があります。データベースの場合と違い、別の「テスト用のキャッシュ」が使われないためです。ただし、この動作は将来 変更される可能性があります 。

テストの出力を理解する

テストを実行すると、テストランナーが用意したたくさんのメッセージが表示されます。表示するメッセージの詳細レベルは、コマンドラインで verbosity オプションを指定することで、自由にコントロールできます。

Creating test database...
Creating table myapp_animal
Creating table myapp_mineral

このメッセージは、テストランナーが前のセクションで説明したテスト用のデータベースを作成していることを表しています。

テスト用データベースが作成されると、Django はテストを実行します。すべてのテストが成功すれば、次のようなメッセージが表示されるはずです。

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

OK

しかし、もしテストが失敗した場合には、失敗したテストとその詳細が表示されます。

======================================================================
FAIL: test_was_published_recently_with_future_poll (polls.tests.PollMethodTests)
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/dev/mysite/polls/tests.py", line 16, in test_was_published_recently_with_future_poll
    self.assertIs(future_poll.was_published_recently(), False)
AssertionError: True is not False

----------------------------------------------------------------------
Ran 1 test in 0.003s

FAILED (failures=1)

このエラー出力の詳しい説明は、このドキュメントの範囲外ですが、極めて直感的に理解できるものです。詳しく知りたければ、Python の unittest ライブラリのドキュメントを読んでみてください。

失敗したテストの数に関わらず（失敗の原因がエラー、アサーションの失敗、予期しない成功のいずれであっても）、テストランナーのスクリプトから返ってくる終了コードは 1 であることに注意してください。すべてのテストが成功すれば、0 が返ります。この特徴は、別のシェルスクリプトの中でテストランナースクリプトを実行するときに、成功したかどうかの情報が必要な時に役に立ちます。

テストのスピードアップ

テストの並列実行

各テストが適切に独立性を保ったものであれば、マルチコアのハードウェア上でテストを並列実行することでスピートアップさせることができます。詳しくは test --parallel を読んでください。

パスワードのハッシュ生成

デフォルトのパスワードのハッシュ生成器は、設計上、時間のかかるものになっています。テストの中で多数のユーザーを認証する必要がある場合、カスタムの設定ファイルを用意して、PASSWORD_HASHERS 設定に、より高速なハッシュ生成アルゴリズムを設定すると良いでしょう。

PASSWORD_HASHERS = [
    "django.contrib.auth.hashers.MD5PasswordHasher",
]

PASSWORD_HASHERS には、必要なハッシュアルゴリズムが複数あっても、追加しておくことを忘れないようにしてください。

テストデータベースを保存する

test --keepdb オプションで、テスト間でテストデータベースを保存できます。テスト実行の際、データベース作成および破棄にかかる時間を大幅に短縮できます。

メディアファイルに対するディスクアクセスを回避する

InMemoryStorage は、メディアファイルに対するディスクアクセスを避けるための便利な手段です。すべてのデータはメモリ内にとどまり、テスト実行の後に破棄されます。

Last update:

12月 04, 2025

« previous | up | next »