Welcome to your whirlwind tour of RSpec, a Behavior Driven Development framework for Ruby and Ruby on Rails. I debated with myself on how best to start this series of tutorials, and eventually decided to take a breadth-first approach, i.e. dump it all in your lap and break it down from there. So this first post we’ll cover just what RSpec is and what it can do for you and your code.

Since RSpec is simply an implementation of Behavior Driven Development, you’d be best served to read my previous post An Introduction to Behavior Driven Development first, if you don’t know what that is.

Getting back to RSpec. RSpec, in addition to being an implementation of BDD, is more specifically, a DSL, or Domain Specific Language. Which, itself, is a fancy way of saying that it is a programming language designed for a specific purpose or task: namely, the task of specifying the behavior of an application. The programming language part may be a bit obtuse in meaning; it’s not another C or Java or VisualBasic. However, it does introduce a new ‘language’ in Ruby that is specific to defining application behavior.

Now that you know what it is, let’s get to the fun stuff and see what it can do.

I’ve already stated that RSpec’s purpose is to specify the behavior of an application. More to the point, RSpec provides a way for us to set down in stone exactly what our application should do and how it should behave. Notice the emphasis on ’should’. ‘Should’ is a crucial focal point of BDD and it’s how RSpec makes its assertions.

For example, if I wanted to specify that a post should have a title, I would write something a little like this:

describe Post do
before(:each) do
@post = Post.new
end

it “should have a title” do
@post.title.should_not be_blank
end
end

There’s actually quite alot going on there, so let’s break it down.

We start with creating a describe block, which encapsulates our specification. The part right after describe is the name of the class we are describing, in this case: Post.

Then, we have a before(:each) block, which acts as a setup method or initializer for the specification. The :each specifies that we want the following instructions performed for every example. Inside this block, we store a new instance of the Post class in the instance variable, @post.

Next, we add an it block, which tells RSpec we’re starting an example. The example, itself, is everything between the do and end. The string after it, “should have a title”, is purely informational. You could even leave it out. In which case, RSpec would automatically generate a description of the example based on what is inside. In this case, that would end up being, “title should not be blank”.

Inside the it block, we have the real meat of our example. We access the title attribute and specify that it should_not be_blank.

should_not is a method RSpec extends the superclass Object with; should_not and it’s positive version should will both return true or false, resulting in either a pass or fail, respectively, for our example.

be_blank is bit of a different beast. It is not a method itself, but rather signals to RSpec to call the blank? method on our title attribute. blank?, by the way, is an innate method (exists out of the box) that returns true if the variable in question is either an empty string or nil.

Every example you code in RSpec will have at least one statement with should or should_not. The be_whatever part is just one of many different possible arguments (matchers) for these two methods. Let’s look at the full list:

Eql and Equal

RSpec has two levels of equality checks. First, you can use eql or the standard equality operator ==. For example:

"this string".should eql "this string" or "this string".should == "this string"

Second, you can check for equality at the object level with equal or the “three equals” operator ===. For example:

25.should equal 25 or 25.should === 25

However, note:

"this string".should equal "this string" and "this string".should === "this string"

Both of these will actually evaluate to false. To understand why you could run script/console and try the following:

$ ruby script/console
Loading development environment.
>> "this string".object_id
=> 106148390
>> "this string".object_id
=> 106145680

Even though it’s the same string, each instance has a unique object id. The example using 25 works because of the following:

$ ruby script/console
Loading development environment.
>> 25.object_id
=> 51
>> 25.object_id
=> 51

The technical explanation is that 25 is instantiated as a Fixnum, so every instance of 25 afterwards is actually a reference to the first instance of 25. However, strings and most other objects in Ruby receive unique ids for every instance.

Have

Quite often, you’ll want to ensure that a collection has at least a certain number of items: ensuring there are no validation errors on a particular field in a form, for example. RSpec provides an easy way to specify the behavior you want with have. For example:

