### ナビゲーション

- 索引
- モジュール |
- 次へ |
- 前へ |
- Python 2.6ja2 documentation »
- Python 標準ライブラリ »
- 25. 開発ツール »

# 25.3. `unittest` — ユニットテストフレームワーク

バージョン 2.1 で追加.

この Python ユニットテストフレームワークは時に “PyUnit” とも呼ばれ、 Kent Beck と Erich Gamma による JUnit の Python 版です。 JUnit はまた Kent の Smalltalk 用テストフレームワークの Java 版で、どちらもそれぞれの言語で業界標準のユニットテストフレームワークとなっています。

`unittest` では、テストの自動化・初期設定と終了処理の共有・テストの分類・テスト実行と結果レポートの分離などの機能を提供しており、 `unittest` のクラスを使って簡単にたくさんのテストを開発できるようになっています。

このようなことを実現するために `unittest` では、テストを以下のような構成で開発します。

test fixture (テストフィクスチャー)
  test fixture とは、テスト実行のために必要な準備や終了処理を指します。例: テスト用データベースの作成・ディレクトリ・サーバプロセスの起動など。
test case (テストケース)
  test case はテストの最小単位で、各入力に対する結果をチェックします。テストケースを作成する場合は、 `unittest` が提供する `TestCase` クラスを基底クラスとして利用することができます。
test suite (テストスイート)
  test suite はテストケースとテストスイートの集まりで、同時に実行しなければならないテストをまとめる場合に使用します。
test runner (テストランナー)
  test runner はテストの実行と結果表示を管理するコンポーネントです。ランナーはグラフィカルインターフェースでもテキストインターフェースでも良いですし、何も表示せずにテスト結果を示す値を返すだけの場合もあります。

`unittest` では、テストケースとテストフィクスチャーを、 `TestCase` クラスと `FunctionTestCase` クラスで提供しています。 `TestCase` クラスは新規にテストを作成する場合に使用し、 `FunctionTestCase` は既存のテストを `unittest` に組み込む場合に使用します。テストフィクスチャーの設定処理と終了処理は、 `TestCase` では `setUp()` メソッドと `tearDown()` をオーバーライドして記述し、 `FunctionTestCase` では初期設定・終了処理を行う既存の関数をコンストラクタで指定します。テスト実行時、まずテストフィクスチャーの初期設定が最初に実行されます。初期設定が正常終了した場合、テスト実行後にはテスト結果に関わらず終了処理が実行されます。 `TestCase` の各インスタンスが実行するテストは一つだけで、テストフィクスチャーは各テストごとに新しく作成されます。

テストスイートは `TestSuite` クラスで実装されており、複数のテストとテストスイートをまとめる事ができます。テストスイートを実行すると、スイートと子スイートに追加されている全てのテストが実行されます。

テストランナーは `run()` メソッドを持つオブジェクトで、 `run()` は引数として `TestCase` か `TestSuite` オブジェクトを受け取り、テスト結果を `TestResult` オブジェクトで戻します。 `unittest` ではデフォルトでテスト結果を標準エラーに出力する `TextTestRunner` をサンプルとして実装しています。これ以外のランナー (グラフィックインターフェース用など) を実装する場合でも、特定のクラスから派生する必要はありません。

参考

Module `doctest`
  もうひとつのテストをサポートするモジュールで、本モジュールと趣きが異なっています。
Simple Smalltalk Testing: With Patterns
  Kent Beck のテスティングフレームワークに関する原論文で、ここに記載されたパターンを `unittest` が使用しています。
Nose と py.test
  サードパーティのユニットテストフレームワークで軽量な文法でテストを書くことができます。例えば、 `assert func(10) == 42` のように書きます。
python-mock と minimock
  テスト用のモックオブジェクトを作成するツールです (モックオブジェクトは外部リソースをシミュレートします)。

## 25.3.1. 基礎的な例

`unittest` モジュールには、テストの開発や実行の為の優れたツールが用意されており、この節では、その一部を紹介します。ほとんどのユーザとっては、ここで紹介するツールだけで十分でしょう。

