\section{\module{unittest} ---
         単体テストフレームワーク}

\declaremodule{standard}{unittest}
\modulesynopsis{単体テストフレームワーク}
\moduleauthor{Steve Purcell}{stephen\textunderscore{}purcell@yahoo.com}
\sectionauthor{Steve Purcell}{stephen\textunderscore{}purcell@yahoo.com}
\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
\sectionauthor{Raymond Hettinger}{python@rcn.com}

\versionadded{2.1}

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

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

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

\begin{definitions}
\term{Fixture}

\dfn{test fixture(テスト設備)}とは、テスト実行のために必要な準備や終了処
理を指します。例:テスト用データベースの作成・ディレクトリ・サーバプロセ
スの起動など。

\term{テストケース}

\dfn{テストケース}はテストの最小単位で、各入力に対する結果をチェックしま
す。テストケースを作成する場合は、\module{unittest}が提供する\class{TestCase}クラス
を基底クラスとして利用することができます。


\term{テストスイート}

\dfn{テストスイート}はテストケースとテストスイートの集まりで、同時に実行
しなければならないテストをまとめる場合に使用します。

\term{テストランナー}

\dfn{テストランナー}はテストの実行と結果表示を管理するコンポーネントで
す。ランナーはグラフィカルインターフェースでもテキストインターフェースで
も良いですし、何も表示せずにテスト結果を示す値を返すだけの場合もありま
す。
\end{definitions}

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

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

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

\begin{seealso}
  \seemodule{doctest}{Another test-support module with a very
                      different flavor.}
  \seetitle[http://www.XProgramming.com/testfram.htm]{Simple Smalltalk
            Testing: With Patterns}{Kent Beck's original paper on
            testing frameworks using the pattern shared by
            \module{unittest}.}
\end{seealso}

\subsection{基礎的な例 \label{minimal-example}}

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

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

\begin{verbatim}
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()
\end{verbatim}

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

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

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

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

\begin{verbatim}
...
----------------------------------------------------------------------
Ran 3 tests in 0.000s

OK
\end{verbatim}

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

\begin{verbatim}
suite = unittest.TestLoader().loadTestsFromTestCase(TestSequenceFunctions)
unittest.TextTestRunner(verbosity=2).run(suite)
\end{verbatim}

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

\begin{verbatim}
testchoice (__main__.TestSequenceFunctions) ... ok
testsample (__main__.TestSequenceFunctions) ... ok
testshuffle (__main__.TestSequenceFunctions) ... ok

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

OK
\end{verbatim}

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

\subsection{テストの構成
            \label{organizing-tests}}

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

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

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

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

\begin{verbatim}
import unittest

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


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

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

\begin{verbatim}
testCase = DefaultWidgetSizeTestCase()
\end{verbatim}

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

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

\begin{verbatim}
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')
\end{verbatim}

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

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

\begin{verbatim}
import unittest

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

    def tearDown(self):
        self.widget.dispose()
        self.widget = None
\end{verbatim}

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

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

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

\begin{verbatim}
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')
\end{verbatim}

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

\begin{verbatim}
defaultSizeTestCase = WidgetTestCase('testDefaultSize')
resizeTestCase = WidgetTestCase('testResize')
\end{verbatim}

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


\begin{verbatim}
widgetTestSuite = unittest.TestSuite()
widgetTestSuite.addTest(WidgetTestCase('testDefaultSize'))
widgetTestSuite.addTest(WidgetTestCase('testResize'))
\end{verbatim}

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

\begin{verbatim}
def suite():
    suite = unittest.TestSuite()
    suite.addTest(WidgetTestCase('testDefaultSize'))
    suite.addTest(WidgetTestCase('testResize'))
    return suite
\end{verbatim}

または:

\begin{verbatim}
def suite():
    tests = ['testDefaultSize', 'testResize']

    return unittest.TestSuite(map(WidgetTestCase, tests))
\end{verbatim}

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

\begin{verbatim}
suite = unittest.TestLoader().loadTestsFromTestCase(WidgetTestCase)
\end{verbatim}

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

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

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


\begin{verbatim}
suite1 = module1.TheTestSuite()
suite2 = module2.TheTestSuite()
alltests = unittest.TestSuite([suite1, suite2])
\end{verbatim}

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

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


