 |
 |
 |
Python ライブラリリファレンス |  |
 |
 |
|
|
|
Python ライブラリリファレンス | |
|
|
doctest では、その挙動の様々な側面をたくさんのオプションフラグで制御 しています。各フラグのシンボル名はモジュールの定数として提供されて おり、論理和で組み合わせて様々な関数に渡せるようになっています。 シンボル名は doctest のディレクティブ (directive, 下記参照) としても 使えます。
最初に説明するオプション群は、 テストのセマンティクスを決めます。 すなわち、実際にテストを実行したときの出力と例題中の予想出力とが 一致しているかどうかを doctest がどうやって判断するかを制御します:
1 だけが入っており、
実際の出力ブロックに 1 または True だけが入って
いた場合、これらの出力は一致しているとみなされます。
0 と False の場合も同様です。
DONT_ACCEPT_TRUE_FOR_1 を指定すると、こうした値の読み替え
を行いません。デフォルトの挙動で読み替えを行うのは、最近の Python で
多くの関数の戻り値型が整数型からブール型に変更されたことに対応する
ためです; 読み替えを行う場合、"通常の整数" の出力を予想出力とする
ような doctest も動作します。このオプションはそのうち無くなるでしょうが、
ここ数年はそのままでしょう。
<BLANKLINE> だけの
入った行がある場合、その行は実際の出力における空行に一致する
ようになります。完全な空行を入れてしまうと予想出力がそこで
終わっているとみなされてしまうため、空行を予想出力に入れたい
場合にはこの方法を使わねばなりません。
DONT_ACCEPT_BLANKLINE を指定すると、
<BLANKLINE> の読み替えを行わなくなります。
...)
を実際の出力中の任意の部分文字列に一致させられます。部分文字列は
行境界にわたるものや空文字列を含みます。従って、このフラグを使うのは
単純な内容を対象にする場合にとどめましょう。複雑な使い方をすると、
正規表現に .* を使ったときのように
"あらら、省略部分をマッチがえてる (match too much) ！"
と驚くことになりかねません。
ELLIPSIS を使っても同様のことができ、 IGNORE_EXCEPTION_DETAIL は リリース 2.4 以前の Python を使う人がほとんどいなくなった時期を見計らって撤廃するかもしれないので 気をつけてください。それまでは、IGNORE_EXCEPTION_DETAIL は 2.4 以前の Python で例外の詳細については気にせずテストをパスさせるように doctest を書くための唯一の明確な方法です。例えば、
>>> (1, 2)[3] = 'moo' #doctest: +IGNORE_EXCEPTION_DETAIL Traceback (most recent call last): File "<stdin>", line 1, in ? TypeError: object doesn't support item assignment
にすると、 Python 2.4 と Python 2.3 の両方でテストをパスさせられます。 というのは、例外の詳細情報は 2.4 で変更され、 "doesn't" から "does not" と書くようになったからです。
このフラグを指定すると、例題は一切実行されません。こうした機能 は doctest の実行例がドキュメントとテストを兼ねていて、ドキュメントの ためには含めておかなければならないけれどチェックされなくても良い、と いうような文脈で役に立ちます。例えば、実行例の出力がランダムであると か、テスト機構には手が届かない資源に依存している場合などです。
SKIP フラグは一時的に例題を"コメントアウト"するのにも使えます。
二つ目のオプション群は、テストの失敗を報告する方法を制御します:
difflib.Differ で分析します。これは、行単位の差分
と同じように行内の差分にマーカをつけられるようにする唯一の手段です。
例えば、予想出力のある行に数字の 1 が入っていて、実際の出力
には l が入っている場合、不一致のおきているカラム位置を
示すキャレットの入った行が一行挿入されます。
「doctest ディレクティブ」を使うと、個々の例題に対してオプションフラグ の設定を変更できます。 doctest ディレクティブは特殊な Python コメント文 として表現され、例題のソースコードの後に続けます:
| directive | ::= | "#" "doctest:" directive_options |
| directive_options | ::= | directive_option ("," directive_option)* |
| directive_option | ::= | on_or_off directive_option_name |
| on_or_off | ::= | "+" | "-" |
| directive_option_name | ::= | "DONT_ACCEPT_BLANKLINE" | "NORMALIZE_WHITESPACE" | ... |
+ や- とディレクティブオプション名の間に空白を入れては
なりません。ディレクティブオプション名は上で説明したオプションフラグ名
のいずれかです。
ある例題の doctest ディレクティブは、その例題だけの doctest の
振る舞いを変えます。ある特定の挙動を有効にしたければ + を、
無効にしたければ - を使います。
例えば、以下のテストはパスします:
>>> print range(20) #doctest: +NORMALIZE_WHITESPACE [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19]
ディレクティブがない場合、実際の出力には一桁の数字の間に二つスペースが 入っていないこと、実際の出力は 1 行になることから、テストはパスしない はずです。別のディレクティブを使って、このテストをパスさせることも できます:
>>> print range(20) # doctest:+ELLIPSIS [0, 1, ..., 18, 19]
複数のディレクティブは、一つの物理行の中にコンマで区切って指定できます:
>>> print range(20) # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE [0, 1, ..., 18, 19]
一つの例題中で複数のディレクティブコメントを使った場合、それらは 組み合わされます:
>>> print range(20) # doctest: +ELLIPSIS ... # doctest: +NORMALIZE_WHITESPACE [0, 1, ..., 18, 19]
前の例題で示したように、"..." の後ろにディレクティブだけの 入った行を例題のうしろに追加して書けます。この書きかたは、 例題が長すぎるためにディレクティブを同じ行に入れると収まりが悪い 場合に便利です:
>>> print range(5) + range(10,20) + range(30,40) + range(50,60) ... # doctest: +ELLIPSIS [0, ..., 4, 10, ..., 19, 30, ..., 39, 50, ..., 59]
デフォルトでは全てのオプションが無効になっており、ディレクティブは
特定の例題だけに影響を及ぼすので、通常意味があるのは有効にするための
オプション(+ のついたディレクティブ) だけです。とはいえ、
doctest を実行する関数はオプションフラグを指定してデフォルトとは
異なった挙動を実現できるので、そのような場合には - を使った
無効化オプションも意味を持ちます。
バージョン 2.4 で 変更 された仕様:
定数 DONT_ACCEPT_BLANKLINE,
NORMALIZE_WHITESPACE, ELLIPSIS,
IGNORE_EXCEPTION_DETAIL,
REPORT_UDIFF, REPORT_CDIFF,
REPORT_NDIFF, REPORT_ONLY_FIRST_FAILURE,
COMPARISON_FLAGS, REPORTING_FLAGS
を追加しました。予想出力中の <BLANKLINE> がデフォルトで
実際の出力中の空行にマッチするようになりました。また、
doctest ディレクティブが追加されました
バージョン 2.5 で 変更 された仕様:
定数 SKIP が追加されました
新たなオプションフラグ名を登録する方法もありますが、doctest の内部をサブクラスで拡張しない限り、意味はないでしょう:
| name) |
MY_FLAG = register_optionflag('MY_FLAG')
バージョン 2.4 で 新たに追加 された仕様です。
|
|
|
Python ライブラリリファレンス | |
|
|