以下は、 `random` モジュールの三つの関数をテストするスクリプトです。:

    import random
    import unittest

    class TestSequenceFunctions(unittest.TestCase):

        def setUp(self):
            self.seq = range(10)

        def test_shuffle(self):
            # make sure the shuffled sequence does not lose any elements
            random.shuffle(self.seq)
            self.seq.sort()
            self.assertEqual(self.seq, range(10))

        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)
            for element in random.sample(self.seq, 5):
                self.assertTrue(element in self.seq)

    if __name__ == '__main__':
        unittest.main()

テストケースは、 `unittest.TestCase` のサブクラスとして作成します。メソッド名が `test` で始まる三つのメソッドがテストです。テストランナーはこの命名規約によってテストを行うメソッドを検索します。

これらのテスト内では、予定の結果が得られていることを確かめるために `assertEqual()` を、条件のチェックに `assert_()` を、例外が発生する事を確認するために `assertRaises()` をそれぞれ呼び出しています。 `assert` 文の代わりにこれらのメソッドを使用すると、テストランナーでテスト結果を集計してレポートを作成する事ができます。

`setUp()` メソッドが定義されている場合、テストランナーは各テストを実行する前に `setUp()` メソッドを呼び出します。同様に、 `tearDown()` メソッドが定義されている場合は各テストの実行後に呼び出します。上のサンプルでは、それぞれのテスト用に新しいシーケンスを作成するために `setUp()` を使用しています。

サンプルの末尾が、簡単なテストの実行方法です。 `unittest.main()` は、テストスクリプトのコマンドライン用インターフェースです。コマンドラインから起動された場合、上記のスクリプトから以下のような結果が出力されます:

    ...
    ----------------------------------------------------------------------
    Ran 3 tests in 0.000s

    OK

簡略化した結果を出力したり、コマンドライン以外からも起動する等のより細かい制御が必要であれば、 `unittest.main()` を使用せずに別の方法でテストを実行します。例えば、上記サンプルの最後の2行は以下のように書くことができます:

    suite = unittest.TestLoader().loadTestsFromTestCase(TestSequenceFunctions)
    unittest.TextTestRunner(verbosity=2).run(suite)

変更後のスクリプトをインタープリタや別のスクリプトから実行すると、以下の出力が得られます:

    test_choice (__main__.TestSequenceFunctions) ... ok
    test_sample (__main__.TestSequenceFunctions) ... ok
    test_shuffle (__main__.TestSequenceFunctions) ... ok

    ----------------------------------------------------------------------
    Ran 3 tests in 0.110s

    OK

以上が `unittest` モジュールでよく使われる機能で、ほとんどのテストではこれだけでも十分です。基礎となる概念や全ての機能については以降の章を参照してください。

## 25.3.2. テストの構成

ユニットテストの基礎となる構築要素は、 test case — セットアップと正しさのチェックを行う、独立したシナリオ — です。 `unittest` では、テストケースは `unittest` モジュールの `TestCase` クラスのインスタンスで示します。テストケースを作成するには `TestCase` のサブクラスを記述するか、または `FunctionTestCase` を使用します。

`TestCase` から派生したクラスのインスタンスは、このオブジェクトだけで一件のテストと初期設定・終了処理を行います。

`TestCase` インスタンスは外部から完全に独立し、単独で実行する事も、他の任意のテストと一緒に実行する事もできなければなりません。

以下のように、 `TestCase` のサブクラスは `runTest()` をオーバライドし、必要なテスト処理を記述するだけで簡単に書くことができます:

    import unittest

    class DefaultWidgetSizeTestCase(unittest.TestCase):
        def runTest(self):
            widget = Widget('The widget')
            self.assertEqual(widget.size(), (50,50), 'incorrect default size')

何らかのテストを行う場合、ベースクラス `TestCase` の `assert*()` か `fail*()` メソッドを使用してください。テストが失敗すると例外が送出され、 `unittest` はテスト結果を failure とします。その他の例外は error となります。これによりどこに問題があるかが判ります。 failure は間違った結果 (6 になるはずが 5 だった) で発生します。 error は間違ったコード (たとえば間違った関数呼び出しによる `TypeError`) で発生します。

テストの実行方法については後述とし、まずはテストケースインスタンスの作成方法を示します。テストケースインスタンスは、以下のように引数なしでコンストラクタを呼び出して作成します。:

    testCase = DefaultWidgetSizeTestCase()

