Frankly, if there's one part of RSpec I wish never existed, it's the 'be_' construction. If tests are supposed to be part of the documentation on how to use the code, then in this case Rspec actually hurts you. I've been converting all my be_ usage (except for be_true, be_false, and be_nil) to the following:
Now you know exactly how the code works (this is the method name, it returns a boolean), vs:
froot.should be_hoopy
which requires you to be very familiar with Rspec to know that it will magically add the "?" when searching for the method, and the "be_" is extraneous to allow "readability".
Though back to the OP, if you want tests that read like manuals, Rspec is the wrong place to look. Tools exist explicitly for this purpose, namely Cucumber. Code is code, and it's always going to look like code. Any attempts to make it read more like English gets you into the realm of ridiculous verbosity or code explosion as you keep abstracting to give you things that "read good".
This sort of thing will likely be surprising to someone new to Rspec. However, as a general rule, I don't think it's fair to knock tools because they're a bit tough for new users to understand. Someone new to vim is hopelessly lost and slow at first, but I can fly with it, because I've taken the time to learn it.
Yes, I had to invest some time to learn about Rspec's 'be_' construction; yes, it confused me at first. However, having learned it, I always use it now. I really enjoy the readability of the code that results from it.
As in many things, there is a tradeoff here. It's fair for both of us to argue that we prefer to sacrifice different things.
There's a difference in the error messages each produces if the assertion fails.
frood.should be_hoopy
will output something like "#<Frood:0xabc> should have been hoopy, but wasn't", which often makes it easy to see at a glance what bug your code change has introduced; whereas
frood.hoopy?.should be_true
will output "expected false to be true", which is very Zen but not so helpful for debugging.
This. I actually wish the be_ facility worked for methods besides booleans. Like:
it do
frood.should be_hoopy_for(apples, oranges)
end
Which would say "#<Frood> should have been hoopy_for #<Apples>, #<Oranges>". There's real value in giving your test infrastructure more responsibility for actually piecing together the assertions. Not only does it give you better error messages, it lets you avoid having to write so many explanatory labels for all of your assertions.
The explosion of domain-specific languages that we've seen in the Ruby space in the last few years, from Capistrano for deployment to Sinatra for web apps, would seem to contradict your statement. A friendly language helps with and encourages friendly programming but does not guarantee it.
Rails itself contains several nice, simple APIs that hide extremely complex implementations. Simplicity is not the same thing to everyone.
The trouble with RSpec is that you, and your team, must to some degree own the complexity built into the framework. If that's something that you're comfortable with, the complexity pays you back in spades for the literacy that it provides your tests.
I'm strongly in favor of written documentation for gems that you assume others will consume. But if you're writing app code and the primary consumers of it are the other programmers on your project, literate tests really, really help. RSpec, and its 80%-as-nice-but-much-simpler cousin, Shoulda, are your friend here.
RSpec's DSL is like a girl who sends flowers after your first date. You want to like her, You SHOULD like her, but it's a little weird that she should be trying so hard.
frood.hoopy?.should be_true frood.knows_where_its_towel_is?.should be_false
Now you know exactly how the code works (this is the method name, it returns a boolean), vs:
froot.should be_hoopy
which requires you to be very familiar with Rspec to know that it will magically add the "?" when searching for the method, and the "be_" is extraneous to allow "readability".
Though back to the OP, if you want tests that read like manuals, Rspec is the wrong place to look. Tools exist explicitly for this purpose, namely Cucumber. Code is code, and it's always going to look like code. Any attempts to make it read more like English gets you into the realm of ridiculous verbosity or code explosion as you keep abstracting to give you things that "read good".