day.should have(24).hours

It should be noted that in order for this to work, day would have to own a collection, hours, with 24 items. This is really just shorthand for the following:

day.hours.should have(24).items

RSpec provides some “sugar” with have so that both of the following will work without any further implementation:

[1, 2, 3].should have(3).items and "fun".should have(3).characters

Additionally, some things in RSpec exist simply for the purpose of readability. One example of this is have_exactly, which is just an alias for have. So, the code above could be be rewritten as:

day.should have_exactly(24).hours

Either way works; it’s simply a matter of preference.

Often, you won’t be entirely sure about how many items you should have, but you will know a minimum or maximum. Once again, RSpec comes through with have_at_least and have_at_most. For example:

blog.should have_at_least(1).post or question.should have_at_most(4).answer_choices

Include

Closely related to have, we have include. Whereas, have concerns itself with the number of items in a collection, include concerns itself with the collection’s values. For example:

{ :str1 => 'first string', :str2 => 'second string' }.should include('second string')

The above would pass because the value ’second string’ exists in the the collection. You can even specify multiple values as such:

[1, 2, 3, 4, 5].should include(1, 3, 5)

However, when you specify multiple values for the include all of those values must be present in order for the example to pass. The following would fail, since 6 is not present in the array:

[1, 2, 3, 4, 5].should include(2, 4, 6)

Match

RSpec provides the ability to match based on regular expressions through the match matcher. Like eql and equal before, there’s you can also the use the operator equivalent, =~. For example:

"sample string".should match(/sample/) or "sample string".should =~ /sample/

Predicates

The previous matchers have all been methods specific to RSpec. The true power of RSpec comes from letting you apply its behavior-specific language to your own methods. It does this via various prefixes. We encountered one of these earlier with be_blank. As we saw, the actual method being called is blank?, but by prefixing it with be_ we can not only instruct RSpec to call this method, but also maintain nicer readability. Here are some other common uses of the be_ prefix:

be_true
be_false
be_nil
be_blank
be_empty
be_an_instance_of(Class)
be_a_kind_of(Class)
be_close(expected, delta)

Each of the above rely on built in Ruby methods, but you can also apply this to any other predicate. What is a predicate? Predicates are methods that end with ?’s and return true or false. It could be one built into Ruby or Ruby on Rails, or it could be one of your own creation. Consider the following:

# method defined in User class
def admin?
self.role == ‘admin’
end

…

# example from User spec
@user.should be_admin # will pass if @user.role == ‘admin’

Also, notice the two matchers above, be_a_kind_of and be_an_instance_of. These respectively call the methods kind_of? and instance_of?. The prefixes be_a_ and be_an_ are aliases of be_, provided for better readability.

In addition to the be_ prefix, RSpec also provides the have_ prefix. Note, however, that this is not the same as the have matcher mentioned above. It’s also not a prefix in the truest since, but the best way to explain is with an example:

{:fun => 1, :times => 2 }.should have_key(:fun)

In this example have_key signals RSpec to call the predicate has_key? built into Ruby. This will work with any predicate starting with has_ as well. For example:

# defined inside a Chicken class
def has_feathers?
self.feathers > 0
end

…

# example inside the Chicken spec
@plucked_chicken.should_not have_feathers # passes if @plucked_chicken.feathers == 0

Is that it?

There’s a few other matchers that I have intentionally not mentioned yet: only because they are a little more abstract in nature. We’ll eventually get to all those as we continue through this series.

The next article up will detail the process of spec’ing a model. I haven’t completely decided on an example application yet, but I have a couple ideas.

Windows, on the other hand, lacks much in the Rails development arena, but has been graced with a really great text editor: e-Text Editor, a TextMate clone for Windows. That’s just enough motivation to keep me hacking away at Windows (at least until I get a Mac… then you’re all on your own).