似たようなテストを数多く行う場合、同じ環境設定処理を何度も必要となります。例えば上記のような Widget のテストが 100 種類も必要な場合、それぞれのサブクラスで `Widget` オブジェクトを生成する処理を記述するのは好ましくありません。

このような場合、初期化処理は `setUp()` メソッドに切り出し、テスト実行時にテストフレームワークが自動的に実行するようにすることができます:

    import unittest

    class SimpleWidgetTestCase(unittest.TestCase):
        def setUp(self):
            self.widget = Widget('The widget')

    class DefaultWidgetSizeTestCase(SimpleWidgetTestCase):
        def runTest(self):
            self.assertEqual(self.widget.size(), (50,50),
                            'incorrect default size')

    class WidgetResizeTestCase(SimpleWidgetTestCase):
        def runTest(self):
            self.widget.resize(100,150)
            self.assertEqual(self.widget.size(), (100,150),
                            'wrong size after resize')

テスト中に `setUp()` メソッドで例外が発生した場合、テストフレームワークはテストを実行することができないとみなし、 `runTest()` を実行しません。

同様に、終了処理を `tearDown()` メソッドに記述すると、 `runTest()` メソッド終了後に実行されます:

    import unittest

    class SimpleWidgetTestCase(unittest.TestCase):
        def setUp(self):
            self.widget = Widget('The widget')

        def tearDown(self):
            self.widget.dispose()
            self.widget = None

`setUp()` が正常終了した場合、 `runTest()` が成功したかどうかに従って `tearDown()` が実行されます。

このような、テストを実行する環境を fixture と呼びます。

JUnit では、多数の小さなテストケースを同じテスト環境で実行する場合、全てのテストについて `DefaultWidgetSizeTestCase` のような `SimpleWidgetTestCase` のサブクラスを作成する必要があります。これは時間のかかる、うんざりする作業ですので、 `unittest` ではより簡単なメカニズムを用意しています:

    import unittest

    class WidgetTestCase(unittest.TestCase):
        def setUp(self):
            self.widget = Widget('The widget')

        def tearDown(self):
            self.widget.dispose()
            self.widget = None

        def test_default_size(self):
            self.assertEqual(self.widget.size(), (50,50),
                             'incorrect default size')

        def test_resize(self):
            self.widget.resize(100,150)
            self.assertEqual(self.widget.size(), (100,150),
                             'wrong size after resize')

この例では `runTest()` がありませんが、二つのテストメソッドを定義しています。このクラスのインスタンスは `test_*()` メソッドのどちらか一方の実行と、 `self.widget` の生成・解放を行います。この場合、テストケースインスタンス生成時に、コンストラクタの引数として実行するメソッド名を指定します:

    defaultSizeTestCase = WidgetTestCase('test_default_size')
    resizeTestCase = WidgetTestCase('test_resize')

`unittest` では `test suite` によってテストケースインスタンスをテスト対象の機能によってグループ化することができます。 test suite は、 `unittest` の `TestSuite` クラスで作成します。:

    widgetTestSuite = unittest.TestSuite()
    widgetTestSuite.addTest(WidgetTestCase('test_default_size'))
    widgetTestSuite.addTest(WidgetTestCase('test_resize'))

各テストモジュールで、テストケースを組み込んだテストスイートオブジェクトを作成する呼び出し可能オブジェクトを用意しておくと、テストの実行や参照が容易になります:

    def suite():
        suite = unittest.TestSuite()
        suite.addTest(WidgetTestCase('test_default_size'))
        suite.addTest(WidgetTestCase('test_resize'))
        return suite

または:

    def suite():
        tests = ['test_default_size', 'test_resize']

        return unittest.TestSuite(map(WidgetTestCase, tests))

一般的には、 `TestCase` のサブクラスには良く似た名前のテスト関数が複数定義されますので、 `unittest` ではテストスイートを作成して個々のテストで満たすプロセスを自動化するのに使う `TestLoader` を用意しています。たとえば、:

    suite = unittest.TestLoader().loadTestsFromTestCase(WidgetTestCase)

は `WidgetTestCase.test_default_size()` と `WidgetTestCase.test_resize` を走らせるテストスイートを作成します。 `TestLoader` は自動的にテストメソッドを識別するのに `'test'` というメソッド名の接頭辞を使います。

いろいろなテストケースが実行される順序は、テスト関数名を組み込み関数 `cmp()` でソートして決定されます。

