.. highlight:: rest

sphinx.ext.doctest – ドキュメント内の簡易テスト

このSphinx拡張を使用すると、自然な形で、ドキュメント内で簡単なテストを行えるようになります。特別なマークアップのされたコードブロックを収集して、doctestとしてテストを行います。

ひとつのドキュメント内で、テストコードをグループという形で分けることができます。それぞれのグループは以下のものを含みます。

• ゼロ個以上のセットアップコードブロック。テストに必要なモジュールをimportします。
• ひとつ以上のテストブロック。

doctestビルダーを使用してドキュメントをビルドすると、それぞれのドキュメントごとに同一グループの要素が集められて次々に実行されます。最初はセットアップコードブロックが実行され、その後はファイルの中で登場する順番にテストブロックが実行されます。

テストブロックには以下の２種類あります:

• Pythonコード(含プロンプト)と出力が交互に書かれている、インタラクティブモードに似たdoctestスタイルのブロック

• 通常のPythonコードと、出力を1つから構成される、コード-出力スタイルのブロック

doctest拡張は4つのディレクティブを提供します。 グループ引数は以下のように解釈されます:

• もしも何も指定されなかった場合には、defaultというグループ名が指定されたとみなします
• もしも*が指定されると、そのブロックはdefaultを含む、すべてのグループに対して割り当てられたものとみなします。そうでなければ、これ以外の場合はグループ名は、カンマ区切りのリストでなければなりません。

.. testsetup:: [グループ]

セットアップのためのコードブロックです。このコードは他のビルダーを使用したときには出力されませんが、それが所属するグループのdoctestが実行される前に実行されます。

.. doctest:: [グループ]

doctestスタイルのコードブロックです。標準の docteset のフラグを使用すると、ユーザが指定した理想の出力と、実際に出力したものをどのように比較するのか、というのを制御することができます。以下のオプションが使用できます:

• ELLIPSIS

  省略記号(...)を期待される出力の中に書くことができます。どのような結果が来てもマッチします。

• IGNORE_EXCEPTION_DETAIL

  例外の詳細を省略して比較します。トレースバックの詳細までは比較しないようになります。

• DONT_ACCEPT_TRUE_FOR_1

  デフォルトでは、実際の出力が”True”で、理想の結果が”1”となっていた場合、デフォルトではこれもテスト成功とみなします。Python 2.2以前の名残です。

このディレクティブは以下の二つのオプションをサポートしています:

• hideはフラグオプションです。他のビルダーの使用時に、doctestブロックを隠します。デフォルトでは、ハイライトされたdoctestブロックとして表示されます。
• optionsは文字列オプションです。それぞれのテストのサンプルに対して、カンマ区切りのdoctestフラグのリストを設定するのに使用します。doctestコメントの中でサンプルごとにフラグを明示することもできますが、他のビルダーをしようすると、そのフラグまでレンダリングされてしまいます。

標準ライブラリのdoctestでは、予想出力の中に空行を入れたい場合には<BLANKLINE>というキーワードを指定しなければなりませんでした。<BLANKLINE>はHTMLやLaTeXなど、人が読める出力を行うビルドの際には削除されます。

doctestの中で書くのと同様に、インラインでdoctestのオプションを指定することもできます。

>>> datetime.date.now()   
datetime.date(2008, 1, 1)

これらのオプションは、テストの実行時には識別されますが、HTMLなどの出力の際には削除されます。

.. testcode:: [グループ]

コード-出力タイプのテストのコードブロックです。

このディレクティブは以下のオプションをサポートしています:

• hideはフラグオプションで、doctest以外の他のビルダーのビルド時はコードブロックが表示されなくなります。デフォルトでは、ハイライトされたコードブロックとして表示されます。

.. testoutput:: [グループ]

最後に定義された testcode ブロックに対応する出力を定義します。

このディレクティブは以下の２つのオプションをサポートしています:

• hideはフラグオプションで、doctest以外の他のビルダーのビルド時はコードブロックが表示されなくなります。デフォルトでは、ハイライトされたコードブロックとして表示されます。
• optionsは文字列オプションで、通常のdoctestブロックと同じように、カンマ区切りのdoctestのフラグを設定するのに使用されます。

サンプル:

.. testoutput::
   :hide:
   :options: -ELLIPSIS, +NORMALIZE_WHITESPACE

   出力テキスト.

以下のコードはこれらのディレクティブの使用方法のサンプルです。 doctest を使用したテストと、 testcode および testoutput の二つで構成されたテストは完全に等価です.

オウムモジュール
================

.. testsetup:: *

   import parrot

parrotモジュールはオウムに関するモジュールです

Doctest例:

.. doctest::

   >>> parrot.voom(3000)
   This parrot wouldn't voom if you put 3000 volts through it!

テスト出力例:

.. testcode::

   parrot.voom(3000)

この出力は以下のようになります:

.. testoutput::

   This parrot wouldn't voom if you put 3000 volts through it!

doctest拡張の動作をカスタマイズする設定がいくつかあります:

doctest_path

doctestビルダーが使用されるときに、 sys.path に対して追加されるディレクトリのリストです。必ず絶対パスで記述してください。

doctest_global_setup

Pythonコードを記述します。このコードはテストされるすべてのファイルのtestsetupディレクティブに書き込んだのと同じように扱われます。例えば、doctest時にいつでも必要となるモジュールをimportするといった用途に使用できます。

バージョン 0.6 で追加.

doctest_test_doctest_blocks

この値に空でない文字列(デフォルトは'default')が設定されると、標準のreSTのdoctestブロックもテストされるようになります。それらのテストには、ここで与えられたグループ名が設定されます。

reSTのdoctestブロックは、reSTの中のパラグラフとして単純にdoctestが置かれます:

何かドキュメント.

>>> print 1
1

追加の何かドキュメント.

reSTの場合は、ブロックを表現するのに特別な::は不要です。docutilsは>>>から始まる行を識別します。そのため、doctestのために追加でインデントを設定する必要はありません。

この設定値がデフォルトのままであったとすると、上記のコード片は、下記のように書いた場合と同じようにdoctestビルダーから解釈されます:

何かドキュメント.

.. doctest::

   >>> print 1
   1

追加の何かドキュメント.

この機能があるおかげで autodoc 拡張を使用して取り込んだdocstring中のdoctestを簡単に実行することができます。特別なディレクティブでマークアップする必要はありません。

reSTのdoctestブロックでは空白行はパラグラフの境界として使用されるため、そのままでは結果として空行を記述することはできません。削除された<BLANKLINE>と# doctest:は、 doctest ブロック内でのみ動作します。