So on to the actual point of this article. Via Cygwin, I have been able to setup up an acceptable Rails development environment for myself in Windows, but since Cygwin can be a little tricky to setup properly, I decided to get some community service hours in by providing a tutorial.

Without further ado (cue drum-roll and general fan-fare)…

Preparation

I had various things such as Ruby and MySQL already set up on my computer before installing Cygwin. The Windows version of Ruby will have to go the way of the dinosaurs once we bring in Cygwin, but it does play well with the Windows version of MySQL. However, I’m not sure if that would still be the case if setup after Cygwin (it probably would, but why take any chances?), so our first step will be to setup MySQL.

Install MySQL for Windows

There’s a few million tutorials on how to do this, so I’m going to cover the bare minimum. If you run into any problems, go make friends with Google.

First, go download the current MySQL binary. At the time of this writing, it’s 5.0.45. You can download either the Essentials or the regular setup executable. I normally go with the regular setup since space is not an issue for me, but I’ll leave the choice to you. Run the installer, and follow the on screen prompts. The install process is pretty self-explanatory, but I’ll cover a bit of minutiae.

You can pretty much use the default settings throughout the install. I normally like to keep all my server apps (apache, mysql, etc) in a common directory for ease. If you’d like to do the same, you can change the install directory when you have the option. After the install finishes, you’ll be asked if you’d like to go ahead and configure MySQL. Yes you do, so proceed with that. Choose the development options throughout (the explanatory paragraphs will mention that this setting or that setting is better for either production or development). When you’re asked if you’d like MySQL to run as a Windows service, tell it yes. When you’re prompted to setup accounts, make sure you disable the anonymous account. You can leave the root password blank, as long as you also turn off remote access. The default Rails database config has blank root passwords, so it’ll save you from having to customize the config every time you start a new app, and it’s just easier to not have to type in a password every time you want to do something with MySQL. The rest of this tutorial will assume the password is blank, though I’ll provide little pointers here and there in case you did set a password.

Install Cygwin

With that out of the way, we can move on to Cygwin. You can grab the setup at the Cygwin website. Look for the “Install or Update Now!” link around the center of the home page. The setup file is a small download, but go ahead and get a pot of coffee ready for brewing, because the rest will be downloaded during install.

Run the setup program, and click next. You’re going to want to stick with the default here (Install from Internet), so click next again. The root directory should default to ‘C:\cygwin’. If not, it’ll make your life a little easier if you change it to that. Leave the two recommended settings checked, and click next again. Now, you’re going to be prompted for a Local Package Directory. I forget what this defaults to, but I like to set it to ‘C:\cygwin\install’ just to keep everything together. Click next again, and you’ll be prompted for your connection settings. For most purposes you should be fine with the default of “Direct Connection”. If that doesn’t work, and you’re unsure of what your settings should be, you can try “Use IE5 Settings”. If you know you’re connecting through a proxy, what are you bothering me for? Just enter your information there.

Time for a new paragraph for this rather tedious install process, but we’re getting close to the end. After clicking next, you’ll be prompted to choose a download site. I always feel a little bit like I’m in Vegas at this point in the install, because it’s basically just a gamble as to which one to pick. FTP is more efficient for file transfer than HTTP, so that weeds it down a bit. Other than that, you can either pick one at random or try to discern one that might be close to you. There’s alot of college servers there, so if you recognize a college that close to your area, go ahead and pick that one.

Okay, I devoted way more attention than was necessary to picking a mirror. Once you’ve rolled the dice, click next. The installer is now going to download a list of available packages and then it’ll present you with a very cryptic screen. Fortunately, we’re going to stick with the defaults for most of these, but we will have to make one small change. Expand the “Devel” category, and then scroll down in the list until you come to the “ruby” package. Click where it says “Skip” to set it to install. And with that, you can click next again and go have a cup of coffee.

When the install completes. You’ll be asked if you’d like to create a Desktop icon or Program Group, give one or both a check, just to simplify your life, and you’re done.