システム全体のテストを行う場合など、テストスイートをさらにグループ化したい場合がありますが、このような場合、 `TestSuite` インスタンスには `TestSuite` と同じように `TestSuite` を追加する事ができます。:

    suite1 = module1.TheTestSuite()
    suite2 = module2.TheTestSuite()
    alltests = unittest.TestSuite([suite1, suite2])

テストケースやテストスイートは (`widget.py` のような) テスト対象のモジュール内にも記述できますが、テストは (`test_widget.py` のような) 独立したモジュールに置いた方が以下のような点で有利です:

- テストモジュールだけをコマンドラインから実行することができる。
- テストコードと出荷するコードを分離する事ができる。
- テストコードを、テスト対象のコードに合わせて修正する誘惑に駆られにくい。
- テストコードは、テスト対象コードほど頻繁に更新されない。
- テストコードをより簡単にリファクタリングすることができる。
- Cで書いたモジュールのテストは、どっちにしろ独立したモジュールとなる。
- テスト戦略を変更した場合でも、ソースコードを変更する必要がない。

## 25.3.3. 既存テストコードの再利用

既存のテストコードが有るとき、このテストを `unittest` で実行しようとするために古いテスト関数をいちいち `TestCase` クラスのサブクラスに変換するのは大変です。

このような場合は、 `unittest` では `TestCase` のサブクラスである `FunctionTestCase` クラスを使い、既存のテスト関数をラップします。初期設定と終了処理も行なえます。

以下のテストコードがあった場合:

    def testSomething():
        something = makeSomething()
        assert something.name is not None
        # ...

テストケースインスタンスは次のように作成します:

    testcase = unittest.FunctionTestCase(testSomething)

初期設定、終了処理が必要な場合は、次のように指定します:

    testcase = unittest.FunctionTestCase(testSomething,
                                         setUp=makeSomethingDB,
                                         tearDown=deleteSomethingDB)

既存のテストスイートからの移行を容易にするため、 `unittest` は `AssertionError` の送出でテストの失敗を示すような書き方もサポートしています。しかしながら、 `TestCase.fail*()` および `TestCase.assert*()` メソッドを使って明確に書くことが推奨されています。 `unittest` の将来のバージョンでは、 `AssertionError` は別の目的に使用される可能性が有ります。

ノート

`FunctionTestCase` を使って既存のテストを `unittest` ベースのテスト体系に変換することができますが、この方法は推奨されません。時間を掛けて `TestCase` のサブクラスに書き直した方が将来的なテストのリファクタリングが限りなく易しくなります。

## 25.3.4. クラスと関数

class `unittest.``TestCase`([methodName])

  `TestCase` クラスのインスタンスは、 `unittest` の世界におけるテストの最小実行単位を示します。このクラスをベースクラスとして使用し、必要なテストを具象サブクラスに実装します。 `TestCase` クラスでは、テストランナーがテストを実行するためのインターフェースと、各種のチェックやテスト失敗をレポートするためのメソッドを実装しています。

  それぞれの `TestCase` クラスのインスタンスはただ一つのテストメソッド、 methodName という名のメソッドを実行します。既に次のような例を扱ったことを憶えているでしょうか。:

      def suite():
          suite = unittest.TestSuite()
          suite.addTest(WidgetTestCase('test_default_size'))
          suite.addTest(WidgetTestCase('test_resize'))
          return suite

  ここでは、それぞれが一つずつのテストを実行するような `WidgetTestCase` の二つのインスタンスを作成しています。

  methodName のデフォルトは `'runTest'` です。

class `unittest.``FunctionTestCase`(testFunc[, setUp[, tearDown[, description]]])

  このクラスでは `TestCase` インターフェースの内、テストランナーがテストを実行するためのインターフェースだけを実装しており、テスト結果のチェックやレポートに関するメソッドは実装していません。既存のテストコードを `unittest` によるテストフレームワークに組み込むために使用します。

class `unittest.``TestSuite`([tests])

  このクラスは、個々のテストケースやテストスイートの集約を示します。通常のテストケースと同じようにテストランナーで実行するためのインタフェースを備えています。 `TestSuite` インスタンスを実行することはスイートの繰り返しを使って個々のテストを実行することと同じです。

  引数 tests が与えられるならば、それはテストケースに亘る繰り返し可能オブジェクトまたは内部でスイートを組み立てるための他のテストスイートでなければなりません。後からテストケースやスイートをコレクションに付け加えるためのメソッドも提供されています。

