explains downloading and use of doctest for ruby

Introduction

Note this is still very alpha, and the syntax is subject to change (but it works as shown here).

This is a gemified (and slightly improved) version of the ruby doctest first created here http://clintonforbes.blogspot.com/2007/08/doctest-for-ruby-and-rails.html.

Use

Here are some examples copied from http://clintonforbes.blogspot.com/2007/08/doctest-for-ruby-and-rails.html

=begin
#doctest Check that 1 + 1 = 2
>> 1 + 1
=> 2
>> 2 + 3
=> 5
=end

And it outputs something like this

Looking for doctests in 3 files
Processing 'script/../app/helpers/application_helper.rb'
Testing 'Check strings'...OK
Testing 'Check that 1 + 1 = 2'...OK
Testing 'Add some arrays'...OK
Testing 'Check that 2 + 2 = 4 and 4 + 4 = 7'...FAILED
Code:
4 + 4
Expected: 7
But got: 8
Processing 'script/../app/models/member.rb'
Testing 'Test creating a Member'...OK
Total tests: 5, Succeeded: 4

You can also add explanations between lines

=begin
#doctest Check that 1 + 1 = 2
>> 1 + 1
=> 2
It should also work for other than 1's
>> 2 + 3
=> 5
=end

You'll note that this is just copied and pasted working output from an irb session. You can add these anywhere in your file.

Advantages

The advantages of using this is that it creates tests that are somewhat behavior oriented, and the tests serve as a kind of documentation for the code. And it is dirt easy and fast to create the tests.

Installation

Download http://ruby-roger-useful-functions.googlecode.com/svn/trunk/packages/doctest/pkg/doctest-0.0.1.gem run [sudo] gem install doctest-0.0.1.gem

Or download and run this file : http://ruby-roger-useful-functions.googlecode.com/svn/trunk/doctest.rb

Run it as

 doctest # same as doctest . -- runs all in current directory and subdirectories.
 doctest filename
 doctest directory_name # also scans subdirectories and runs tests in each .rb file in all directories

Advanced usage (subject to change)

You'll note as well that each file that contains tests will have that file included.

You can also add some testing setup code anywhere in the file:

=begin
#setup_doctest once_per_file
require 'activerecord'
class TestConnection
  def quote_column_name name
   name
  end
  def quote name
    name
  end
end
=end

This can be anywhere in the file, and is run once, then the tests in the file are run in order.

If one line 'should' always fail it's irb output is too complex to match--for example nested hashes then you can add #doctest_failable somewhere in the line and it will count it as a success line no matter what. ex:

=> #<ActiveMerchant::Billing::Integrations::AuthorizeNetSim::Notification:0x1bbed50 {"x_MD5_Hash"=>"DE4A0F077B30886E4F5585EA3961222B", "x_fax"=>"", "x_response_reason_code"=>"1"}, @options={}> #doctest_fail_ok

Feel free to submit patches and/or ideas. -R

Links:

http://docs.python.org/lib/module-doctest.html gives some good ideas on how to use doctests.