23.2.11 提言

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

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

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

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

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

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

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