class `unittest.``TestLoader`

  モジュールまたは `TestCase` クラスから、指定した条件に従ってテストをロードし、 `TestSuite` にラップして返します。このクラスは与えられたモジュールまたは `TestCase` のサブクラスの中から全てのテストをロードできます。

class `unittest.``TestResult`

  このクラスはどのテストが成功しどのテストが失敗したかの情報を集積するのに使います。

`unittest.``defaultTestLoader`

  `TestLoader` のインスタンスで、共用することが目的です。 `TestLoader` をカスタマイズする必要がなければ、新しい `TestLoader` オブジェクトを作らずにこのインスタンスを使用します。

class `unittest.``TextTestRunner`([stream[, descriptions[, verbosity]]])

  実行結果を標準エラーに出力する、単純なテストランナー。いくつかの設定項目がありますが、非常に単純です。グラフィカルなテスト実行アプリケーションでは、独自のテストランナーを作成してください。

`unittest.``main`([module[, defaultTest[, argv[, testRunner[, testLoader]]]]])

  テストを実行するためのコマンドラインプログラム。この関数を使えば、簡単に実行可能なテストモジュールを作成する事ができます。一番簡単なこの関数の使い方は、以下の行をテストスクリプトの最後に置くことです。

      if __name__ == '__main__':
          unittest.main()

  引数、 testRunner は、test runner class、あるいは、そのインスタンスのどちらでも構いません。

場合によっては、 `doctest` モジュールを使って書かれた既存のテストがあります。その場合、モジュールは既存の `doctest` に基づいたテストコードから `unittest.TestSuite` インスタンスを自動的に構築できる `DocTestSuite` クラスを提供します。

バージョン 2.3 で追加.

## 25.3.5. TestCase オブジェクト

`TestCase` クラスのインスタンスは個別のテストをあらわすオブジェクトですが、 `TestCase` の具象サブクラスには複数のテストを定義する事ができます — 具象サブクラスは、特定の fixture (テスト設備) を示している、と考えてください。 fixture は、それぞれのテストケースごとに作成・解放されます。

`TestCase` インスタンスには、次の3種類のメソッドがあります: テストを実行するためのメソッド・条件のチェックやテスト失敗のレポートのためのメソッド・テストの情報収集に使用する問い合わせメソッドです。

テストを実行するためのメソッドを以下に示します:

`TestCase.``setUp`()

  テストを実行する直前に、 fixture を作成する為に呼び出されます。このメソッドを実行中に例外が発生した場合、テストの失敗ではなくエラーとされます。デフォルトの実装では何も行いません。

`TestCase.``tearDown`()

  テストを実行し、結果を記録した直後に呼び出されます。テスト実行中に例外が発生しても呼び出されますので、内部状態に注意して処理を行ってください。メソッドを実行中に例外が発生した場合、テストの失敗ではなくエラーとみなされます。このメソッドは、 `setUp()` が正常終了した場合にはテストメソッドの実行結果に関わり無く呼び出されます。デフォルトの実装では何も行いません。

`TestCase.``run`([result])

  テストを実行し、テスト結果を result に指定されたテスト結果オブジェクトに収集します。 result が `None` か省略された場合、一時的な結果オブジェクトを( `defaultTestCase()` メソッドを呼んで)生成して使用しますが `run()` の呼び出し元には渡されません。

  このメソッドは、 `TestCase` インスタンスの呼び出しと等価です。

`TestCase.``debug`()

  テスト結果を収集せずにテストを実行します。例外が呼び出し元に通知されるため、テストをデバッガで実行することができます。

テスト結果のチェックとレポートには、以下のメソッドを使用してください。

`TestCase.``assert_`(expr[, msg])
`TestCase.``failUnless`(expr[, msg])
`TestCase.``assertTrue`(expr[, msg])
  expr が偽の場合、テスト失敗を通知します。 msg にはエラーの説明
    を指定するか、または `None` を指定してください。

