I'm pleased to introduce a new Test Double (or mock) framework named RR, which is short for Double Ruby.

Why a Double framework and not a Mock framework?

A mock is a type of test double. Since RR supports mocks, stubs, and proxies, it makes sense to refer to RR as a double framework. The proxy is a new usage pattern that I will introduce later in this article, and in more detail in future articles.

Unfortunately, the terminology over doubles has been contradictory depending on the framework. RR's terminology tries to be as faithful as possible to Gerald Meszaros' definition of test doubles. You can read more about test doubles in http://xunitpatterns.com/Test2e.html and Martin Fowler's article, http://martinfowler.com/articles/mocksArentStubs.html. Regretfully, this does mean that RR will have slightly different terminology than other double frameworks.

How does RR compare to other Mock frameworks?

Most double frameworks focus mainly on mocks (hence the categorization "mock framework"). RR's focus is on enabling more double test patterns in a terse and readable syntax.

RR also does not have dedicated mock objects. It primarily uses the technique called 'double injection'. Names that other frameworks use are 'stub injection', 'mock object injection', 'partial mocking', or 'stubbing'. The term I'll use for this is a double injection, since one or many doubles are being injected into an object's method.

I'll use trivial Rails examples to highlight the syntactical differences between RR, Mocha, Rspec's mocks, and Flexmock. They may or may not be appropriate situations for mocks. The right situations for mocks is an entirely different discussion.

If there is better way to do any of the examples, please post a comment and I will gladly replace it.

Mocks

Here are the ways to mock the User.find method. The expectation is the User class object will receive a call to #find with the argument '99' once and will return the object represented by the variable user.

RR

mock(User).find('99') { user }

Mocha

User.expects(:find).with('99').returns(user)

spec/mocks

User.should_receive(:find).with('99').and_return(user)

Flexmock

flexstub(User).should_receive(:find).with('99').and_return(user).once

Stubs

Here are the ways to stub the User.find method. When the User class object receives a call to find with the argument '99' it will return user1. When User receives find with any other arg, it returns user2.

RR

stub(User).find('99') { user1 }
stub(User).find { user2 }

Mocha

User.stubs(:find).with(anything).returns(2)
User.stubs(:find).with('99').returns(1)

spec/mocks

users = {
  '99' => user1,
  'default' => user2
}
User.stub!(:find).and_return do |id|
  users[id] || users['default']
end

Flexmock

users = {
  '99' => user1,
  'default' => user2
}
flexstub(User).should_receive(:find).and_return do |id|
  users[id] || users['default']
end

Proxy

A proxy used with a mock or stub causes the real method to be called. Expectations can be placed on the invocation and the return value can be intercepted. The main rationales are test clarity and you can ensure that the methods are being called correctly, even after you refactor your code. I will delve more into proxies and their usage patterns in my next article.

Mock Proxy

The following examples set an expectation that User.find('99') will be called once. The actual user is returned.

RR

mock.proxy(User).find('99')

Mocha

You cannot implement this in Mocha. You can do an approximation in this situation however. This technique is not always the solution you need, though.

user = User.find('99')
User.expects(:find).with('99').returns(user)

spec/mocks

find_method = User.method(:find)
User.should_receive(:find).with('99').and_return(&find_method)

Flexmock

find_method = User.method(:find)
User.should_receive(:find).with('99').and_return(&find_method)

Stub Proxy

The following examples intercept the return value of User.find('99') and stub out valid? to return false.

RR

stub.proxy(User).find('99') do |user|
  stub(user).valid? {false}
  user
end

Mocha

Again, this is an approximation, since you cannot use proxies in Mocha.

user = User.find('99')
user.stubs(:valid?).returns(false)
User.stubs(:find).with('99').returns(user)

spec/mocks

find_method = User.method(:find)
User.stub!(:find).with('99').and_return do |id|
  user = find_method.call(id)
  user.stub!(:valid?).and_return(false)
  user
end

Flexmock

find_method = User.method(:find)
flexstub(User).should_receive(:find).with('99').and_return do |id|
  user = find_method.call(id)
  flexstub(user).should_receive(:valid?).and_return(false)
  user
end

instance_of

instance_of is method sugar than allows you to mock or stub instances of a particular class. The following examples mock instances of User to expect valid? with no arguments to be called once and return false.

RR

mock.instance_of(User).valid? {false}

Mocha

User.any_instance.expects(:valid?).returns(false)

spec/mocks

new_method = User.method(:new)
User.stub!(:new).and_return do |*args|
  user = new_method.call(*args)
  user.should_receive(:valid?).and_return(false)
  user
end

Flexmock

