For a long time I was evangelizing Shoulda at Surgeworks and used it in my personal projects. The fact is, I didn’t have much success in convincing my co-workers to adopt Shoulda. On the other hand, they managed to convince me to learn and use RSpec.

RSpec is a very interesting Testing Framework. But I start to like it more after I started to use the Cucumber.

The great thing about Shoulda is that it’s simplifies tests for trivial things.

I got to like RSpec more and more, so I decided to adopt it as my official testing framework from now on. But I can no longer live without the resources that Shoulda offers me. So I decided to scratch my itch.

Remarkable

Initially, the main objective of Remarkable is to port all Shoulda macros to RSpec, but of course the plan is more ambitious than that. I have other ideas that will hopefully be especially useful for Rspec users.

At this point you may ask: “But aren’t there already plug-ins that do the same thing, such as skinny and rspec-on-rails-matchers. Why build something else?”

First, this isn’t simply “another” plugin with RSpec matchers. It also does a lot of things differently that I feel are better than other approaches.

Here are some of the things that make Remarkable special:

1. It is not a plug-in; it’s a gem.
2. All currently Shoulda macros are ported to RSpec.
3. It has two different test syntaxes: one for those who like the RSpec style and another for those who are migrating their projects from Shoulda to RSpec.
4. Tests.
5. More tests.
6. And a few more tests.

Unlike other similar projects, Remarkable is the only one that tests itself, and this is a big difference, believe me! How can we trust in a project that has no tests? How can you develop an open-source project with no tests? How do you ensure that the last commit didn’t break anything?

Install

Install Remarkable is very easy. It is stored in GitHub, so if you have never installed a gem via GitHub run the following:

gem sources -a http://gems.github.com

Then install the gem:

sudo gem install carlosbrando-remarkable

In RAILS_ROOT/config/environment.rb:

config.gem "carlosbrando-remarkable",  :lib => "remarkable", :source => "http://gems.github.com"

Using

All Remarkable macros can be accessed in two different ways. For those who prefer the Shoulda style, let’s look at some model tests:

describe Post do  fixtures :all

  should_belong_to :user  should_belong_to :owner  should_belong_to :user, :owner

  should_have_many :tags, :through => :taggings  should_have_many :through_tags, :through => :taggings  should_have_many :tags, :through_tags, :through => :taggings

  should_require_unique_attributes :title  should_require_attributes :body, :message => /wtf/  should_require_attributes :title  should_only_allow_numeric_values_for :user_idend

Like Shoulda, right? That’s the idea! This syntax is for those who wish to migrate their Shoulda tests to RSpec. You basically just have to change context to describe and wrap your should statements with it {}.

But if you don’t like this syntax, you can also create the same tests as follows:

describe Post do  fixtures :all

  it { should belong_to(:user) }  it { should belong_to(:owner) }  it { should belong_to(:user, :owner) }

  it { should have_many(:tags, :through => :taggings) }  it { should have_many(:through_tags, :through => :taggings) }  it { should have_many(:tags, :through_tags, :through => :taggings) }

  it { should require_unique_attributes(:title) }  it { should require_attributes(:body, :message => /wtf/) }  it { should require_attributes(:title) }  it { should only_allow_numeric_values_for(:user_id) }end

Now with an RSpec style!

Macros

Here are all the available macros:

For Shoulda style, click here. For RSpec style, click here.

Finalizing

This project has already reached the first goal, which was to port all Shoulda macros to RSpec. This has been done with great care and attention to detail, and I have tried to write lots of tests. But there is no substitute for using it in real life and finding areas that could use improvement.

Please use Remarkable and help me to make it even better!