RSpec is a Behaviour-Driven Development tool for Ruby programmers. Created shortly after JBehave in 2005, its raison d'être has been writing human-readable specifications in the BDD tradition - accessible to not just developers but also business users, analysts, and testers. Over the years, though, that idea of accessibility to an audience beyond just developers seems to have been lost on many. I suspect that's because many view RSpec as little more than a testing tool with a DSL rather than the BDD tool that it's meant to be.
This narrower developer-focused view leads to dubious guidelines like the ones documented on Better Specs. One of the very first ones there is about how to describe your methods.
How to describe your methods
The only guideline needed on that topic is: Don't do it. Describe behaviors, not methods.
Instead, you get guidelines like: Be clear about what method you are describing. For instance, use the Ruby documentation convention of
. (or ::) when referring to a class method's name and # when
referring to an instance method's name.Below is an example of a supposedly good practice according to that guideline.
# (supposedly) good
describe Lemon
describe "#yellow?" do
context "when ripe" do
it "returns true"
end
end
end
# vs (supposedly) bad
describe Lemon
it "is yellow if ripe"
end
When trying to reason about good practice, I find it always instructive to go back to the origins of an idea. Here too, Dan North's article introducing BDD offers great insight. Some quotes:
[...] when they wrote the method name in the language of the business domain, the generated documents made sense to business users, analysts, and testers.Notice how, in contrast to the above example, the emphasis is on the language of the business domain (e.g. Lemon is yellow if ripe), rather than the language of code (e.g.
Lemon#yellow?, when ripe, returns true) that would make little sense to someone other than a developer.
This sentence template – The class should do something – means you can only define a test for the current class.Notice how the reference is to a class, not a method. The class, not its methods, should do something. Why should anyone care about whether
Lemon#yellow? returns true rather than whether Lemon is yellow?
If you find yourself writing a test whose name doesn’t fit this template, it suggests the behaviour may belong elsewhere.Consider this Active Record test (assuming Lemon is an Active Record model).
describe Lemon
describe ".ripe" do
it "returns only ripe lemons"
end
describe ".rotten" do
it "returns only rotten lemons"
end
end
This test just can't be written in the form 'Lemon should do something' following the suggested template. Because after all, we aren't really describing a Lemon here. What we're describing is the equivalent of a Lemon Repository (or Lemon Basket, perhaps, in the UbiquitousLanguage of the domain) or Data Access Object or whatever floats your goat when it comes to persistence. Active Record sadly conflates a model's class and its persistence mechanism, even though they're two clearly distinct concepts with distinct concerns. If the two concepts weren't conflated, you'd write tests that don't need to describe methods anymore but can describe the behavior/responsibilities of a class, as below:
describe LemonBasket
it "should provide only ripe lemons"
it "should provide only rotten lemons"
end
Another way to think about this is to remember that a class is an object, and class methods are, therefore, really instance methods of the (singleton) class object. So, if you include descriptions of .class_methods and #instance_methods in the description of a class, you're really mixing the descriptions of two different classes (pun intended) of objects. Consider this sample from RSpec's own documentation:
RSpec.describe Widget, :type => :model do
it "has none to begin with" do
expect(Widget.count).to eq 0
end
it "has one after adding one" do
Widget.create
expect(Widget.count).to eq 1
end
end
That description just doesn't make any sense as soon as you try to read it as sentences that'd appear in RSpec output formatted as documentation.
Widget has none to begin with has one after adding oneThat doesn't make sense because what you're really describing is conceptually something like a WidgetWarehouse.
WidgetWarehouse has no widgets to begin with has one widget after adding (storing?) oneWith Active Record, the Widget class above doubles up as a singleton WidgetWarehouse (WidgetDAO/WidgetRepository/whatever). But instead of letting that incidental implementation detail drive the structure of your tests, you could recognize that they're essentially two distinct concepts/concerns, and describe them in independent tests rather than first mixing them up in the same class test and then trying to distinguish them through syntactic conventions.
Moreover, method descriptions aren't conducive to true BDD or TDD style in general. The behaviors of an object are known before the tests, but the structure (method names, signatures, etc.) quite often emerges. For instance, the behavior
WidgetWarehouse has one widget after adding one is known at the time of writing the test, but the method that'd provide that behavior isn't (.add or .store? - I shouldn't have to make up my mind before writing the first test.).Using cutesy syntactic conventions to describe classes based on their structure allows, even encourages, you to sidestep such considerations and suppresses the feedback generation mechanism that's at the heart of TDD and BDD. Focusing on and describing behavior forces you to think more deeply about the behavior and where it belongs.