`TestCase.``assertEqual`(first, second[, msg])
`TestCase.``failUnlessEqual`(first, second[, msg])

  first と second expr が等しくない場合、テスト失敗を通知します。エラー内容は msg に指定された値か、または `None` となります。 `failUnlessEqual()` では msg のデフォルト値は first と second を含んだ文字列となりますので、 `failUnless()` の第一引数に比較の結果を指定するよりも便利です。

`TestCase.``assertNotEqual`(first, second[, msg])
`TestCase.``failIfEqual`(first, second[, msg])

  first と second expr が等しい場合、テスト失敗を通知します。エラー内容は msg に指定された値か、または `None` となります。 `failUnlessEqual()` では msg のデフォルト値は first と second を含んだ文字列となりますので、 `failUnless()` の第一引数に比較の結果を指定するよりも便利です。

`TestCase.``assertAlmostEqual`(first, second[, places[, msg]])
`TestCase.``failUnlessAlmostEqual`(first, second[, places[, msg]])

  first と second を places (デフォルトは 7 です) で与えた小数位で値を丸めて差分を計算し、ゼロと比較することで、近似的に等価であるかどうかをテストします。指定小数位の比較というものは指定有効桁数の比較ではないので注意してください。値の比較結果が等しくなかった場合、テストは失敗し、 msg で指定した説明か、 `None` を返します。

`TestCase.``assertNotAlmostEqual`(first, second[, places[, msg]])
`TestCase.``failUnlessAlmostEqual`(first, second[, places[, msg]])

  first と second を places (デフォルトは 7 です) で与えた小数位で値を丸めて差分を計算し、ゼロと比較することで、近似的に等価でないかどうかをテストします。指定小数位の比較というものは指定有効桁数の比較ではないので注意してください。値の比較結果が等しかった場合、テストは失敗し、 msg で与えた説明か、 `None` を返します。

`TestCase.``assertRaises`(exception, callable, ...)
`TestCase.``failUnlessRaises`(exception, callable, ...)

  callable を呼び出し、発生した例外をテストします。 `assertRaises()` には、任意の位置パラメータとキーワードパラメータを指定する事ができます。 exception で指定した例外が発生した場合はテスト成功とし、それ以外の例外が発生するか例外が発生しない場合にテスト失敗となります。複数の例外を指定する場合には、例外クラスのタプルを exception に指定します。

`TestCase.``failIf`(expr[, msg])
`TestCase.``assertFalse`(expr[, msg])

  `failIf()` は `failUnless()` の逆で、 expr が真の場合、テスト失敗を通知します。エラー内容は msg に指定された値か、または `None` となります。

`TestCase.``fail`([msg])

  無条件にテスト失敗を通知します。エラー内容は msg に指定された値か、または `None` となります。

`TestCase.``failureException`

  `test()` メソッドが送出する例外を指定するクラス属性。テストフレームワークで追加情報を持つ等の特殊な例外を使用する場合、この例外のサブクラスとして作成します。この属性の初期値は `AssertionError` です。

テストフレームワークは、テスト情報を収集するために以下のメソッドを使用します:

`TestCase.``countTestCases`()

  テストオブジェクトに含まれるテストの数を返します。 `TestCase` インスタンスは常に `1` を返します。

`TestCase.``defaultTestResult`()

  このテストケースクラスで使われるテスト結果クラスのインスタンスを ( もし `run()` メソッドに他の結果インスタンスが提供されないならば ) 返します。

  `TestCase` インスタンスに対しては、いつも `TestResult` のインスタンスですので、 `TestCase` のサブクラスでは必要に応じてこのメソッドをオーバライドしてください。

`TestCase.``id`()

  テストケースを特定する文字列を返します。通常、 id はモジュール名・クラス名を含む、テストメソッドのフルネームを指定します。

`TestCase.``shortDescription`()

  テストの説明を一行分、または説明がない場合には `None` を返します。デフォルトでは、テストメソッドの docstring の先頭の一行、または `None` を返します。

## 25.3.6. TestSuite オブジェクト

`TestSuite` オブジェクトは `TestCase` とよく似た動作をしますが、実際のテストは実装せず、一まとめにに実行するテストのグループをまとめるために使用します。 `TestSuite` には以下のメソッドが追加されています:

`TestSuite.``addTest`(test)

  `TestCase` 又は `TestSuite` のインスタンスをスイートに追加します。