Installing RubyGems

The process from here ought to be familiar for awhile if you’ve ever done any Rails development before. However, we do have a few gotchas to take a look at.

First, download the rubygems archive, which is at version 0.9.4 at the time of this writing. Save it to your desktop to make things easy on yourself. Now, we need to open up a Cygwin command prompt, using one of our handy, dandy shortcuts (either on your desktop or in your start menu… you did remember to do that right?). In the command prompt, you’ll already be in your home directory (i.e. C:\Documents and Settings\[your name]\) which is short-handed as ‘~’ (Tip: you can run ‘cd ~’ at any point to return to your home directory). We need to get to the RubyGems archive we downloaded, so if you followed instructions that’ll mean running ‘cd Desktop’. Now, run the following command (remembering to change the version to whatever is appropriate):

$ tar -pxzf rubygems-0.9.4.tgz

After that finishes it’s work change into the directory that was created:

$ cd rubygems-0.9.4

And run the setup.rb program:

$ ruby setup.rb

Note:

At some point either by now or in the next few steps, you might come across a cryptic error resembling:

ruby: no such file to load -- ubygems (LoadError)

If or when this occurs, you can simply run the following command, and you’ll be good to proceed:

$ unset RUBYOPT

Now back to our regularly scheduled tutorial…

Install Rails

Normally, this is a easy as:

$ gem install rails --include-dependencies

But I have recently noticed, both in Linux and Cygwin that this will return a NoSuchGem error. (Confirmation?). Go ahead and try it the tried and true way first, but if that doesn’t work, continue on.

Go ahead now and download the rails gem, which is at 1.2.3 at the time of this writing. Save it to your desktop, like before. Back in your Cygwin command prompt change back to your desktop (’cd ..’), and run the following command to take care of the dependencies:

$ gem install rake activerecord actionpack actionmailer actionwebservice

You’ll be prompted at points to confirm the download of additional dependencies. Of course, you’ll want to allow those. Grab another cup of coffee, and when it finishes up, run:

$ gem install rails-1.2.3.gem

With that, we now have Rails up and running.

Getting Autotest

Autotest is a very nice feature that will run both your tests and specs automatically based on file changes. It’s actually just a part of a larger suite of testing tools, though, available through the ZenTest gem. Let’s go ahead and get that:

$ gem install zentest

Creating a Rails App

Now that we’ve got all the boring stuff out of the way, let’s get to the interesting part, setting up a Rails app and bootstrapping it for Behavior Driven Development via the RSpec framework. First, change to whatever directory you want to store your Rails apps in (I like to simply use my home directory) and then run:

$ rails myapp

(Where ‘myapp’ is whatever you want to name your app). Then change into the new app’s directory, via:

$ cd myapp

This is where all the fun will happen. But I’ve gotten a little ahead of myself. Before we continue, we need to take care of a few little things. First, we’re going to need both a test and development database for our new app. We can take care of that easily with:

$ mysqladmin -uroot create myapp_development

and

$ mysqladmin -uroot create myapp_test

Now we need to make a slight change to the database.yml config file for our app, due to some Cygwin/Windows compatibility issues. Open the database.yml file (found in the config folder of your app’s directory) in your favorite text editor or wordpad (notepad would not be a good choice due to the Unix format line-endings). Once there, replace every occurrence of ‘localhost’ with ‘127.0.0.1′ (fixes a socket problem with MySQL).

Install the RSpec and Spec:Rails Plugins

There, that’s taken care of. Let’s bootstrap our app with RSpec. (Oddly enough though, we can’t seem to do this in Cygwin. I ran into a very weird issue trying. The plugins appear as if they are installing normally, but afterwards, nothing shows up in the vendors/plugins directory of the app. Odder still, if you try to install the plugins again, it will actually error out, saying that the directories already exist. The only way I could get the plugins installed was to backdoor it through a standard Windows command prompt, but that requires keeping a separate version of Ruby on the Windows side. (Confirmation?) Unfortunately, I have not been able to find another way, so for the meantime, I will go ahead and still put the process here. However, be advised that it may not work.)