\subsection{既存テストコードの再利用
            \label{legacy-unit-tests}}

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

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

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

\begin{verbatim}
def testSomething():
    something = makeSomething()
    assert something.name is not None
    # ...
\end{verbatim}

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

\begin{verbatim}
testcase = unittest.FunctionTestCase(testSomething)
\end{verbatim}

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

\begin{verbatim}
testcase = unittest.FunctionTestCase(testSomething,
                                     setUp=makeSomethingDB,
                                     tearDown=deleteSomethingDB)
\end{verbatim}

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

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


\subsection{クラスと関数
            \label{unittest-contents}}

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

  それぞれの\class{TestCase}クラスのインスタンスはただ一つのテストメソッド、
  \var{methodName}という名のメソッドを実行します。既に次のような例を扱った
  ことを憶えているでしょうか。
  
  \begin{verbatim}
  def suite():
      suite = unittest.TestSuite()
      suite.addTest(WidgetTestCase('testDefaultSize'))
      suite.addTest(WidgetTestCase('testResize'))
      return suite
  \end{verbatim}

  ここでは、それぞれが一つずつのテストを実行するような\class{WidgetTestCase}の
  二つのインスタンスを作成しています。
  
  \var{methodName}のデフォルトは\code{'runTest'}です。
\end{classdesc}

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

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

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

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

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

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

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

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

\begin{verbatim}
if __name__ == '__main__':
    unittest.main()
\end{verbatim}
\end{funcdesc}

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



\subsection{TestCase オブジェクト
            \label{testcase-objects}}

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

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

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

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

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

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

  このメソッドは、\class{TestCase}インスタンスの呼び出しと等価です。
\end{methoddesc}

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

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

\begin{methoddesc}[TestCase]{assert_}{expr\optional{, msg}}
\methodline[TestCase]{failUnless}{expr\optional{, msg}}
  \var{expr}が偽の場合、テスト失敗を通知します。\var{msg}にはエラーの説
  明を指定するか、または\constant{None}を指定してください。
\end{methoddesc}

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

\begin{methoddesc}[TestCase]{assertNotEqual}{first, second\optional{, msg}}
\methodline[TestCase]{failIfEqual}{first, second\optional{, msg}}
  \var{first}と\var{second}\var{expr}が等しい場合、テスト失敗を通知しま
  す。エラー内容は\var{msg}に指定された値か、または\constant{None}となりま
  す。\method{failUnlessEqual()}では\var{msg}のデフォルト値は\var{first}
  と\var{second}を含んだ文字列となりますので、\method{failUnless()}の第
  一引数に比較の結果を指定するよりも便利です。
\end{methoddesc}

\begin{methoddesc}[TestCase]{assertAlmostEqual}{first, second\optional{,
						places\optional{, msg}}}
\methodline[TestCase]{failUnlessAlmostEqual}{first, second\optional{,
						places\optional{, msg}}}
\var{first} と \var{second} を
\var{places} で与えた小数位で値を丸めて差分を計算し、
ゼロと比較することで、近似的に等価であるかどうかをテストします。
指定小数位の比較というものは指定有効桁数の比較ではないので注意してください。
値の比較結果が等しくなかった場合、テストは失敗し、\var{msg} で指定した
説明か、\constant{None} を返します。
\end{methoddesc}

\begin{methoddesc}[TestCase]{assertNotAlmostEqual}{first, second\optional{,
						places\optional{, msg}}}
\methodline[TestCase]{failUnlessAlmostEqual}{first, second\optional{,
						places\optional{, msg}}}
\var{first} と \var{second} を
\var{places} で与えた小数位で値を丸めて差分を計算し、
ゼロと比較することで、近似的に等価でないかどうかをテストします。
指定小数位の比較というものは指定有効桁数の比較ではないので注意してください。
値の比較結果が等しかった場合、テストは失敗し、\var{msg} で与えた
説明か、\constant{None} を返します。
\end{methoddesc}



\begin{methoddesc}[TestCase]{assertRaises}{exception, callable, \moreargs}
\methodline[TestCase]{failUnlessRaises}{exception, callable, \moreargs}
  \var{callable}を呼び出し、発生した例外をテストします。
  \method{assertRaises()}には、任意の位置パラメータとキーワードパラメー
  タを指定する事ができます。\var{exception}で指定した例外が発生した場合
  はテスト成功とし、それ以外の例外が発生するか例外が発生しない場合にテス
  ト失敗となります。複数の例外を指定する場合には、例外クラスのタプルを
  \var{exception}に指定します。