new_method = User.method(:new)
flexstub(User).should_receive(:new).and_return do |*args|
  user = new_method.call(*args)
  flexmock(user).should_receive(:valid?).and_return(false)
  user
end

More to come

This concludes the introduction to RR. RR enables some techniques, like proxying, that will make your tests clearer and less brittle. In the next article I will describe into patterns and techniques that will make mocks a more feasible tool for more situations.

I have a few gems on Rubyforge and I want to track how many of them were downloaded. I found Firefox's search tools lacking to find my gem rr.

To fix this issue, I made a sake task, named gems:downloads:list, that prints the gem downloads in text.

The source is on caboo.se.

You can install it by using:

sudo gem install sake
sake -i http://pastie.caboo.se/79547.txt gems:downloads:list
sake gems:downloads:list | less

This will give an output like:

------------------------------------------------
|                              Gem | Downloads |
------------------------------------------------
|                            rails |   1194471 |
|                     activerecord |   1121778 |
|                       actionpack |   1054718 |
|                    activesupport |    990851 |
|                     actionmailer |    960759 |
|                 actionwebservice |    948640 |
|                             rake |    860824 |
|                            mysql |    593476 |
|                             fcgi |    230394 |
|                          mongrel |    220370 |
|                          daemons |    167443 |
|                          rmagick |    164537 |
|                       gem_plugin |    153505 |
|                         RedCloth |    147182 |
|                  rubygems-update |    119615 |
|                          net-ssh |    114369 |
|                     sqlite3-ruby |    105796 |
|                       fastthread |     95534 |
|            cgi_multipart_eof_fix |     95399 |
|                           needle |     87718 |

Sake is way cool. It was just too easy to implement and deploy this. Have fun making your own sake tasks.

We all like a good oxymoron, like redefining constants. There are times where we need to redefine a constant to test an edge case in the application code. Before I go into this example, please note that redefining constants is generally not a good way to have maintainable software. If you find yourself needing to redefine a constant, it may be an indication that refactoring is needed.

Given that, lets get into an example where you may need to redefine a constant. Lets say an app has does file uploads to Amazon's S3 service. A common practice to upload to a real S3 account made for the production, development, or demo environment.

When in the test environment, a fake S3 service would be used instead. The fake service is useful to keep your tests fast and running predictably.

To get a different File Upload service object in each of your environments, one can have the S3 configuration in the environment files:

test.rb

STORAGE_SERVICE = FakeStorageService.new

development.rb

STORAGE_SERVICE = S3StorageService.new("development_service", "access_key", "secret_access_key")

production.rb

STORAGE_SERVICE = S3StorageService.new("production_service", "access_key", "secret_access_key")

The File Upload service objects can be set to constants in the environment file. This works great when testing the logic of the objects that use the File Upload service. However it is a good idea to run an integration test that does a real upload.

Since the tests are running in the test environment, a fake File Upload service is being used. Well now we want to use a real service that points to a test S3 account. An easy trick is to redefine the constant to the S3 service in setup and then redefine the constant back to the fake service on teardown.

There are a few ways of doing this...

Just Reset the Constant

context "A real S3 call" do
  setup do
    STORAGE_SERVICE = S3StorageService.new("test_service", "access_key", "secret_access_key")
  end
  teardown do
    STORAGE_SERVICE = FakeStorageService.new
  end
end

This is the simplest approach, but it produces an error:

warning: already initialized constant STORAGE_SERVICE

###Use silence_warnings

context "A real S3 call" do
  setup do
    silence_warnings do
      STORAGE_SERVICE = S3StorageService.new("test_service", "access_key", "secret_access_key")
    end
  end
  teardown do
    silence_warnings do
      STORAGE_SERVICE = FakeStorageService.new
    end
  end
end

This solution removes the warning, but now a certain section of your code will not have warning at all. Also, one could argue that you lose semantic meaning. It also feels like a hack.

Redefine the Constant

class Module
  def redefine_const(name, value)
    __send__(:remove_const, name) if const_defined?(name)
    const_set(name, value)
  end
end

context "A real S3 call" do
  setup do
    Object.redefine_const(
      :STORAGE_SERVICE,
      S3StorageService.new("test_service", "access_key", "secret_access_key")
    )
  end
  teardown do
    Object.redefine_const(
      :STORAGE_SERVICE,
      STORAGE_SERVICE = FakeStorageService.new
    )
  end
end

Calling redefining the constant does not generate a warning. Also it does provide semantic value because you are actively declaring that you are redefining the constant. If there are other warnings, you will also see them.

Its all Dirty

Redefining constants is a non-standard tatic, especially for those new to Ruby. Since this is unconventional and is often contrary to assumptions, it may lead to unpredictable behavior.

Maybe the storage service can be an attribute that can be changed for individual tests.