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:
- It is not a plug-in; it’s a gem.
- All currently Shoulda macros are ported to RSpec.
- 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.
- 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 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:
Then install the gem:
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:
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:
fixtures :all
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!
My code doesn’t “should” anything, they “must”. I hope you support “must_require_unique_attributes” and such. Because should makes no sense.
Justin: “Should”, I believe, derives in part from the writing of requirements. Honestly, I would have expected it to be “shall”. See here: http://www.itmweb.com/essay543.htm
“Must” is not part of that vocabulary.
Justin, your “must” statement contains unnecessary duplication. “must” and “require”. Saying something “should require” is the same as saying “must have”.
@luke Bad example, which I pulled from up above.
@evan When your “describing behaviour”, in speech, do you say “it should blink the light”, or do you say “it blinks the light”?
If we’re writing requirement specifications in Rspec, then I’m going to make a statement about how a system will work. Not should work.
That document doesn’t make any sense either…
“The guidance and control subsystem shall provide control in six degrees of freedom.”
…over…
“The guidance and control subsystem provide control in six degrees of freedom.” [and here's the Ruby code to show you how it does that].
I guess its all in how you want to define the systems your building. ::shrug::
should require acts_as_pedantic? =P
Great tool here Carlos, been curious about Shoulda but use RSpec right now.
@Brandon Har har har… acts_as_troll would have been more appropriate! ;Q
@Justin
(a) It blinks lights.
(b) It must blink lights.
(c) It should blink lights.
IMO only (c) is always true in requirements, and explicitly and non-ambiguously implies that we *want* something to be the case.
(a) could be true even if we don’t want it blinking the blinking lights. It could be a description of a fault, for example.
(b) could be stating a physical fact (it’s wired to the blinkenator, it’s got power, therefore must the lights blinken). Furthermore it might be false during dev because the code hasn’t been written etc.
(c) is true even when the test fails.
@Dave Well, didn’t that really clear it up. Love the library thanks…
Well I should from the hip. Must get coat.
We say “should” instead of “does” because we’re writing tests. Tests should pass, but they don’t always – that’s why we’re writing them.
Is not the same what rspec-on-rails-matchers do?
http://github.com/joshknowles/rspec-on-rails-matchers/tree/master
I actually completely agree that “should” is the proper term here. These is a specification / test framework. Like Mark Wilden said above, you’re making a statement that something “should” have, require, do something else. Specifically in the case of writing your spec before you write the code (which is why it’s called rSPEC), you’re making a statement of what it should do when you get it implemented.
Agree @ should explanation, but i am still a fan of the it xxx simply because it makes everything more readable/sipmle.
I imply that only things that are intended (should work) are specified with tests, for everything else there is “it currently xxxx”.
i has the same function then rspec-on-rails-matchers but a lot more code, why?
Josh Knowles and others have done an excellent work in rspec-on-rails-matchers.
The idea is that Remarkable is turning this into something more serious. With a better structure, better organization and tests.
Wait for news and you will understand what I’m talking about. This is just the first release.
Just wanted to beat the “should verbiage” horse a bit more…
We often use certain words for a reason – language is important and words carry a certain amount of baggage with them.
In context/specification style tests we use the word “should” to get the reader into the correct state of mind. We want to to communicate that the specification is not rigid, but is subject to change over time. Using words like “must” make the specifications feel rigid and final, which is not the case.
Anyhow, just my two pennies…
I’m having trouble making this work with validates_inclusion_of.
In my model I have:
validates_inclusion_of :precision, :in => VALID_PRECISIONSAnd in my spec, I say:
should_allow_values_for :precision, Location::VALID_PRECISIONSUnfortunately, this spec does not pass:
should allow precision to be set to ["country", "state", "city", "zip", "street", "address"] expected true, got false /Users/nathan/dev/mcommons/mcommons/vendor/gems/carlosbrando-remarkable-1.1.1/lib/remarkable/active_record/macros/validations/allow_values_for.rb:73 :in `should_allow_values_for’ 71 good_values.each do |v| 72 it “should allow #{attribute} to be set to #{v.inspect}” do 73 assert_good_value(klass, attribute, v).should be_true 74 end 75 endAm I using the tool correctly?
Thanks,
Nathan
After adding the gem to my environment, I get the following warning when loading script/console:
Loading development environment (Rails 2.2.1)
irb: warn: can’t alias context from irb_context.
I tried removing it and adding require “remarkable” to spec_helper.rb (am using rspec) but that didn’t work.
Has anyone resolved this?
So very glad I found this truly great site :-)
I think I may have found a bug in the Shoulda macros. The should_set_the_flash_to macro creates an it block which does an ‘assert_contains’. However assert_contains just returns a boolean [for use with simple_matcher?]. This means that should_set_the_flash_to will always pass when a val is provided.
@Matt, can you register a new ticket?
http://carlosbrando.lighthouseapp.com/projects/19775-remarkable
I don’t much care for “should” OR “shall”. I think it should read “damned well better”.
E.g.,
damned_well_batter_have_many :tags, :through => :taggings
Lol. “better”