5.2.11 提言

冒頭でも触れたように、doctest は、

docstring 内の例題をチェックする、
回帰テストを行う、
実行可能なドキュメント/読めるテストの実現、

という三つの主な用途を持つようになりました。これらの用途にはそれぞれ違った要求があるので、区別して考えるのが重要です。特に、 docstring を曖昧なテストケースに埋もれさせてしまうとドキュメントとしては最悪です。

docstring の例は注意深く作成してください。 doctest の作成にはコツがあり、きちんと学ぶ必要があります -- 最初はすんなりできないでしょう。例題は、ドキュメントに紛れ無しの価値を与えます。よい例がたくさんの言葉に値することは多々あります。注意深くやれば、例はユーザにとってはあまり意味のないものになるかもしれませんが、歳を経るにつれて、あるいは "状況が変わった" 際に何度も何度も正しく動作させるためにかかることになる時間を節約するという形で、きっと見返りを得るでしょう。私は今でも、自分の doctest で処理した例が "たいした事のない" 変更を行った際にうまく動作しなくなることに驚いています。

説明テキストの作成をけちらなければ、doctest は回帰テストの優れたツールにもなり得ます。説明文と例題を交互に記述していけば、実際に何をどうしてテストしているのかもっと簡単に把握できるようになるでしょう。もちろん、コードベースのテストに詳しくコメントを入れるのも手ですが、そんなことをするプログラマはほとんどいません。多くの人々が、doctest のアプローチをとった方がきれいにテストを書けると気づいています。おそらく、これは単にコード中にコメントを書くのが少し面倒だからという理由でしょう。私はもう少しうがった見方もしています: doctest ベースのテストを書くときの自然な態度は、自分のソフトウェアのよい点を説明しようとして、例題を使って説明しようとするときの態度そのものだからだ、という理由です。それゆえに、テストファイルは自然と単純な機能の解説から始め、論理的により複雑で境界条件的なケースに進むような形になります。結果的に、一見ランダムに見えるような個別の機能をテストしている個別の関数の集まりではなく、首尾一貫した説明ができるようになるのです。 doctest によるテストの作成は全く別の取り組み方であり、テストと説明の区別をなくして、全く違う結果を生み出すのです。

回帰テストは特定のオブジェクトやファイルにまとめておくのがよいでしょう。回帰テストの組み方にはいくつか選択肢があります:

テストケースを対話モードの例題にして入れたテキストファイルを書き、 testifle() や DocFileSuite() を使ってそのファイルをテストします。この方法をお勧めします。最初から doctest を使うようにしている新たなプロジェクトでは、この方法が一番簡単です。
_regrtest_topic という名前の関数を定義します。この関数には、あるトピックに対応するテストケースの入った docstring が一つだけ入っています。この関数はモジュールと同じファイルの中にも置けますし、別のテストファイルに分けてもかまいません。
回帰テストのトピックをテストケースの入った docstring に対応付けた辞書__test__ 辞書を定義します。

ご意見やご指摘をお寄せになりたい方は、 このドキュメントについて... をご覧ください。