`TestSuite.``addTests`(tests)

  イテラブル tests に含まれる全ての `TestCase` 又は `TestSuite` のインスタンスをスイートに追加します。

  このメソッドは test 上のイテレーションをしながらそれぞれの要素に `addTest()` を呼び出すのと等価です。

`TestSuite` クラスは `TestCase` と以下のメソッドを共有します:

`TestSuite.``run`(result)

  スイート内のテストを実行し、結果を result で指定した結果オブジェクトに収集します。 `TestCase.run()` と異なり、 `TestSuite.run()` では必ず結果オブジェクトを指定する必要があります。

`TestSuite.``debug`()

  このスイートに関連づけられたテストを結果を収集せずに実行します。これによりテストで送出された例外は呼び出し元に伝わるようになり、デバッガの下でのテスト実行をサポートできるようになります。

`TestSuite.``countTestCases`()

  このテストオブジェクトによって表現されるテストの数を返します。これには個別のテストと下位のスイートも含まれます。

通常、 `TestSuite` の `run()` メソッドは `TestRunner` が起動するため、ユーザが直接実行する必要はありません。

## 25.3.7. TestResultオブジェクト

`TestResult` は、複数のテスト結果を記録します。 `TestCase` クラスと `TestSuite` クラスのテスト結果を正しく記録しますので、テスト開発者が独自にテスト結果を管理する処理を開発する必要はありません。

`unittest` を利用したテストフレームワークでは、 `TestRunner.run()` が返す `TestResult` インスタンスを参照し、テスト結果をレポートします。

以下の属性は、テストの実行結果を検査する際に使用することができます:

`TestResult.``errors`

  `TestCase` と例外のトレースバック情報をフォーマットした文字列の 2 要素タプルからなるリスト。それぞれのタプルは予想外の例外を送出したテストに対応します。

  バージョン 2.2 で変更: `sys.exc_info()` の結果ではなく、フォーマットしたトレースバッ クを保存します。

`TestResult.``failures`

  `TestCase` と例外のトレースバック情報をフォーマットした文字列の 2 要素タプルからなるリスト。それぞれのタプルは `TestCase.fail*()` や `TestCase.assert*()` メソッドを使って見つけ出した失敗に対応します。

  バージョン 2.2 で変更: `sys.exc_info()` の結果ではなく、フォーマットしたトレースバッ クを保存します。

`TestResult.``testsRun`

  これまでに実行したテストの総数です。

`TestResult.``wasSuccessful`()

  これまでに実行したテストが全て成功していれば `True` を、それ以外なら `False` を返します。

`TestResult.``stop`()

  このメソッドを呼び出して `TestResult` の `shouldStop` 属性に `True` をセットすることで、実行中のテストは中断しなければならないというシグナルを送ることができます。 `TestRunner` オブジェクトはこのフラグを尊重してそれ以上のテストを実行することなく復帰しなければなりません。

  たとえばこの機能は、ユーザのキーボード割り込みを受け取って `TextTestRunner` クラスがテストフレームワークを停止させるのに使えます。 `TestRunner` の実装を提供する対話的なツールでも同じように使用することができます。

以下のメソッドは内部データ管理用のメソッドですが、対話的にテスト結果をレポートするテストツールを開発する場合などにはサブクラスで拡張することができます。

`TestResult.``startTest`(test)

  test を実行する直前に呼び出されます。

  デフォルトの実装では単純にインスタンスの `testRun` カウンタをインクリメントします。

`TestResult.``stopTest`(test)

  test の実行直後に、テスト結果に関わらず呼び出されます。

  デフォルトの実装では何もしません。

`TestResult.``addError`(test, err)

  テスト test 実行中に、想定外の例外が発生した場合に呼び出されます。 err は `sys.exc_info()` が返すタプル `(type, value, traceback)` です。

  デフォルトの実装では、タプル、 `(test, formatted_err)` をインスタンスの `errors` 属性に追加します。ここで、 formatted_err は、 err から導出される、整形されたトレースバックです。

`TestResult.``addFailure`(test, err)

  テストが失敗した場合に呼び出されます。 err は `sys.exc_info()` が返すタプル `(type, value, traceback)` です。

  デフォルトの実装では、タプル、 `(test, formatted_err)` をインスタンスの `errors` 属性に追加します。ここで、 formatted_err は、 err から導出される、整形されたトレースバックです。