$ ruby script/plugin install svn://rubyforge.org/var/svn/rspec/tags/CURRENT/rspec

and when that finishes:

$ ruby script/plugin install svn://rubyforge.org/var/svn/rspec/tags/CURRENT/rspec_on_rails

Note:

If you’re feeling adventurous, you can download the trunk versions of these plugins instead. As of this writing, this would give you access to the new Story Runner functionality of RSpec, that has not yet been released. Instead of the above commands run:

$ ruby script/plugin install svn://rubyforge.org/var/svn/rspec/trunk/rspec

and then:

$ ruby script/plugin install svn://rubyforge.org/var/svn/rspec/trunk/rspec_on_rails

Now back to our tutorial, already in progress…

Whichever route you choose above, the next step is to generate the standard RSpec folders and files:

$ ruby script/generate rspec

Generating Some Stuff to Play With

And that’s all there is to it. But for the sake of instruction let’s generate a sample controller and model. This will let us run autotest and see how the whole process went. I’ll be pretending that this app is going to be a blog, but you can go ahead and create something more meaningful here if you want.

The model:

$ ruby script/generate rspec_model post

The controller:

$ ruby script/generate rspec_controller blog

After these two complete, open the 001_create_posts.rb migration file that was created in the apps db/migrate directory. It will initially look like this:

class CreatePosts < ActiveRecord::Migration
def self.up
create_table :posts do |t|
end
end

def self.down
drop_table :posts
end
end

Modify it to look like this:

class CreatePosts < ActiveRecord::Migration
def self.up
create_table :posts do |t|
t.column :title, :string
t.column :content, :string
t.column :created_at, :datetime
end
end

def self.down
drop_table :posts
end
end

Save and close. Then go back to your Cygwin command prompt and run:

$ rake db:migrate

followed by:

$ rake db:test:clone

With that done, we can run autotest and get a glimpse of the rest of our lives in development

$ autotest
loading autotest/rails_rspec
/usr/bin/ruby -S script/spec -O spec/spec.opts  spec/helpers/blog_helper_spec.rb
 spec/controllers/blog_controller_spec.rb spec/models/post_spec.rb
...

Finished in 0.389 seconds

3 examples, 0 failures

Those three examples are default examples generated for us by RSpec.

Finally…

Take a breather now. You’ve done alot of work, and accomplished quite alot too. I hope this helps those of you who are stuck programming in a Windows environment.

As always, if something is unclear, feel free to ask for further explanation. I do my best to try and write to the lowest common denominator, but I don’t always succeed. Thanks for reading. Now get out there and do some coding.

The Background

Let me get everyone caught up to speed. RSpec is of course a Behavior Driven Development framework for Ruby and Ruby on Rails. The Behavior Driven Development process itself involves writing a specification (test), running that specification (which will initially fail), writing the functionality to satisfy that specification, and finally running the specification again which should then pass. This process continues until you’ve implemented all the functionality in the application you are developing.

Now, if you run all the specifications manually, this can get really bothersome very quickly. This is particularly aggravated in a Windows environment, since all the common Rails tasks (rakes, generations, migrations, etc.) seem to take twice as long as they do in a Linux or OSX environment. Even under Linux or OSX, though, the frequency of running specs tends to slow down the production cycle incredibly when run manually.

Thankfully, there’s ZenTest and more specifically the autotest functionality of ZenTest. Autotest watches for file changes and then automatically runs any specs or tests that have changed. Combine this with the color-coding provided by Redgreen and a notification system (Growl, KDENotify, Libnotify) and you have a very effective Behavior Driven Development environment.

The Specs

There is strong indication that all of the issues I have noticed are version dependent (i.e. broken in newer versions), so it makes sense, then, to provide the specs of the various gems and plugins I’m using for these tests:

