目次

前のトピックへ

26.2. doctest — 対話モードを使った使用例の内容をテストする

次のトピックへ

26.4. 2to3 - Python 2 から 3 への自動コード変換

このページ

26.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() は引数として TestCaseTestSuite オブ ジェクトを受け取り、テスト結果を TestResult オブジェクトで戻 します。 unittest ではデフォルトでテスト結果を標準エラーに出力 する TextTestRunner をサンプルとして実装しています。これ以外 のランナー (グラフィックインターフェース用など) を実装する場合でも、特 定のクラスから派生する必要はありません。

参考

Module doctest
Another test-support module with a very different flavor.
Simple Smalltalk Testing: With Patterns
Kent Beck’s original paper on testing frameworks using the pattern shared by unittest.
Nose and py.test
Third-party unittest frameworks with a lighter-weight syntax for writing tests. For example, assert func(10) == 42.
python-mock and minimock
Tools for creating mock test objects (objects simulating external resources).

26.3.1. 基礎的な例

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

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

import random
import unittest

class TestSequenceFunctions(unittest.TestCase):

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

    def testshuffle(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 testchoice(self):
        element = random.choice(self.seq)
        self.assert_(element in self.seq)

    def testsample(self):
        self.assertRaises(ValueError, random.sample, self.seq, 20)
        for element in random.sample(self.seq, 5):
            self.assert_(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)

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

testchoice (__main__.TestSequenceFunctions) ... ok
testsample (__main__.TestSequenceFunctions) ... ok
testshuffle (__main__.TestSequenceFunctions) ... ok

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

OK

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

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

何らかのテストを行う場合、ベースクラス TestCaseassert*()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.failUnless(self.widget.size() == (50,50),
                        'incorrect default size')

class WidgetResizeTestCase(SimpleWidgetTestCase):
    def runTest(self):
        self.widget.resize(100,150)
        self.failUnless(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 testDefaultSize(self):
        self.failUnless(self.widget.size() == (50,50),
                        'incorrect default size')

    def testResize(self):
        self.widget.resize(100,150)
        self.failUnless(self.widget.size() == (100,150),
                        'wrong size after resize')

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

defaultSizeTestCase = WidgetTestCase('testDefaultSize')
resizeTestCase = WidgetTestCase('testResize')

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

widgetTestSuite = unittest.TestSuite()
widgetTestSuite.addTest(WidgetTestCase('testDefaultSize'))
widgetTestSuite.addTest(WidgetTestCase('testResize'))

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

def suite():
    suite = unittest.TestSuite()
    suite.addTest(WidgetTestCase('testDefaultSize'))
    suite.addTest(WidgetTestCase('testResize'))
    return suite

または:

def suite():
    tests = ['testDefaultSize', 'testResize']

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

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

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

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

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

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

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

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

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

26.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)

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

ノート

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

26.3.4. クラスと関数

class unittest.TestCase([methodName])

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

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

def suite():
    suite = unittest.TestSuite()
    suite.addTest(WidgetTestCase('testDefaultSize'))
    suite.addTest(WidgetTestCase('testResize'))
    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 で追加.

26.3.5. TestCase オブジェクト

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

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

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

TestCase.setUp()

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

TestCase.tearDown()

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

TestCase.run([result])

テストを実行し、テスト結果を result に指定されたテスト結果オブジェ クトに収集します。 resultNone か省略された場合、一時 的な結果オブジェクトを( 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])

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

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

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

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

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

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

firstsecondplaces (デフォルトは 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 を返します。

26.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()

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

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

26.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()

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

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

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

TestResult.startTest(test)

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

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

TestResult.stopTest(test)

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

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

TestResult.addError(test, err)

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

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

TestResult.addFailure(test, err)

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

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

TestResult.addSuccess(test)

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

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

26.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 インスタンスまたは TestCaseTestSuite のインスタンスを返す呼び出 し可能オブジェクトを指定します。このチェックはここで挙げた順番に行 なわれます。すなわち、候補テストケースクラス内のメソッドは「呼び出 し可能オブジェクト」としてではなく「テストケースクラス内のメソッド」 として拾い出されます。

例えば 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 中の全てのメソッド名を含むソート済みシーケンスを返 します。 testCaseClassTestCase のサブクラスでなけれ ばなりません。

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

TestLoader.testMethodPrefix

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

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

TestLoader.sortTestMethodsUsing

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

TestLoader.suiteClass

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

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