\end{methoddesc}

\begin{methoddesc}[TestCase]{failIf}{expr\optional{, msg}}
  \method{failIf()}は\method{failUnless()}の逆で、\var{expr}が真の場合、
  テスト失敗を通知します。エラー内容は\var{msg}に指定された値か、または
  \constant{None}となります。
\end{methoddesc}

\begin{methoddesc}[TestCase]{fail}{\optional{msg}}
  無条件にテスト失敗を通知します。エラー内容は\var{msg}に指定された値
  か、または\constant{None}となります。
\end{methoddesc}

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

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

\begin{methoddesc}[TestCase]{countTestCases}{}
  テストオブジェクトに含まれるテストの数を返します。\class{TestCase}イン
  スタンスは常に\code{1}を返します。
\end{methoddesc}

\begin{methoddesc}[TestCase]{defaultTestResult}{}
  このテストケースクラスで使われるテスト結果クラスのインスタンス
  を(もし\method{run()}メソッドに他の結果インスタンスが提供されないなら
  ば)返します。

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

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

\begin{methoddesc}[TestCase]{shortDescription}{}
  テストの説明を一行分、または説明がない場合には\constant{None}を返します。
  デフォルトでは、テストメソッドのdocstringの先頭の一行、または
  \constant{None}を返します。
\end{methoddesc}


\subsection{TestSuite オブジェクト
            \label{testsuite-objects}}

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

\begin{methoddesc}[TestSuite]{addTest}{test}
  \class{TestCase}又は\class{TestSuite}のインスタンスをスイートに追加し
  ます。
\end{methoddesc}

\begin{methoddesc}[TestSuite]{addTests}{tests}
  イテラブル\var{tests}に含まれる全ての\class{TestCase}又は
  \class{TestSuite}のインスタンスをスイートに追加します。

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

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

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

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

\begin{methoddesc}[TestSuite]{countTestCases}{}
  このテストオブジェクトによって表現されるテストの数を返します。
  これには個別のテストと下位のスイートも含まれます。
\end{methoddesc}

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

\subsection{TestResultオブジェクト
            \label{testresult-objects}}

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

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

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

\begin{memberdesc}[TestResult]{errors}
  \class{TestCase}と例外のトレースバック情報をフォーマットした文字列の
  2要素タプルからなるリスト。それぞれのタプルは予想外の例外を送出したテストに
  対応します。
  \versionchanged[\function{sys.exc_info()}の結果ではなく、
  フォーマットしたトレースバックを保存]{2.2}
\end{memberdesc}

\begin{memberdesc}[TestResult]{failures}
  \class{TestCase}と例外のトレースバック情報をフォーマットした文字列の
  2要素タプルからなるリスト。それぞれのタプルは\method{TestCase.fail*()}や
  \method{TestCase.assert*()}メソッドを使って見つけ出した失敗に対応します。
  \versionchanged[\function{sys.exc_info()}の結果ではなく、フォーマット
  したトレースバックを保存]{2.2}
\end{memberdesc}

\begin{memberdesc}[TestResult]{testsRun}
  これまでに実行したテストの総数。
\end{memberdesc}

\begin{methoddesc}[TestResult]{wasSuccessful}{}
  これまでに実行したテストが全て成功していれば\constant{True}を、
  それ以外なら\constant{False}を返す。
\end{methoddesc}

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

  たとえばこの機能は、ユーザのキーボード割り込みを受け取っ
  て\class{TextTestRunner}クラスがテストフレームワークを停止させるのに
  使えます。\class{TestRunner}の実装を提供する対話的なツールでも同じよ
  うに使用することができます。
\end{methoddesc}
 
 
以下のメソッドは内部データ管理用のメソッドですが、対話的にテスト結果をレ
ポートするテストツールを開発する場合などにはサブクラスで拡張することがで
きます。

\begin{methoddesc}[TestResult]{startTest}{test}
  \var{test}を実行する直前に呼び出されます。

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

