Simplifying tests!

Remarkable is a framework for Rspec matchers.

Matchers are a powerful tool for DRYing and simplifying tests and if you are using Rspec on Rails, you are already using them for a long long time (redirect_to and be_success for example).

But the creation of matchers should not be in hand of few, but spreaded to millions. :)

If not enough, Remarkable also makes easy your matchers become macros and have even cleaner tests.

Current Features

Here are some of the things that make Remarkable special (and we are working on even more):

  • All ActiveRecord validation macros with support to all options;

  • More Rails macros (all currently Shoulda macros are ported);

  • It has two different test syntaxes: one for those who like the RSpec style and another for those who like macro (Shoulda) style;

  • It’s a gem;

  • Tests;

  • More tests;

  • 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 do you ensure that the last commit didn’t break anything?

Synopsis

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_validate_uniqueness_of :title
  should_validate_presence_of :body, :message => /wtf/
  should_validate_presence_of :title
  should_validate_numericality_of :user_id
end

Notice how you declare your macros with the same name as you do in Rails! This is great because most of the time you won’t have to check the documentation (just pay attention that has_many becomes have_many and validates become validate according to english grammar).

The syntax above is similar with Shoulda, but those who likes more the Rspec way can simply do:

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 validate_uniqueness_of(:title) }
  it { should validate_presence_of(:body, :message => /wtf/) }
  it { should validate_presence_of(:title) }
  it { should validate_numericality_of(:user_id) }
end

Macros

Here are all the available macros:

ActiveRecord macros: wiki.github.com/carlosbrando/remarkable/active-record-macros

Controller macros: wiki.github.com/carlosbrando/remarkable/controller-macros

Pending Macros

Even more than just bringing macros to Rspec, we are bringing Rspec to macros. So let’s suppose you are doing some code refactoring and you know some tests will fail while you clean the house, what do you do then?

In Rspec you could do:

xit { should validate_numericality_of(:user_id) }

Well, now you can do just the same with macros:

xvalidate_numericality_of(:user_id)

And it’s even better, because it will show a nice message:

"Example disabled: should validate numericality of user_id"

Yeah!

Install

Run the following if you haven’t already:

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

Install the gem:

sudo gem install carlosbrando-remarkable

Installing via Rails

Specify the gem dependency in your config/environment.rb file:

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

Then run in terminal:

$ rake gems:install
$ rake gems:unpack

As a Plugin

You can also install Remarkable as a plugin:

$ script/plugin install git://github.com/carlosbrando/remarkable.git

Or using git submodules:

$ git submodule add git://github.com/carlosbrando/remarkable.git vendor/plugins/remarkable

Note: When installed as a plugin, you need to also install the rspec and rspec-rails in your project.

Requirements

  • rspec >= 1.1.12

  • rspec-rails >= 1.1.12

More information

Google group: groups.google.com/group/remarkable-core Bug tracking: carlosbrando.lighthouseapp.com/projects/19775-remarkable/overview

License

(The MIT License)

Copyright © 2008 Carlos Brando

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the ‘Software’), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED ‘AS IS’, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.