To add a collaborator to this project you will need to use the Relish gem to add the collaborator via a terminal command. Soon you'll be able to also add collaborators here!More about adding a collaborator
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:
Or install it yourself as:
$ gem install rspec-fire-roles
Add it to your
RSpec.configure do |config| config.include RSpec::Fire config.include RSpec::Fire::Roles end
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
discovery, 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"]]) end end end
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) end end end
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
require "roles/notifier" describe EmailNotifier do implements_role "Roles::Notifier" # [...] class-specific specs about notifying via email, not shown end
implements_role macro ensures that this spec will fail if the
EmailNotifier class doesn't have the right methods to satisfy the
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 end
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) end end end
BatchSender spec will fail because the
fire_double is expecting
the wrong arguments, and your specs for
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!
- 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
implements_rolemethod 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_doubleare 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!
- Fork it
- Create your feature branch (
git checkout -b my-new-feature)
- Commit your changes (
git commit -am 'Add some feature')
- Push to the branch (
git push origin my-new-feature)
- Create new Pull Request
Last published about 5 years ago by Chris Vincent.