[rspec-users] How to write specification for the *base* class API?

Pat Maddox pergesu at gmail.com
Tue Jul 15 10:24:39 EDT 2008

On Tue, Jul 15, 2008 at 10:10 AM, Piotr Wlodarek <lists at ruby-forum.com> wrote:
> David Chelimsky wrote:
>> On Jul 15, 2008, at 8:22 AM, Piotr Wlodarek <lists at ruby-forum.com>
>> wrote:
>>> It's not AR. I have 2 levels: Site1Scraper < BaseScraper.
>>> There will be many SiteXScrapers implemented by several people.
>>> ++++
>>>> From your answers I conclude it's not possible (or at least not
>>> recommended) to document abstract interface with RSpec.
>> If everyone gave up that easily we'd never improve anything ;)
>> Not sure how you get to "not possible." Pat suggested shared examples,
>> which would be a perfectly good solution for part of the problem.
>> I think the question is what are you trying to acheive here and
>> whether Rspec (or any testing framework) is the right place for that
>> goal.
> I try to document public API of important base class.
> Shared examples, as you said, solve part of the problem.
> Since I try to develop this project in a BDD style, and specifications
> are said to be - among other things - a documentation tool, it seems
> reasonable to take advantage of it. Alternative is mixed documentation
> of rdoc + specs.
> In a perfect world I would expect to have only one documentation tool:
> specs.

I think in this case you could provide contract tests.  These would be
shared behaviors that developers can mix in to their own specs.
Consider something basic for an account:

describe "account", :shared => true do
  it "should increase in balance after a deposit" do
    start_balance = account.balance
    account.deposit 100
    account.balance.should > start_balance

  it "should decrease in balance after a withdrawal" do
    start_balance = account.balance
    account.withdraw 100
    account.balance.should < start_balance

This defines the contract of an Account abstraction... you can imagine
different account types that might implement it in a way that the
actual dollar values differ.  For example, fees may be applied to one
kind of account but not another.

Anyone who implements your API can include that shared example group
and verify their code against the contract you've defined.


More information about the rspec-users mailing list