rubydoctest – Example Usage の邦訳

2011 年 12 月 5 日 by 山平

前回(レーベンシュタイン距離で文字列の類似度を測る)引用させていただいたサイトさま(Moderation is a fatal thing. Nothing succeeds like excess.)でとても気になる記述がありました。

で、、、この手のコードを書いたときに、ちょっとしたテストも書いときたいなあ、と思うんですよね。Python だと、doctest っていうコメントにテストを埋め込める便利なのがあるんですが、ruby にもないものかと思って探したらありました。rubydoctestってやつが。

Ruby DocTest

気になりすぎて調査したかったので前回はあえて触れず、今回紹介されているrubydoctestの使用例のページ(Example Usage)を訳してみました。
ほとんどコードでかつコード中の文は訳していないのですが、雰囲気はつかめると思います。

Example Usage
使用例

Create a .doctest document, for example, “simple.doctest”, and begin documenting your application, like this:

例えば”simple.doctest”のような、拡張子”doctest”のドキュメントを生成します。
そして以下のようにあなたのアプリケーションについて記述します。

Here is an example doctest file (say called simple.doctest):

This is an example test that succeeds
>> 1 + 2
=> 3

And here’s a test that will fail
>> 1 + 2
=> 4

Test a some multiline statements

>> class Person
attr_accessor :name
end
>> Person
=> Person

>> p = Person.new
>> p.name = “Tom”
>> p.name
=> “Tom”

doctest: you split a file into separate named tests by adding a doctest: directive
>> 1 + 2
=> 4

Or, put your pastes in as comments within your ruby code, say, factorial.rb, like this:

もしくは以下のようにあなたのアプリケーション”factorial.rb”のコードにコメントとして記述することもできます。

doctest: factorial should give correct results for 0 to 2
>> factorial(0)
=> 1
>> factorial(1)
=> 1
#
comments describing the parameters can be included
this is how it works with 2:
>> factorial(2)
=> 2
def factorial(n)
if n == 0
1
else
n * factorial(n-1)
end
end
#
doctest: should work for 3, too
>> factorial(3)
=> 6

When the above code is run, i.e. with the command “rubydoctest factorial.rb”, it shows the following results:

上記のコードを”rubydoctest factorial.rb”というコマンドで実行させると、以下のような結果が得られます。

=== Testing 'factorial.rb'...
OK  | factorial should give correct results for 0 to 3
OK  | should work for 3, too
6 comparisons | 2 doctests | 0 failures | 0 errors

You can do multiline statements like this, as long as the indentation level is greater than the >> start line (note that ‘end’ is at an unnatural indentation level):

インデントの階層をテスト開始行の”>>”よりも深くしておけば、複数行にまたがってテストコードを記述することもできます。
(メモ:インデントの階層が条件に合わないとき、複数行コードの終了とみなします)

# >> all_true = true
# >> 3.times do |t|
#      all_true &&= (a[t] == b[t])
#      end
# >> all_true
# => true

Here’s a more advanced usage example, in a Rails model, book.rb:

以下にRailsのモデルクラス”book.rb”を使ってさらに進んだ使用例を示します。

require File.join(File.dirname(__FILE__), "..", "rubydoctest_helper")

class Book < ActiveRecord::Base

=== Description
Extension for sections and chapters collections
e.g. book.sections.approved_only, book.chapters.dirty!
=== Tests
doctest: Sample data should provide an example of a book with both approved
and unapproved sections.
>> v_a_books = Book.varied(:approved)
>> v_a_books.size > 0
=> true
doctest: Sample data should provide an example of a book with both dirty
and non-dirty sections.
>> v_d_books = Book.varied(:dirty)
>> v_d_books.size > 0
=> true
module SectionExtension
=== Tests
doctest: Book#sections.approved_only should return approved sections,
including first-level sections, i.e “chapters”.
>> s = v_a_books.first.sections.approved_only
>> s.size > 1
=> true
>> s.any?{ |t| t.approved? }
=> true
>> s.any?{ |t| !t.approved? }
=> false
def approved_only
self.select{ |s| s.approved? }
end

=== Tests
doctest: Book#sections.unapproved_only should return unapproved sections,
including first-level sections, i.e “chapters”.
>> s = v_a_books.first.sections.unapproved_only
>> s.size > 1
=> true
>> s.any?{ |t| t.approved? }
=> false
>> s.any?{ |t| !t.approved? }
=> true
def unapproved_only
self.select{ |s| !s.approved? }
end

=== Tests
doctest: Book#sections.dirty! should set the dirty flag for sections
specific to the particular book it was called on.
>> book = v_d_books.first
>> (yes = book.sections.count(:conditions => [“dirty = ?”, true])) > 0
=> true
>> (no = book.sections.count(:conditions => [“dirty = ?”, false])) > 0
=> true
>> v_d_books.first.sections.dirty!
>> book.sections.count(:conditions => [“dirty = ?”, true])
=> yes + no
>> book.sections.count(:conditions => [“dirty = ?”, false])
=> 0
def dirty!
self.update_all [“dirty = ?”, true]
end
end

has_many :sections,  :extend => SectionExtension

=== Description
Find books with a diverse set of sections with a certain property.
=== Examples
@see SectionExtension module
def self.varied(field, min = 2)
find_by_sql \
“SELECT * FROM books WHERE id IN
(SELECT book_id FROM sections
GROUP BY book_id
HAVING COUNT >= #{min})”
end
end

See the Rails Usage page for more information about the rubydoctest_helper script mentioned above.

上記のコード中で参照しているスクリプト”rubydoctest_helper”についての詳しい説明はページ”Rails Usage”を参照してください。

In each case, you run your tests using the rubydoctest command-line tool, e.g.:

どちらの場合においても、コマンドラインツール”rubydoctest”を使ってテストを実行します。

$ rubydoctest doc/sample.doctest
$ rubydoctest factorial.rb
$ rubydoctest app/models/book.rb

Note also that you can use =begin and =end to suround the tests, ex: factorial.rb

埋め込みドキュメント(rubyコード中、=beginと=endに囲まれている部分)内に記述できる事を、先ほどのアプリケーション”factorial.rb”を例に付記しておきます。
訳注:埋め込みドキュメントについては下記を参照してください。
埋め込みドキュメント < 字句構造 < Ruby 1.9.2 リファレンスマニュアル

def factorial(n)
if n == 0
1
else
n * factorial(n-1)
end
end
=begin
doctest: fact
&gt;&gt; factorial(0)
=&gt; 1
=end

And that tests can be interspersed with comments, a la

そしてこのテストコードには、以下のようにコメントをちりばめることができます。

doctest: factial 0 is 1
&gt;&gt; factorial(0)
=&gt; 1
#
These numbers grow much larger with a higher n:
#
&gt;&gt; factorial(10)
=&gt; 3628800

And since your test code and comments will appear in the rdocs, you’ve made instant documentation for parameters to your functions.

そして、あなたのテストコードはRDoc上にも出力されるため、メソッド(など)についての使用例のドキュメントを作成したことにもなるのです。

And all it cost was a copy and past from an irb session.

そのドキュメントはirbセッションからコピーペーストする労力しかかかっていないのです。

Last edited by canadaduane, September 15, 2010

最終更新: 2010/09/15 canadaduane

タグ: ,

TrackBack