2007-08-07 14:44:59 +00:00
= Shoulda - Making tests easy on the fingers and eyes
2007-04-05 18:26:25 +00:00
2007-07-24 20:16:01 +00:00
Shoulda makes it easy to write elegant, understandable, and maintainable tests. Shoulda consists of test macros, assertions, and helpers added on to the Test::Unit framework. It's fully compatible with your existing tests, and requires no retooling to use.
2007-04-05 18:26:25 +00:00
2009-03-03 22:00:44 +00:00
Helpers:: #context and #should give you RSpec like test blocks.
2007-07-24 20:16:01 +00:00
In addition, you get nested contexts and a much more readable syntax.
2008-08-31 20:53:06 +00:00
Macros:: Generate hundreds of lines of Controller and ActiveRecord tests with these powerful macros.
2007-07-24 20:16:01 +00:00
They get you started quickly, and can help you ensure that your application is conforming to best practices.
2008-08-31 20:53:06 +00:00
Assertions:: Many common rails testing idioms have been distilled into a set of useful assertions.
2009-01-26 23:34:04 +00:00
Matchers:: Rspec-compatible matchers providing the same tests as Shoulda macros.
2007-04-05 18:26:25 +00:00
2007-07-24 20:16:01 +00:00
= Usage
2009-01-05 16:50:57 +00:00
=== Context Helpers (Shoulda::Context)
2007-07-24 20:16:01 +00:00
Stop killing your fingers with all of those underscores... Name your tests with plain sentences!
2009-01-06 18:18:39 +00:00
class UserTest < Test::Unit::TestCase
2007-07-24 20:16:01 +00:00
context "A User instance" do
setup do
@user = User.find(:first)
end
2008-08-31 20:53:06 +00:00
2008-04-05 14:36:17 +00:00
should "return its full name" do
2007-07-24 20:16:01 +00:00
assert_equal 'John Doe', @user.full_name
end
2008-08-31 20:53:06 +00:00
2007-07-24 20:16:01 +00:00
context "with a profile" do
setup do
@user.profile = Profile.find(:first)
end
2008-08-31 20:53:06 +00:00
2008-04-05 14:36:17 +00:00
should "return true when sent #has_profile?" do
2007-07-24 20:16:01 +00:00
assert @user.has_profile?
end
end
end
end
Produces the following test methods:
"test: A User instance should return its full name."
"test: A User instance with a profile should return true when sent #has_profile?."
So readable!
2009-01-05 16:50:57 +00:00
=== ActiveRecord Tests (Shoulda::ActiveRecord::Macros)
2007-07-24 20:16:01 +00:00
Quick macro tests for your ActiveRecord associations and validations:
class PostTest < Test::Unit::TestCase
2008-09-02 20:49:13 +00:00
fixtures :all
2007-07-24 20:16:01 +00:00
2010-06-17 13:39:56 +00:00
should belong_to(:user)
should have_many(:tags).through(:taggings)
2007-07-24 20:16:01 +00:00
2010-06-17 13:39:56 +00:00
should validate_uniqueness_of(:title)
should validate_presence_of(:body).with_message(/wtf/)
should validate_presence_of(:title)
should validate_numericality_of(:user_id)
2007-07-24 20:16:01 +00:00
end
class UserTest < Test::Unit::TestCase
2010-06-17 13:39:56 +00:00
should have_many(:posts)
should_not allow_value("blah").for(:email)
should_not allow_value("b lah").for(:email)
should allow_value("a@b.com").for(:email)
should allow_value("asdf@asdf.com").for(:email)
should ensure_inclusion_of(:email).in_range(1..100)
should ensure_inclusion_of(:age).in_range(1..100)
should_not allow_mass_assignment_of(:password)
2007-07-24 20:16:01 +00:00
end
Makes TDD so much easier.
2009-01-05 16:50:57 +00:00
=== Controller Tests (Shoulda::Controller::Macros)
2007-07-24 20:16:01 +00:00
Macros to test the most common controller patterns...
2009-05-27 17:58:39 +00:00
class PostsControllerTest < ActionController::TestCase
context "on GET to :show for first record" do
setup do
get :show, :id => 1
end
2007-07-24 20:16:01 +00:00
2010-06-17 13:39:56 +00:00
should assign_to(:user)
should respond_with(:success)
should render_template(:show)
should_not set_the_flash
2007-07-24 20:16:01 +00:00
2009-05-27 17:58:39 +00:00
should "do something else really cool" do
assert_equal 1, assigns(:user).id
end
2007-07-24 20:16:01 +00:00
end
end
2009-05-27 17:58:39 +00:00
2009-01-05 16:50:57 +00:00
=== Helpful Assertions (Shoulda::Assertions)
2007-07-24 20:16:01 +00:00
More to come here, but have fun with what's there.
assert_same_elements([:a, :b, :c], [:c, :a, :b])
assert_contains(['a', '1'], /\d/)
assert_contains(['a', '1'], 'a')
2009-03-03 22:00:44 +00:00
= Rails Installation (Test::Unit)
2009-01-13 20:20:54 +00:00
2010-06-16 15:07:49 +00:00
Specify the gem dependency in your config/environment.rb file:
2009-01-13 20:20:54 +00:00
Rails::Initializer.run do |config|
2010-06-16 15:07:49 +00:00
config.gem "shoulda", :lib => "shoulda", :source => "http://gems.github.com"
2009-01-13 20:20:54 +00:00
end
Then:
$ rake gems:install
$ rake gems:unpack
2009-03-03 22:00:44 +00:00
= Rails Installation (RSpec)
2009-03-04 14:57:09 +00:00
If you're using Shoulda with RSpec, we recommend that you add config.gem lines
for RSpec and Shoulda in your config/environment/test.rb file, but do not ask
Rails to load the RSpec and Shoulda libraries:
2009-03-03 22:00:44 +00:00
config.gem 'rspec', :lib => false
config.gem 'rspec-rails', :lib => false
2010-06-16 15:07:49 +00:00
config.gem 'shoulda',
2009-03-03 22:00:44 +00:00
:lib => false,
:source => 'http://gems.github.com'
Then require shoulda from your spec/spec_helper.rb file, before Spec::Runner is
configured:
# requires for RSpec
require 'shoulda'
Spec::Runner.configure do |config|
# ...
You should not need to require anything besides the top-level shoulda library.
2007-07-24 20:16:01 +00:00
= Credits
2010-06-16 15:07:49 +00:00
Shoulda is maintained and funded by {thougthbot}[http://thoughtbot.com/community]
2007-07-24 20:16:01 +00:00
= License
2007-04-05 18:26:25 +00:00
2008-08-04 20:17:32 +00:00
Shoulda is Copyright © 2006-2008 Tammer Saleh, Thoughtbot. It is free software, and may be redistributed under the terms specified in the MIT-LICENSE file.