[This is the 5th part of a series of posts about writing a Ruby gem. The introductory post about this tutorial contains links to each part of the tutorial. Previous post - Setting up Test::Unit.]

In the previous part of this tutorial we set up Test::Unit for writing our gem’s unit tests. In this part, we will replace Test::Unit by another testing framework, Rspec.

Test::Unit is a great testing framework, but I personally prefer using Rspec for its syntactic sugar. At the end of this part of the tutorial, we will have set up both Rspec and Test::Unit, so you can choose whichever framework you feel comfortable with.

First of all, let’s change the Rakefile to add the following two lines to the Rakefile:

require 'rspec/core/rake_task'
RSpec::Core::RakeTask.new('spec')

This adds a rake task called ‘spec’ and you will be able to run the specs in the spec/ directory. If you wish to run your specs as the default rake task instead of Test::Unit tests, replace task :default => 'test' to task :default => :spec.

The next thing we need to do is to tell rubygems that you want Rspec as a development dependency.

  s.add_development_dependency 'rspec', '~> 2.5'

If anyone installs the gem using gem install sudoku --development, Rubygems will install rspec when installing sudoku.

Now we need to add a spec directory and create spec_helper.rb before we start writing the specs. The spec_helper will look like this:

require 'rspec'
require 'sudoku'

RSpec.configure do |config|
  config.color_enabled = true
  config.formatter     = 'documentation'
end

The Rspec.configure block will contain the options to configure Rspec, and we have used the color_enabled and formatter configurations.

Next, we’ll add a spec similar to the test we wrote using Test::Unit. Add the following code to a file sudoku_spec.rb:

require 'spec_helper'

describe Sudoku do
  it 'should return correct version string' do
    Sudoku.version_string.should == "Sudoku version #{Sudoku::VERSION}"
  end
end

Now run rake spec (or even simply rake, if you've changed the default task to rspec) and you’ll see the output looks something like this:

$ rake
/home/username/.rvm/rubies/ruby-1.9.2-p180/bin/ruby -S rspec ./spec/sudoku_spec.rb

Sudoku
  should return correct version string

Finished in 0.00051 seconds
1 example, 0 failures

The passing spec will be displayed in green because we have set the color_enabled option to true. And, because we have set the formatter option to 'documentation', the documentation string 'should return correct version string' is also displayed in the output.

Let's now build and install the gem, and check the directory where the gem is installed. You'll see that the spec folder is missing from the installed gem. To include the specs in the package, we need to change the following line in the gemspec:

  s.test_files  = Dir.glob("test/**/*.rb")

to:

  s.test_files  = Dir.glob("{spec,test}/**/*.rb")

We have added the spec/ directory in addition to the test/ directory as the source of test files. Now if you build and install the gem again, the spec files will be present in the installed gem.

You now have the option of using Rspec or Test::Unit for writing the tests for the sudoku solver. You also have the option of not writing any tests, but try not to take that path if you are making a gem that lots of people might find useful. Nobody wants to use an untested library.

In the next part of this tutorial, we will add an executable to the gem, which would give our gem's users a command line sudoku solver tool.

[Subscribe to this blog to find out when the next part of this tutorial is published, or keep an eye on the first post in this series where I'll post the links to all published posts.]