`TestResult.``addSuccess`(test)

  テストケース test が成功した場合に呼び出されます。

  デフォルトの実装では何もしません。

## 25.3.8. TestLoader オブジェクト

`TestLoader` クラスは、クラスやモジュールからテストスイートを作成するために使用します。通常はこのクラスのインスタンスを作成する必要はなく、 `unittest` モジュールのモジュール属性 `unittest.defaultTestLoader` を共用インスタンスとして使用することができます。ただ、サブクラスや別のインスタンスを活用すると設定可能なプロパティをカスタマイズすることもできます。

`TestLoader` オブジェクトには以下のメソッドがあります:

`TestLoader.``loadTestsFromTestCase`(testCaseClass)

  `TestCase` の派生クラス `testCaseClass` に含まれる全テストケースのスイートを返します。

`TestLoader.``loadTestsFromModule`(module)

  指定したモジュールに含まれる全テストケースのスイートを返します。このメソッドは module 内の `TestCase` 派生クラスを検索し、見つかったクラスのテストメソッドごとにクラスのインスタンスを作成します。

  警告

  `TestCase` クラスを基底クラスとしてクラス階層を構築すると fixture や補助的な関数をうまく共用することができますが、基底クラスに直接インスタンス化できないテストメソッドがあると、この `loadTestsFromModule()` を使うことができません。この場合でも、 fixture が全て別々で定義がサブクラスにある場合は使用することができます。

`TestLoader.``loadTestsFromName`(name[, module])

  文字列で指定される全テストケースを含むスイートを返します。

  name には “ドット修飾名” でモジュールかテストケースクラス、テストケースクラス内のメソッド、 `TestSuite` インスタンスまたは `TestCase` か `TestSuite` のインスタンスを返す呼び出し可能オブジェクトを指定します。このチェックはここで挙げた順番に行なわれます。すなわち、候補テストケースクラス内のメソッドは「呼び出し可能オブジェクト」としてではなく「テストケースクラス内のメソッド」として拾い出されます。

  例えば `SampleTests` モジュールに `TestCase` から派生した `SampleTestCase` クラスがあり、 `SampleTestCase` にはテストメソッド `test_one()` ・ `test_two()` ・ `test_three()` があるとします。この場合、 name に `'SampleTests.SampleTestCase'` と指定すると、 `SampleTestCase` の三つのテストメソッドを実行するテストスイートが作成されます。 `'SampleTests.SampleTestCase.test_two'` と指定すれば、 `test_two()` だけを実行するテストスイートが作成されます。インポートされていないモジュールやパッケージ名を含んだ名前を指定した場合は自動的にインポートされます。

  また、 module を指定した場合、 module 内の name を取得します。

`TestLoader.``loadTestsFromNames`(names[, module])

  `loadTestsFromName()` と同じですが、名前を一つだけ指定するのではなく、複数の名前のシーケンスを指定する事ができます。戻り値は names 中の名前で指定されるテスト全てを含むテストスイートです。

`TestLoader.``getTestCaseNames`(testCaseClass)

  testCaseClass 中の全てのメソッド名を含むソート済みシーケンスを返します。 testCaseClass は `TestCase` のサブクラスでなければなりません。

以下の属性は、サブクラス化またはインスタンスの属性値を変更して `TestLoader` をカスタマイズする場合に使用します。

`TestLoader.``testMethodPrefix`

  テストメソッドの名前と判断されるメソッド名の接頭語を示す文字列。デフォルト値は `'test'` です。

  この値は `getTestCaseNames()` と全ての `loadTestsFrom*()` メソッドに影響を与えます。

`TestLoader.``sortTestMethodsUsing`

  `getTestCaseNames()` および全ての `loadTestsFrom*()` メソッドでメソッド名をソートする際に使用する比較関数。デフォルト値は組み込み関数 `cmp()` です。ソートを行なわないようにこの属性に `None` を指定することもできます。

`TestLoader.``suiteClass`

  テストのリストからテストスイートを構築する呼び出し可能オブジェクト。メソッドを持つ必要はありません。デフォルト値は `TestSuite` です。

  この値は全ての `loadTestsFrom*()` メソッドに影響を与えます。

### ナビゲーション

- 索引
- モジュール |
- 次へ |
- 前へ |
- Python 2.6ja2 documentation »
- Python 標準ライブラリ »
- 25. 開発ツール »