pytho****@googl*****
pytho****@googl*****
2011年 12月 25日 (日) 16:24:35 JST
Revision: 312cf9c3e119 Author: Toshiyuki Kawanishi <toshi****@gmail*****> Date: Sat Dec 24 23:22:55 2011 Log: 2.7対応途中までコミット 2.7 対応: Toshiyuki Kawanishi <toshi****@gmail*****> http://code.google.com/p/python-doc-ja/source/detail?r=312cf9c3e119 Modified: /library/unittest.rst ======================================= --- /library/unittest.rst Sun May 22 06:11:37 2011 +++ /library/unittest.rst Sat Dec 24 23:22:55 2011 @@ -9,9 +9,11 @@ .. sectionauthor:: Fred L. Drake, Jr. <fdrak****@acm*****> .. sectionauthor:: Raymond Hettinger <pytho****@rcn*****> - .. versionadded:: 2.1 +(読者の方がすでにテストの基本概念についてなじみがあるようでしたら、 +この部分をとばして :ref:`the list of assert methods <assert-methods>` に進 むと良いでしょう。) + この Python ユニットテストフレームワークは時に "PyUnit" とも呼ばれ、 Kent Beck と Erich Gamma による JUnit の Python 版です。 JUnit はまた Kent の Smalltalk 用テストフレームワークの Java 版で、 @@ -50,8 +52,8 @@ います。 :class:`TestCase` クラスは新規にテストを作成する場合に使用し、 :class:`FunctionTestCase` は既存のテストを :mod:`unittest` に組み込む 場合に使用します。テストフィクスチャーの設定処理と終了処理は、 -:class:`TestCase` では :meth:`setUp` メソッドと :meth:`tearDown` をオー -バーライドして記述し、 :class:`FunctionTestCase` では初期設定・終了処 +:class:`TestCase` では :meth:`~TestCase.setUp` メソッド と :meth:`~TestCase.tearDown` +をオーバーライドして記述し、 :class:`FunctionTestCase` では初期設定・終了処 理を行う既存の関数をコンストラクタで指定します。テスト実行時、まずテス トフィクスチャーの初期設定が最初に実行されます。初期設定が正常終了した 場合、テスト実行後にはテスト結果に関わらず終了処理が実行されます。 @@ -62,13 +64,13 @@ トとテストスイートをまとめる事ができます。テストスイートを実行すると、 スイートと子スイートに追加されている全てのテストが実行されます。 -テストランナーは :meth:`run` メソッドを持つオブジェクトで、 -:meth:`run` は引数として :class:`TestCase` か :class:`TestSuite` オブ +テストランナーは :meth:`~TestRunner.run` メソッドを持つオブジェクトです。 +このメソッドは引数として :class:`TestCase` か :class:`TestSuite` オブ ジェクトを受け取り、テスト結果を :class:`TestResult` オブジェクトで戻 します。 :mod:`unittest` ではデフォルトでテスト結果を標準エラーに出力 する :class:`TextTestRunner` をサンプルとして実装しています。これ以外 -のランナー (グラフィックインターフェース用など) を実装する場合でも、特 -定のクラスから派生する必要はありません。 +のランナー (グラフィックインターフェース用など) を実装する場合でも、 +特別なクラスから派生させて実装する必要はありません。 .. seealso:: @@ -76,6 +78,11 @@ Module :mod:`doctest` もうひとつのテストをサポートするモジュールで、本モジュールと趣きが異 なっています。 + `unittest2: ユニットテストの新機能の Python 2.4-2.6 向けバックポート <http://pypi.python.org/pypi/unittest2>`_ + Python 2.7 になり多くの機能が unittest に追加されました。特に、 + テストディスカバリが追加されました。 unittest2 を導入する事で + 以前のバージョンの Python でもこれらの機能を使えます。 + `Simple Smalltalk Testing: With Patterns <http://www.XProgramming.com/testfram.htm>`_ Kent Beck のテスティングフレームワークに関する原論文で、ここに記載さ れたパターンを :mod:`unittest` が使用しています。 @@ -84,8 +91,13 @@ サードパーティのユニットテストフレームワークで軽量な文法でテストを書 くことができます。 例えば、 ``assert func(10) == 42`` のように書きます。 - `python-mock <http://python-mock.sourceforge.net/>`_ と `minimock <http://blog.ianbicking.org/minimock.html>`_ - テスト用のモックオブジェクトを作成するツールです (モックオブジェクト は外部リソースをシミュレートします)。 + `The Python Testing Tools Taxonomy <http://pycheesecake.org/wiki/PythonTestingToolsTaxonomy>`_ + 多くの Python のテストツールが一覧で紹介されています。 + ファンクショナルテストのフレームワークやモックライブラリも掲載されて います。 + + `Testing in Python Mailing List <http://lists.idyll.org/listinfo/testing-in-python>`_ + Python でテストやテストツールについての議論に特化したグループです。 + .. _unittest-minimal-example: @@ -112,12 +124,16 @@ self.seq.sort() self.assertEqual(self.seq, range(10)) + # should raise an exception for an immutable sequence + self.assertRaises(TypeError, random.shuffle, (1,2,3)) + def test_choice(self): element = random.choice(self.seq) self.assertTrue(element in self.seq) def test_sample(self): - self.assertRaises(ValueError, random.sample, self.seq, 20) + with self.assertRaises(ValueError): + random.sample(self.seq, 20) for element in random.sample(self.seq, 5): self.assertTrue(element in self.seq) @@ -129,16 +145,16 @@ ンナーはこの命名規約によってテストを行うメソッドを検索します。 これらのテスト内では、予定の結果が得られていることを確かめるために -:meth:`assertEqual` を、条件のチェックに :meth:`assert_` を、例外が発 -生する事を確認するために :meth:`assertRaises` をそれぞれ呼び出していま -す。 :keyword:`assert` 文の代わりにこれらのメソッドを使用すると、テス -トランナーでテスト結果を集計してレポートを作成する事ができます。 - -:meth:`setUp` メソッドが定義されている場合、テストランナーは各テストを -実行する前に :meth:`setUp` メソッドを呼び出します。同様に、 -:meth:`tearDown` メソッドが定義されている場合は各テストの実行後に呼び +:meth:`~TestCase.assertEqual` を、条件のチェック に :meth:`~TestCase.assertTrue` を、 +例外が発生する事を確認するために :meth:`~TestCase.assertRaises` を +それぞれ呼び出しています。 :keyword:`assert` 文の代わりにこれらのメソッドを 使用すると、 +テストランナーでテスト結果を集計してレポートを作成する事ができます。 + +:meth:`~TestCase.setUp` メソッドが定義されている場合、テストランナーは各テ ストを +実行する前に :meth:`~TestCase.setUp` メソッドを呼び出します。同様に、 +:meth:`~TestCase.tearDown` メソッドが定義されている場合は各テストの実行後に 呼び 出します。上のサンプルでは、それぞれのテスト用に新しいシーケンスを作成 -するために :meth:`setUp` を使用しています。 +するために :meth:`~TestCase.setUp` を使用しています。 サンプルの末尾が、簡単なテストの実行方法です。 :func:`unittest.main` は、テストスクリプトのコマンドライン用インターフェースです。コマンドラ @@ -176,6 +192,143 @@ 章を参照してください。 +.. _unittest-command-line-interface: + +コマンドラインインタフェース +---------------------------- + +ユニットテストモジュールはコマンドラインから使うこともできます。 +モジュール、クラス、もしくは、特定のテストメソッドで定義されたテストを実行 します。:: + + python -m unittest test_module1 test_module2 + python -m unittest test_module.TestClass + python -m unittest test_module.TestClass.test_method + +引数として渡す事ができるのは、テストが定義されたモジュール名、 +もしくはクラス、メソッドのフルパス名です。 + +テスト実行時に（冗長な）詳細を表示するには -f フラグを渡します。:: + + python -m unittest -v test_module + +コマンドラインプションの一覧を表示するには以下のコマンドを実行します。:: + + python -m unittest -h + +.. versionchanged:: 2.7 + 以前のバージョンでは、特定のメソッドでしか実行できず、 + モジュールやクラスは指定できませんでした。 + + +コマンドラインオプション +~~~~~~~~~~~~~~~~~~~~~~~~ + +:program:`unittest` には以下のコマンドラインオプションがあります: + +.. program:: unittest + +.. cmdoption:: -b, --buffer + + 標準出力と標準エラーのストリームをテスト実行の間バッファリングします。 + テストが成功している間は結果の出力は破棄されます。 + テストが失敗、もしくはエラーが発生した場合には、 + 結果にエラーメッセージが追加されたうえで通常通り出力されます。 + +.. cmdoption:: -c, --catch + + control-C を実行中のテストが終了するまで遅延させ、そこまでの結果を出力し ます。 + 二回目の control-C は、通常通り :exc:`KeyboardInterrupt` + の例外を発生させます。 + + この機能の仕組みについては、 `Signal Handling`_ を参照してください。 + +.. cmdoption:: -f, --failfast + + 初回のエラーもしくは失敗の時にテストを停止します。 + +.. versionadded:: 2.7 + コマンドラインオプションの ``-b``, ``-c`` および ``-f`` が追加されまし た。 + +このコマンドラインは、プロジェクト内の全テストを実行したり、 +サブセットのみを実行したりといった、テストディスカバリを使用することもでき ます。 + + +.. _unittest-test-discovery: + +テストディスカバリ +------------------ + +.. versionadded:: 2.7 + +unittest はシンプルなテストディスカバリをサポートします。 +このテストディスカバリに対応するために、テストが定義された全ファイルは +:ref:`modules <tut-modules>` もしくは :ref:`packages <tut-packages>` として +プロジェクトの最上位のディスカバリでインポート可能である必要があります。 +（つまり、これらのファイルは :ref:`identifiers <identifiers>` として有効で +ある必要があるということです。） + +テストディスカバリは :meth:`TestLoader.discover` で実装されています。 +しかし、コマンドラインからも使う事ができます。コマンドラインからは以下のよ うに使用します。:: + + cd project_directory + python -m unittest discover + +``discover`` サブコマンドには以下のオプションがあります。 + +.. program:: unittest discover + +.. cmdoption:: -v, --verbose + + 詳細な出よr区 + +.. cmdoption:: -s directory + + ディスカバリを開始するディレクトリ （デフォルトは '.'） + +.. cmdoption:: -p pattern + + テストファイル名を識別するパターン （デフォルトは 'test*.py'） + +.. cmdoption:: -t directory + + プロジェクトの最上位のディスカバリのディレクトリ （デフォルトは開始のデ ィレクトリ） + +The :option:`-s`, :option:`-p`, and :option:`-t` options can be passed in +as positional arguments in that order. The following two command lines +are equivalent:: + +:option:`-s` 、 :option:`-p` 、および :option:`-t` の各オプションは、 +この順番で指定すれば位置固定の引数として指定する事ができます。 +以下の二つのコマンドは同じ結果になります。:: + + python -m unittest discover -s project_directory -p '*_test.py' + python -m unittest discover project_directory '*_test.py' + +パスを渡すのはもちろんのこと、例えば ``myproject.subpackage.test`` のよう に、 +パッケージ名をスタートディレクトリとして渡すことができます。 +指定したパッケージがインポートされ、そのパッケージのファイルシステム上のパ スが +スタートディレクトリになります。 + +.. caution:: + + テストディスカバリはテストをインポートすることで読み込みます。 + テストディスカバリは一度、指定した開始ディレクトリから全テストファイル を探索し、 + そのファイルのパスをパッケージ名に変換してインポートします。 + 例えば、 `foo/bar/baz.py` は ``foo.bar.baz`` としてインポートされます。 + + もしパッケージをグローバルにインストールしていて、 + インストールしたのとは異なるパッケージのコピーをディスカバリしようとす ると、 + 間違った場所からインポートして *しまうかもしれません* 。 + このような状態になるとテストディスカバリは警告を出し、停止します。 + + スタートディレクトリとしてディレクトリのパスではなく + パッケージ名を指定した場合は、いずれかの場所からインポートされます。 + この場合は警告が表示されません。 + +テストモジュールとテストパッケージは、テストのロードとディスカバリを +カスタマイズすることができます。そのために `load_tests protocol`_ を使用し ます。 + + .. _organizing-tests: テストの構成 @@ -194,7 +347,7 @@ :class:`TestCase` インスタンスは外部から完全に独立し、単独で実行する事 も、他の任意のテストと一緒に実行する事もできなければなりません。 -以下のように、 :class:`TestCase` のサブクラスは :meth:`runTest` をオー +以下のように、 :class:`TestCase` のサブクラスは :meth:`~TestCase.runTest` をオー バライドし、必要なテスト処理を記述するだけで簡単に書くことができます:: import unittest @@ -205,7 +358,7 @@ self.assertEqual(widget.size(), (50,50), 'incorrect default size') 何らかのテストを行う場合、ベースクラス :class:`TestCase` の -:meth:`assert\*` か :meth:`fail\*` メソッドを使用してください。テスト +:meth:`assert\*` メソッドを使用してください。テスト が失敗すると例外が送出され、 :mod:`unittest` はテスト結果を :dfn:`failure` とします。その他の例外は :dfn:`error` となります。 これによりどこに問題があるかが判ります。 :dfn:`failure` は間違った結果 @@ -223,7 +376,7 @@ れのサブクラスで :class:`Widget` オブジェクトを生成する処理を記述する のは好ましくありません。 -このような場合、初期化処理は :meth:`setUp` メソッドに切り出し、テスト +このような場合、初期化処理は :meth:`~TestCase.setUp` メソッドに切り出し、テ スト 実行時にテストフレームワークが自動的に実行するようにすることができます:: import unittest @@ -243,12 +396,12 @@ self.assertEqual(self.widget.size(), (100,150), 'wrong size after resize') -テスト中に :meth:`setUp` メソッドで例外が発生した場合、テストフレーム -ワークはテストを実行することができないとみなし、 :meth:`runTest` を実 +テスト中に :meth:`~TestCase.setUp` メソッドで例外が発生した場合、テストフ レーム +ワークはテストを実行することができないとみなし、 :meth:`~TestCase.runTest` を実 行しません。 -同様に、終了処理を :meth:`tearDown` メソッドに記述すると、 -:meth:`runTest` メソッド終了後に実行されます:: +同様に、終了処理を :meth:`~TestCase.tearDown` メソッドに記述すると、 +:meth:`~TestCase.runTest` メソッド終了後に実行されます:: import unittest @@ -260,8 +413,8 @@ self.widget.dispose() self.widget = None -:meth:`setUp` が正常終了した場合、 :meth:`runTest` が成功したかどうか -に従って :meth:`tearDown` が実行されます。 +:meth:`~TestCase.setUp` が正常終了した場合、 :meth:`~TestCase.runTest` が成 功したかどうか +に従って :meth:`~TestCase.tearDown` が実行されます。 このような、テストを実行する環境を :dfn:`fixture` と呼びます。 @@ -337,8 +490,8 @@ :class:`TestLoader` は自動的にテストメソッドを識別するのに ``'test'`` というメソッド名の接頭辞を使います。 -いろいろなテストケースが実行される順序は、テスト関数名を組み込み関数 -:func:`cmp` でソートして決定されます。 +いろいろなテストケースが実行される順序は、テスト関数名を組み込みの +文字列の順番に従って決まります。 システム全体のテストを行う場合など、テストスイートをさらにグループ化し たい場合がありますが、このような場合、 :class:`TestSuite` インスタンス @@ -413,12 +566,119 @@ 時間を掛けて :class:`TestCase` のサブクラスに書き直した方が将来的な テストのリファクタリングが限りなく易しくなります。 +既存のテストが :mod:`doctest` を使って書かれている場合もあるでしょう。 +その場合、 :mod:`doctest` は :class:`DocTestSuite` クラスを提供します。 +このクラスは、既存の :mod:`doctest`\ ベースのテストから、 +自動的に :class:`unittest.TestSuite` のインスタンスを作成します。 + + +.. _unittest-skipping: + +テストのスキップと意図的な失敗 +-------------------------------- + +.. versionadded:: 2.7 + +unittest は特定のテストメソッドやテストクラス全体をスキップする仕組みを備え ています。 +さらに、この機能はテスト結果を「意図的な失敗」とすることができ、 +テストが失敗しても :class:`TestResult` の失敗数にはカウントされなくなりま す。 + +テストをスキップするには、 単に :func:`skip` :term:`デコレータ` を使用する か、 +条件を表現するための :func:`skip` に類する :term:`デコレータ` を使用しま す。 + +スキップは以下のようになります。 :: + + class MyTestCase(unittest.TestCase): + + @unittest.skip("demonstrating skipping") + def test_nothing(self): + self.fail("shouldn't happen") + + @unittest.skipIf(mylib.__version__ < (1, 3), + "not supported in this library version") + def test_format(self): + # Tests that work for only a certain version of the library. + pass + + @unittest.skipUnless(sys.platform.startswith("win"), "requires Windows") + def test_windows_support(self): + # windows specific testing code + pass + +このサンプルを詳細モードで実行すると以下のように出力されます。 :: + + test_format (__main__.MyTestCase) ... skipped 'not supported in this library version' + test_nothing (__main__.MyTestCase) ... skipped 'demonstrating skipping' + test_windows_support (__main__.MyTestCase) ... skipped 'requires Windows' + + ---------------------------------------------------------------------- + Ran 3 tests in 0.005s + + OK (skipped=3) + +テストクラスは以下のようにメソッドをスキップすることができます。 :: + + @skip("showing class skipping") + class MySkippedTestCase(unittest.TestCase): + def test_not_run(self): + pass + +:meth:`TestCase.setUp` もスキップすることができます。 +この機能はセットアップの対象のリソースが使用不可能な状態の時に便利です。 + +意図的な失敗の機能を使用するには、 :func:`expectedFailure` デコレータを使い ます。 :: + + class ExpectedFailureTestCase(unittest.TestCase): + @unittest.expectedFailure + def test_fail(self): + self.assertEqual(1, 0, "broken") + +独自のスキップ用のデコレータも簡単に作成することができます。 +そのためには、独自のデコレータのスキップしたい時点で :func:`skip` を呼び出 します。 +以下のデコレータはオブジェクトに指定した属性が無い場合にテストをスキップし ます。 :: + + def skipUnlessHasattr(obj, attr): + if hasattr(obj, attr): + return lambda func: func + return unittest.skip("{0!r} doesn't have {1!r}".format(obj, attr)) + +以下のデコレータはテストのスキップと意図的な失敗を実装しています。 + +.. function:: skip(reason) + + デコレートしたテストを無条件でスキップします。 + *reason* にはテストをスキップした理由を記載します。 + +.. function:: skipIf(condition, reason) + + *condition* が真の場合に、デコレートしたテストをスキップします。 + +.. function:: skipUnless(condition, reason) + + *condition* が偽の場合に、デコレートしたテストをスキップします。 + +.. function:: expectedFailure + + テストの失敗が意図的であることを表します。 + 該当のテストが失敗しても、そのテストは失敗にカウントされません。 + +スキップしたテストの前後では、 :meth:`setUp` および :meth:`tearDown` は実行 されません。 +同様に、スキップしたテストクラスの前後では、 :meth:`setUpClass` および + :meth:`tearDownClass` は実行されません。 + .. _unittest-contents: クラスと関数 ------------ +この節では、 :mod:`unittest` モジュールのAPIの詳細について説明します。 + + +.. _testcase-objects: + +テストクラス +~~~~~~~~~~~~ .. class:: TestCase([methodName]) @@ -442,10 +702,604 @@ ここでは、それぞれが一つずつのテストを実行するような :class:`WidgetTestCase` の二つのインスタンスを作成しています。 - *methodName* のデフォルトは ``'runTest'`` です。 - - -.. class:: FunctionTestCase(testFunc[, setUp[, tearDown[, description]]]) + *methodName* のデフォルトは :meth:`runTest` です。 + + :class:`TestCase` のインスタンスのメソッドは3種類のグループに分けられま す。 + 1つ目のグループのメソッドはテストの実行で使用します。2つ目のグループのメ ソッドは + 条件の確認および失敗のレポートといったテストの実装で使用されます。3つ目 のグループである + 問い合わせ用のメソッドはテスト自身の情報を収集するために使用します。 + + はじめのグループ（テスト実行）に含まれるメソッドは以下の通りです。 + + + .. method:: setUp() + + テストフィクスチャの準備のために呼び出されるメソッドです。テストメソ ッドの直前に + 呼び出されます。このメソッドを実行中に例外が発生した場合、テストの失 敗ではなくエラーと + されます。デフォルトの実装では何も行いません。 + + + .. method:: tearDown() + + テストメソッドが実行され、結果が記録された直後に呼び出されるメソッド です。 + このメソッドはテストメソッドで例外が投げられても呼び出されます。 + そのため、サブクラスでこのメソッドを実装する場合は、内部状態を確認す ることが + 必要になるでしょう。メソッドを実行中に例外が発生した場合、テストの失 敗ではなく + エラーとみなされます。このメソッドは、テストの結果に関わらず + :meth:`setUp` が成功した場合にのみ呼ばれます。 + デフォルトの実装では何も行いません。 + + + .. method:: setUpClass() + + クラス内に定義されたテストが実行される前に呼び出されるクラスメソッド です。 + ``setUpClass`` はクラスを唯一の引数として取り、 :func:`classmethod` で + デコレートされている必要があります。 :: + + @classmethod + def setUpClass(cls): + ... + + 詳しくは `Class and Module Fixtures`_ を参照してください。 + + .. versionadded:: 2.7 + + + .. method:: tearDownClass() + + クラス内に定義されたテストが実行された後に呼び出されるクラスメソッド です。 + ``tearDownClass`` はクラスを唯一の引数として取 り、 :func:`classmethod` で + デコレートされている必要があります。 :: + + @classmethod + def tearDownClass(cls): + ... + + 詳しくは `Class and Module Fixtures`_ を参照してください。 + + .. versionadded:: 2.7 + + + .. method:: run(result=None) + + テストを実行し、テスト結果を *result* に指定されたテスト結果オブジェ + クトに渡します。 *result* 省略されるか :const:`None` か渡された場合、 + 一時的な結果オブジェクトを（ :meth:`defaultTestCase` メソッドを呼んで ） + 生成して使用しますが :meth:`run` の呼び出し元には渡されません。 + + このメソッドは、単に :class:`TestCase` インスタンスの呼び出した場合と + 同様に振る舞います。 + + + .. method:: skipTest(reason) + + 現在のテストでテストクラスもしくは :meth:`setUp` をスキップする場合に 呼ばれます。 + 詳細については、 :ref:`unittest-skipping` を参照してください。 + + .. versionadded:: 2.7 + + + .. method:: debug() + + テスト結果を収集せずにテストを実行します。例外が呼び出し元に通知さ + れます。また、テストをデバッガで実行することができます。 + + .. _assert-methods: + + :class:`TestCase` クラスには、条件の確認と失敗のレポートのために + 以下のメソッドが定義されています。 + + +-----------------------------------------+-----------------------------+---------------+ + | メソッド | 確認事項 | バージョン | + +=========================================+=============================+===============+ + | :meth:`assertEqual(a, b) | ``a == b`` | | + | <TestCase.assertEqual>` | | | + +-----------------------------------------+-----------------------------+---------------+ + | :meth:`assertNotEqual(a, b) | ``a != b`` | | + | <TestCase.assertNotEqual>` | | | + +-----------------------------------------+-----------------------------+---------------+ + | :meth:`assertTrue(x) | ``bool(x) is True`` | | + | <TestCase.assertTrue>` | | | + +-----------------------------------------+-----------------------------+---------------+ + | :meth:`assertFalse(x) | ``bool(x) is False`` | | + | <TestCase.assertFalse>` | | | + +-----------------------------------------+-----------------------------+---------------+ + | :meth:`assertIs(a, b) | ``a is b`` | 2.7 | + | <TestCase.assertIs>` | | | + +-----------------------------------------+-----------------------------+---------------+ + | :meth:`assertIsNot(a, b) | ``a is not b`` | 2.7 | + | <TestCase.assertIsNot>` | | | + +-----------------------------------------+-----------------------------+---------------+ + | :meth:`assertIsNone(x) | ``x is None`` | 2.7 | + | <TestCase.assertIsNone>` | | | + +-----------------------------------------+-----------------------------+---------------+ + | :meth:`assertIsNotNone(x) | ``x is not None`` | 2.7 | + | <TestCase.assertIsNotNone>` | | | + +-----------------------------------------+-----------------------------+---------------+ + | :meth:`assertIn(a, b) | ``a in b`` | 2.7 | + | <TestCase.assertIn>` | | | + +-----------------------------------------+-----------------------------+---------------+ + | :meth:`assertNotIn(a, b) | ``a not in b`` | 2.7 | + | <TestCase.assertNotIn>` | | | + +-----------------------------------------+-----------------------------+---------------+ + | :meth:`assertIsInstance(a, b) | ``isinstance(a, b)`` | 2.7 | + | <TestCase.assertIsInstance>` | | | + +-----------------------------------------+-----------------------------+---------------+ + | :meth:`assertNotIsInstance(a, b) | ``not isinstance(a, b)`` | 2.7 | + | <TestCase.assertNotIsInstance>` | | | + +-----------------------------------------+-----------------------------+---------------+ + + （ :meth:`assertRaises` と :meth:`assertRaisesRegexp` を除く）すべての + アサートメソッドには *msg* 引数を指定することができ、テストの失敗時の + エラーメッセージで使用されます。 + （ :data:`longMessage` も参照してください。） + + .. method:: assertEqual(first, second, msg=None) + + *first* と *second* が等しいことをテストします。 + 両者が比較出来ない場合は、テストが失敗します。 + + さらに、 *first* と *second* が厳密に同じ型であり、 + その型が、list, tuple, dict, set, frozenset もしくは unicode のいずれ か、 + または :meth:`addTypeEqualityFunc` で比較関数が登録されている型の場合 には、 + デフォルトのエラーメッセージを生成するために、その型特有の比較関数が 呼ばれます。 + （ :ref:`list of type-specific methods <type-specific-methods>` も参 照してください。） + + .. versionchanged:: 2.7 + 型特有の比較関数の自動呼び出しを追加。 + + + .. method:: assertNotEqual(first, second, msg=None) + + *first* と *second* が等しくないことをテストします。 + 両者が比較出来ない場合は、テストが失敗します。 + + .. method:: assertTrue(expr, msg=None) + assertFalse(expr, msg=None) + + *expr* が真（偽）であることをテストします。 + + このメソッドは、 ``bool(expr) is True`` と等価であり、 ``expr is True`` と + 等価ではないことに注意が必要です（後者のためには、 ``assertIs(expr, True)`` + が用意されています）。また、専用のメソッドが使用できる場合には、 + そちらを使用してください（例えば ``assertTrue(a == b)`` の代わりに + ``assertEqual(a, b)`` を使用してください）。そうすることにより、 + テスト失敗時のエラーメッセージを詳細に表示することができます。 + + + .. method:: assertIs(first, second, msg=None) + assertIsNot(first, second, msg=None) + + *first* と *second* が同じオブジェクトであること（そうでないこと）を テストします。 + + .. versionadded:: 2.7 + + + .. method:: assertIsNone(expr, msg=None) + assertIsNotNone(expr, msg=None) + + *expr* が None であること（そうでないこと）をテストします。 + + .. versionadded:: 2.7 + + + .. method:: assertIn(first, second, msg=None) + assertNotIn(first, second, msg=None) + + *first* が *second* に含まれること（そうでないこと）をテストします。 + + .. versionadded:: 2.7 + + + .. method:: assertIsInstance(obj, cls, msg=None) + assertNotIsInstance(obj, cls, msg=None) + + *obj* が *cls* のインスタンスであること（そうでないこと）をテストしま す。 + （この *cls* は、 :func:`isinstance` が扱うことのできる、クラスもしく は + クラスのタプルである必要があります。） + + .. versionadded:: 2.7 + + + 例外と例外発生時の警告を確認するために以下のメソッドを使用することができ ます。 + + +---------------------------------------------------------+--------------------------------------+------------+ + | Method | Checks that | New in | + +=========================================================+======================================+============+ + | :meth:`assertRaises(exc, fun, *args, **kwds) | ``fun(*args, **kwds)`` raises `exc` | | + | <TestCase.assertRaises>` | | | + +---------------------------------------------------------+--------------------------------------+------------+ + | :meth:`assertRaisesRegexp(exc, re, fun, *args, **kwds) | ``fun(*args, **kwds)`` raises `exc` | 2.7 | + | <TestCase.assertRaisesRegexp>` | and the message matches `re` | | + +---------------------------------------------------------+--------------------------------------+------------+ + + .. method:: assertRaises(exception, callable, *args, **kwds) + assertRaises(exception) + + *callable* を呼び出した時に例外が発生することをテストします。 + :meth:`assertRaises` で指定した位置パラメータとキーワードパラメータを + 該当メソッドに渡します。 *exception* が投げられた場合にテストが成功し ます。 + また、他の例外が投げられた場合はエラー、例外が投げられなかった場合は 失敗になります。 + 複数の例外をキャッチする場合には、例外クラスのタプルを *exception* に + 指定してください。 + + *exception* 引数のみが渡された場合には、コンテキストマネージャが返さ れます。 + これにより関数名を渡す形式ではなく、インラインでテスト対象のコードを 書くことができます。 :: + + with self.assertRaises(SomeException): + do_something() + + このコンテキストマネージャは :attr:`exception` で + 指定されたオブジェクトを格納します。 + これにより、例外発生時の詳細な確認をおこなうことができます。:: + + with self.assertRaises(SomeException) as cm: + do_something() + + the_exception = cm.exception + self.assertEqual(the_exception.error_code, 3) + + .. versionchanged:: 2.7 + コンテキストマネージャとして :meth:`assertRaises` を使用する機能を 追加。 + + + .. method:: assertRaisesRegexp(exception, regexp, callable, *args, **kwds) + assertRaisesRegexp(exception, regexp) + + :meth:`assertRaises` と同等ですが、例外の文字列表現が正規表現オブジェ クトにマッチ + することもテストします。 *regexp* は正規表現オブジェクト か、 :func:`re.search` が + 扱える正規表現が書かれた文字列である必要があります。例えば以下のよう になります。 :: + + self.assertRaisesRegexp(ValueError, 'invalid literal for.*XYZ$', + int, 'XYZ') + + もしくは :: + + with self.assertRaisesRegexp(ValueError, 'literal'): + int('XYZ') + + .. versionadded:: 2.7 + + + + さらに特有の確認を行うために以下のメソッドが用意されています。 + + +---------------------------------------+--------------------------------+--------------+ + | メソッド | 確認項 目 | バージョン | + +=======================================+================================+==============+ + | :meth:`assertAlmostEqual(a, b) | ``round(a-b, 7) == 0`` | | + | <TestCase.assertAlmostEqual>` | | | + +---------------------------------------+--------------------------------+--------------+ + | :meth:`assertNotAlmostEqual(a, b) | ``round(a-b, 7) != 0`` | | + | <TestCase.assertNotAlmostEqual>` | | | + +---------------------------------------+--------------------------------+--------------+ + | :meth:`assertGreater(a, b) | ``a > b`` | 2.7 | + | <TestCase.assertGreater>` | | | + +---------------------------------------+--------------------------------+--------------+ + | :meth:`assertGreaterEqual(a, b) | ``a >= b`` | 2.7 | + | <TestCase.assertGreaterEqual>` | | | + +---------------------------------------+--------------------------------+--------------+ + | :meth:`assertLess(a, b) | ``a < b`` | 2.7 | + | <TestCase.assertLess>` | | | + +---------------------------------------+--------------------------------+--------------+ + | :meth:`assertLessEqual(a, b) | ``a <= b`` | 2.7 | + | <TestCase.assertLessEqual>` | | | + +---------------------------------------+--------------------------------+--------------+ + | :meth:`assertRegexpMatches(s, re) | ``regex.search(s)`` | 2.7 | + | <TestCase.assertRegexpMatches>` | | | + +---------------------------------------+--------------------------------+--------------+ + | :meth:`assertNotRegexpMatches(s, re) | ``not regex.search(s)`` | 2.7 | + | <TestCase.assertNotRegexpMatches>` | | | + +---------------------------------------+--------------------------------+--------------+ + | :meth:`assertItemsEqual(a, b) | sorted(a) == sorted(b) and | 2.7 | + | <TestCase.assertItemsEqual>` | works with unhashable objs | | + +---------------------------------------+--------------------------------+--------------+ + | :meth:`assertDictContainsSubset(a, b) | all the key/value pairs | 2.7 | + | <TestCase.assertDictContainsSubset>` | in `a` exist in `b` | | + +---------------------------------------+--------------------------------+--------------+ + + + .. method:: assertAlmostEqual(first, second, places=7, msg=None, delta=None) + assertNotAlmostEqual(first, second, places=7, msg=None, delta=None) + + *first* と *second* が近似的に等しい（等しくない）ことをテストしま す。 + この比較は、*places* （デフォルト7）で指定した小数位で丸めた差分を + ゼロと比べることでおこないます。これらのメソッドは、（ :func:`round` と同様に） + *小数位* を指定するのであって、*有効桁数* を指定するのではないことに 注意してください。 + + *places* の代わりに *delta* が渡された場合には、 + *first* と *second* の差分が *delta* より大きい（小さい）ことをテスト します。 + + *delta* と *places* の両方が指定された場合は ``TypeError`` が投げられ ます。 + + .. versionchanged:: 2.7 + :meth:`assertAlmostEqual` は、オブジェクトが等しい場合には自動で + 近似的に等しいとみなすようになりました。 + :meth:`assertNotAlmostEqual` は、オブジェクトが等しい場合には自動 的に + 失敗するようになりました。 + *delta* 引数が追加されました。 + + + .. method:: assertGreater(first, second, msg=None) + assertGreaterEqual(first, second, msg=None) + assertLess(first, second, msg=None) + assertLessEqual(first, second, msg=None) + + *first* が *second* と比べて、メソッド名に対応して >, >=, < もしくは <= + であることをテストします。そうでない場合はテストが失敗します。 :: + + >>> self.assertGreaterEqual(3, 4) + AssertionError: "3" unexpectedly not greater than or equal to "4" + + .. versionadded:: 2.7 + + + .. method:: assertRegexpMatches(text, regexp, msg=None) + + *regexp* の検索が *text* とマッチすることをテストします。テスト失敗時 には、 + エラーメッセージにパターンと *text* が表示されます（もしくは、 + パターンと意図しないかたちでマッチした *text* の一部が表示されます ）。 + *regexp* は正規表現オブジェクトか、 :func:`re.search` が + 扱える正規表現が書かれた文字列である必要があります。 + + .. versionadded:: 2.7 + + + .. method:: assertNotRegexpMatches(text, regexp, msg=None) + + *regexp* の検索が *text* とマッチしないことをテストします。テスト失敗 時には、 + エラーメッセージにマッチしたパターンと *text* が表示されます。 + *regexp* は正規表現オブジェクトか、 :func:`re.search` が + 扱える正規表現が書かれた文字列である必要があります。 + + .. versionadded:: 2.7 + + + .. method:: assertItemsEqual(actual, expected, msg=None) + + シーケンス *expected* が *actual* と同じ要素を含んでいることをテスト します。 + 要素の順序はテスト結果に影響しません。要素が含まれていない場合には、 + シーケンスの差分がエラーメッセージとして表示されます。 + + *actual* と *expected* の比較では、重複した要素は無視 *されません* 。 + 両者に同じ数の要素が含まれていることを検証します。このメソッドは + ``assertEqual(sorted(expected), sorted(actual))`` と同等に振る舞うこ とに加えて、 + ハッシュ化できないオブジェクトのシーケンスでも動作します。 + + .. versionadded:: 2.7 + + + .. method:: assertDictContainsSubset(expected, actual, msg=None) + + 辞書 *actual* のキー/バリューペアが *expected* のスーパーセットになっ ているかどうかを + テストします。そうなっていない場合には、足りないキーとバリューの一覧 が + エラーメッセージに表示されます。 + + .. versionadded:: 2.7 + .. deprecated:: 3.2 + + + + .. _type-specific-methods: + + :meth:`assertEqual` メソッドは、同じ型のオブジェクトの等価性確認のため に、 + 型ごとに特有のメソッドにディスパッチします。これらのメソッドは、ほとんど の組み込み型用の + メソッドは既に実装されています。さらに、 :meth:`addTypeEqualityFunc` を 使う事で + 新たなメソッドを登録することができます。 + + .. method:: addTypeEqualityFunc(typeobj, function) + + :meth:`assertEqual` で呼び出される型特有のメソッドを登録します。 + 登録するメソッドは、 比較する2つのオブジェクトの型がが厳密に *typeobj* と同じ + （サブクラスでもいけません）の場合に等価性を確認します。 *function* は + :meth:`assertEqual` と同様に、2つの位置固定引数と、3番目に msg=None のキーワード引数を + 取れる必要があります。このメソッドは、始めの2つに指定したパラメータ間 の差分を + 検出した時に :data:`self.failureException(msg) <failureException>` の 例外を投げる + 必要があります。この例外を投げる際は、出来る限り、エラーの内容が分か る有用な情報と + 差分の詳細をエラーメッセージに含めてください。 + + .. versionadded:: 2.7 + + :meth:`~TestCase.assertEqual` が自動的に呼び出す型特有のメソッドの概要を + 以下の表示に記載しています。これらのメソッドは通常は直接呼び出す必要がな い + ことに注意が必要です。 + + +-----------------------------------------+-----------------------------+--------------+ + | メソッド | 比較の対象 | 初出 | + +=========================================+=============================+==============+ + | :meth:`assertMultiLineEqual(a, b) | strings | 2.7 | + | <TestCase.assertMultiLineEqual>` | | | + +-----------------------------------------+-----------------------------+--------------+ + | :meth:`assertSequenceEqual(a, b) | sequences | 2.7 | + | <TestCase.assertSequenceEqual>` | | | + +-----------------------------------------+-----------------------------+--------------+ + | :meth:`assertListEqual(a, b) | lists | 2.7 | + | <TestCase.assertListEqual>` | | | + +-----------------------------------------+-----------------------------+--------------+ + | :meth:`assertTupleEqual(a, b) | tuples | 2.7 | + | <TestCase.assertTupleEqual>` | | | + +-----------------------------------------+-----------------------------+--------------+ + | :meth:`assertSetEqual(a, b) | sets or frozensets | 2.7 | + | <TestCase.assertSetEqual>` | | | + +-----------------------------------------+-----------------------------+--------------+ + | :meth:`assertDictEqual(a, b) | dicts | 2.7 | + | <TestCase.assertDictEqual>` | | | + +-----------------------------------------+-----------------------------+--------------+ + + + + .. method:: assertMultiLineEqual(first, second, msg=None) + + 複数行の文字列 *first* が文字列 *second* と等しいことをテストします。 + 等しくない場合には、両者の差分がハイライトされてエラーメッセージに表 示されます。 + このメソッドは、デフォルトで、 :meth:`assertEqual` が string を比較す るときに + 自動的に使用します。 + + .. versionadded:: 2.7 + + + .. method:: assertSequenceEqual(seq1, seq2, msg=None, seq_type=None) + + 2つのシーケンスが等しいことをテストします。 *seq_type* が指定された場 合、 + *seq1* と *seq2* が *seq_type* のインスタンスで無い場合にはテストが失 敗します。 + シーケンスどうしが異なる場合には、両者の差分がエラーメッセージに表示 されます。 + + このメソッドは直接 :meth:`assertEqual` からは呼ばれませんが、 + :meth:`assertListEqual` と :meth:`assertTupleEqual` の実装で使われて います。 + + .. versionadded:: 2.7 + + + .. method:: assertListEqual(list1, list2, msg=None) + assertTupleEqual(tuple1, tuple2, msg=None) + + 2つのリストまたはタプルが等しいかどうかをテストします。等しくない場合 には、 + 両者の差分を表示します。2つのパラメータの型が異なる場合には + テストがエラーになります。このメソッドは、デフォルト で、 :meth:`assertEqual` が + list または tuple を比較するときに自動的に使用します。 + + .. versionadded:: 2.7 + + + .. method:: assertSetEqual(set1, set2, msg=None) + + 2つのセットが等しいかどうかをテストします。等しくない場合には、 + 両者の差分を表示します。このメソッドは、デフォルト で、 :meth:`assertEqual` が + set もしくは frozenset を比較するときに自動的に使用します。 + + *set1* or *set2* のいずれかに :meth:`set.difference` が無い場合には + テストは失敗します。 + + .. versionadded:: 2.7 + + + .. method:: assertDictEqual(expected, actual, msg=None) + + 2つの辞書が等しいかどうかをテストします。等しくない場合には、 + 両者の差分を表示します。このメソッドは、デフォルト で、 :meth:`assertEqual` が + dict を比較するときに自動的に使用します。 + + .. versionadded:: 2.7 + + + + .. _other-methods-and-attrs: + + 最後に、 :class:`TestCase` の残りのメソッドと属性を紹介します。 + + + .. method:: fail(msg=None) + + 無条件にテストを失敗させます。 + エラーメッセージの表示に、 *msg* または ``None`` が使われます。 + + + .. attribute:: failureException + + :meth:`test` メソッドが送出する例外を指定するクラス属性です。 + 例えばテストフレームワークで追加情報を付した特殊な例外が必要になる場 合、 + この例外のサブクラスとして作成します。この属性の初期値 は :exc:`AssertionError` + です。 + + + .. attribute:: longMessage + + この属性に ``True`` が設定された場合、 :ref:`assert methods <assert-methods>` + で指定したすべての明示的な失敗メッセージが、通常の失敗メッセージに追 加されます。 + 通常の失敗メッセージには、オブジェクトに関する有用な情報が含まれてい ます。 + 例えば、 assertEqual は異なるオブジェクトの repr を表示します。 + この属性を ``True`` にすることで、カスタマイズしたエラーメッセージを 通常の + メッセージに追加することができます。 + + この属性はデフォルトで ``False`` になっていて、カスタムメッセージが渡 されても + 表示しないようになっています。 + + アサートメソッドを呼び出す前に、 + インスタンス属性として ``True`` または ``False`` を指定することで、 + この設定をオーバーライドすることができます。 + + .. versionadded:: 2.7 + + + .. attribute:: maxDiff + + この属性は、アサーションメソッドが失敗をレポートする時に表示する + 差分の長さをコントロールします。デフォルトは 80*8 文字です。 + この属性が影響するメソッドは、 + :meth:`assertSequenceEqual` （およびこのメソッドに委譲するシーケンス 比較メソッド）、 + :meth:`assertDictEqual` と :meth:`assertMultiLineEqual` です。 + + ``maxDiff`` に ``None`` を指定すると差分表示の上限がなくなります。 + + .. versionadded:: 2.7 + + + テストフレームワークは、テスト情報を収集するために以下のメソッドを使用 + します。 + + + .. method:: countTestCases() + + テストオブジェクトに含まれるテストの数を返します。 + :class:`TestCase` インスタンスは常に ``1`` を返します。 + + + .. method:: defaultTestResult() + + このテストケースクラスで使われるテスト結果クラスのインスタンスを ( + もし :meth:`run` メソッドに他の結果インスタンスが提供されないならば + ) 返します。 ***The diff for this file has been truncated for email.***