• Windows XP SP2
• Ruby 1.8.6
• Rails 1.2.3
• ZenTest 3.6.1
• RSpec 1.0.8
• Spec:Rails 1.0.8
• Redgreen 1.2.2
• Ruby-Snarl 0.0.8
• Snarl 1.6

The Issues

But then there’s Windows. On the surface, it looks as though the same should be possible here. We can develop Rails apps in Windows. RSpec, Autotest, and Redgreen are operating system agnostic. There’s even a fairly mature notification system for Windows in Snarl. So what’s the problem? Well, when you put all of these together, it explodes.

I did a good bit of trial and error debugging tonight trying to pin down the exact problem, and while I was ultimately unsuccessful, I was able to notice certain trends which, to a more apt Rubyist, may spark an idea for a solution. So, for posterity, I want to post my findings in the hope that someone can figure out what is wrong.

Autotest and Redgreen

A great deal of work has been done to integrate RSpec and Autotest, and in Linux and OSX, the two play very nicely together with little to no configuration. In Windows, however, Autotest initially hangs when trying to read the specs. The only way I could find to get Autotest to actually run the specs through, was to remove everything from the spec.opts file in the spec directory of the app in question.

Unfortunately one of the lines in the spec.opts file is the “–colour” option which sets up the color-coding of passes and failures. I did quite a bit of research online, and found many articles which tell you that you must install the redgreen gem in order to get color-coding on your tests. However, this seems to be outdated information since both Autotest and RSpec seem to come with this functionality out of the box, now (assuming you have installed the win32console gem to make it work in Windows). Indeed, even without the redgreen gem installed, if I simply ‘rake spec’ the color-coding is there.

So, after realizing that I could not rely on this out of the box functionality in Windows, I tried the alternate route of installing the redgreen gem and then requiring it in a ‘.autotest’ file in my RAILSROOT (require ‘redgreen/autotest’ along with require ‘Win32/Console/ANSI’). However, this resulted in autotest erroring-out on load complaining of an ‘Invalid Option: -O’.

I then realized that Autotest has a redgreen plugin of its own, which can be reference as flip-flop of the previous require for the redgreen gem (i.e. require ‘autotest/redgreen’). So I uninstalled the redgreen gem, changed the require in .autotest, and ran autotest again. This time it loads fine, but without color-coding still. Finally, just to be thorough, I reinstalled the redgreen gem in the hopes that it still somehow provided some functionality for the autotest plugin of the same name. However, this two proved fruitless. Autotest still ran successfully, but still without color-coding.

Autotest and Snarl

At this point, I gave up on having nice color-coded test results. Snarl, I thought, can be setup to provide all the visual indication necessary, so I began to work on the Snarl side of things. I already had Snarl installed, so I went ahead and installed the ruby-snarl gem which sets up the connectivity. Then, I opened my .autotest file once more and added the require for snarl (require ‘autotest/snarl’). Time to test it out, so I went to my command line, ran autotest once more, only to see Snarl pop up with a notification window saying all tests had passed, while autotest simultaneously informed me that I had two failures. This is pretty much where I stopped because I have no idea where to even begin to troubleshoot Snarl.

The Summary

In the end, the only thing I could get to work was plain-jane autotest, which is better than nothing but not by much. Through all the digging I have done online, the only thing I can determine definitively is that at one point it was possible to integrate all of this in Windows. However, this was before both Autotest and RSpec added in their own implementations of Redgreen. The Snarl issue is even stranger, and I’m not sure if it is a related issue or something entirely separate.

The ironic part is that it appears that it has been so for quite some time, and no one is either using Windows to notice it, or cares enough to fix it if they have noticed it. Which gives even greater weight in my mind to simply abandon Windows for Rails development, preferring Linux or OSX. Obviously, OSX would be the optimum choice, but for those of us still on PCs, Linux is as close as you can get.