\begin{methoddesc}[TestResult]{stopTest}{test}
  \var{test}の実行直後に、テスト結果に関わらず呼び出されます。

  デフォルトの実装では何もしません。
\end{methoddesc}

\begin{methoddesc}[TestResult]{addError}{test, err}
  テスト\var{test}実行中に、想定外の例外が発生した場合に呼び出されます。
  \var{err}は\function{sys.exc_info()}が返すタプル\code{(\var{type},
  \var{value}, \var{traceback})}です。

  デフォルトの実装ではインスタンスの\code{errors}属性
  に\code{(\var{test}, \var{err})}を追加します。
\end{methoddesc}

\begin{methoddesc}[TestResult]{addFailure}{test, err}
  テストが失敗した場合に呼び出されます。\var{err}は
  \function{sys.exc_info()}が返すタプル\code{(\var{type}, \var{value},
  \var{traceback})}です。

  デフォルトの実装ではインスタンスの\code{failures}属性
  に\code{(\var{test}, \var{err})}を追加します。
\end{methoddesc}

\begin{methoddesc}[TestResult]{addSuccess}{test}
  テストケース\var{test}が成功した場合に呼び出されます。

  デフォルトの実装では何もしません。
\end{methoddesc}


\subsection{TestLoader オブジェクト
            \label{testloader-objects}}

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

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

\begin{methoddesc}[TestLoader]{loadTestsFromTestCase}{testCaseClass}
  \class{TestCase}の派生クラス\class{testCaseClass}に含まれる全テスト
  ケースのスイートを返します。
\end{methoddesc}

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

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

\begin{methoddesc}[TestLoader]{loadTestsFromName}{name\optional{, module}}
  文字列で指定される全テストケースを含むスイートを返します。

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

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

  また、\var{module}を指定した場合、\var{module}内の\var{name}を取得しま
  す。
\end{methoddesc}

\begin{methoddesc}[TestLoader]{loadTestsFromNames}{names\optional{, module}}
  \method{loadTestsFromName()}と同じですが、名前を一つだけ指定するのでは
  なく、複数の名前のシーケンスを指定する事ができます。戻り値は
  \var{names}中の名前で指定されるテスト全てを含むテストスイートです。
\end{methoddesc}

\begin{methoddesc}[TestLoader]{getTestCaseNames}{testCaseClass}
  \var{testCaseClass}中の全てのメソッド名を含むソート済みシーケンスを返
  します。\var{testCaseClass}は\class{TestCase}のサブクラスでなければな
  りません。
\end{methoddesc}

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

\begin{memberdesc}[TestLoader]{testMethodPrefix}
  テストメソッドの名前と判断されるメソッド名の接頭語を示す文字列。デフォ
  ルト値は\code{'test'}です。

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

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

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

  この値は全ての\method{loadTestsFrom*()}メソッドに影響を与えます。
\end{memberdesc}


% \subsection{追加エラー情報の取得
%             \label{unittest-error-info}}

% 統合開発環境(IDE)等のアプリケーションでは、より詳細なエラー情報を使用す
% る場合があります。この場合、独自の\class{TestResult}クラスの実装を使用
% し、\class{TestCase}クラスの\method{defaultTestResult()}メソッドを拡張し
% て必要な情報を取得する事ができます。

% 以下に\class{TestResult}を拡張して例外オブジェクトとトレースバックオブジ
% ェクトをそのまま格納する例を示します。(トレースバックオブジェクトを保存
% すると、通常は解放されるメモリが解放されなくなり、テストの実行に影響を与
% える場合がありますので注意してください。)

% %begin{verbatim}
% import unittest

% class MyTestCase(unittest.TestCase):
%     def defaultTestResult(self):
%         return MyTestResult()

% class MyTestResult(unittest.TestResult):
%     def __init__(self):
%         self.errors_tb = []
%         self.failures_tb = []

%     def addError(self, test, err):
%         self.errors_tb.append((test, err))
%         unittest.TestResult.addError(self, test, err)

%     def addFailure(self, test, err):
%         self.failures_tb.append((test, err))
%         unittest.TestResult.addFailure(self, test, err)
% %end{verbatim}

% \class{TestCase}ではなく\class{MyTestCase}をベースクラスとしたテストで
% は、追加情報がテスト結果オブジェクトに格納されます。

