Logo: Relish

  1. Sign in

Project: Rspec-fire-roles



Mocking against roles rather than concrete objects results in more flexible,
pluggable object designs. This gem builds upon the capabilities of rspec-fire
to make it easier to mock in this style while also knowing with confidence that
your objects and their collaborators are speaking through the same interfaces.


Add this line to your application's Gemfile:

gem "rspec-fire-roles"

Or install it yourself as:

$ gem install rspec-fire-roles

Add it to your spec_helper.rb:

RSpec.configure do |config|
  config.include RSpec::Fire
  config.include RSpec::Fire::Roles


While rspec-fire allows you to create mocks of specific concrete classes, this
isn't quite enough if you'd like to mock a role rather than a class. Mocking
roles results in more flexible designs, because a given object might play more
than one role, and more than one object might play the same role. Thinking in
terms of roles rather than objects also assists in the process of interface
, which is the main purpose of behavior-driven development as an
assistant to the design process.

For more on the topic of mocking roles, see the seminal paper on the topic. Also highly recommended reads are the
infamous Growing Object-Oriented Software Guided by Tests and Practical Object-Oriented Design in Ruby. See also the example usage below.

Full disclosure: Them be affiliate links.


Skip directly to the Relish documentation
for a simple worked example. Read on for a more detailed explanation.

Let's say you have a BatchSender object. Here's your spec:

require "roles/notifier"

describe BatchSender do
  describe "#send_messages" do
    it "passes each message to the injected notifier" do
      notifier = fire_double("Roles::Notifier")
      instance = BatchSender.new(notifier)
      notifier.should_receive(:notify).with("Subject 1", "Body 1").once
      notifier.should_receive(:notify).with("Subject 2").once

      instance.send_messages([["Subject 1", "Body 1"], ["Subject 2"]])

We're using a regular old fire_double here to create the mock, just like with
rspec-fire. But notice that, rather than passing in the name of some concrete
class which implements #notify with two arguments, we pass in the name of a
role. Here's that role, defined in spec/roles/notifier.rb (though it can be
defined anywhere as long as it gets included), which should be required in any
isolated unit test which depends upon this role so that rspec-fire recognizes

module Roles
  class Notifier
    def notify(subject, body = nil)

It's just an empty implementation of the interface. Thanks to rspec-fire, our
specs will now fail if they depend upon the Notifier role but the mock
expectations don't match this interface.

Now here's where rspec-fire-roles comes in. Here's the spec for a concrete
object which implements the Notifier role:

require "roles/notifier"

describe EmailNotifier do
  implements_role "Roles::Notifier"

  # [...] class-specific specs about notifying via email, not shown

The implements_role macro ensures that this spec will fail if the
EmailNotifier class doesn't have the right methods to satisfy the Notifier
role. Of course, this class can have additional public methods which don't have
anything to do with the role; the macro only checks that the methods on
Notifier are also implemented on EmailNotifier. Furthermore, multiple
implements_role calls can be added to the spec for objects which play more
than one role.

Here's an example of another class in the same system which plays this role,
plus another role (for demonstration purposes):

require "roles/notifier"

describe SmsNotifier do
  implements_role "Roles::Notifier"
  implements_role "Roles::Serializable"

  # [...] class-specific specs about notifying via SMS, not shown

You should be able to see what this gains over using rspec-fire alone. Let's
say later you decide to extract a Value Object instead of using arrays to
represent messages. First you change the role:

module Roles
  class Notifier
    def notify(message)

Now your BatchSender spec will fail because the fire_double is expecting
the wrong arguments, and your specs for EmailNotifier and SmsNotifier will
fail because the classes still implement the old interface which takes a
subject and body. You you can haz fast, isolated unit tests which mock roles
rather than objects without having to worry or write extra integration tests to
ensure that the objects play well together. Bliss!

Future improvements

  • It would be cool to have a nicer DSL for defining roles than just empty implementations.
  • It would also be cool if roles defined default return values for their fire_doubles.
  • The implements_role method presently only supports the interface of instances of the class. It would be nice to be able to specify that a role is implemented by class methods instead.
  • False positives are still possible. If expectations on a fire_double are set with the correct number arguments, but the types of the arguments are incorrect (for example, the role expects a single float parameter but a string is passed in), there's no way to detect this disparity because arguments aren't typed. I can imagine placing additional constraints a role such that arguments must match some other role, though I don't know if such a restriction would be worth it. In practice, such a scenario is probably quite rare.
  • The way rspec-fire works, there is no failure in a dependent class's spec if the role is simply not defined. This is intentional so that using fire_doubles can be done in both isolation and integration. Be sure your roles are actually being required when you use them, which should be fast enough for isolated tests.
  • Anything else. Feedback is appreciated!


  1. Fork it
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create new Pull Request


  1. Using roles with rspec-fire

Last published over 7 years ago by Chris Vincent.