[rspec-users] Are you writing "imperative" or "declarative" scenarios in your stories?

Ben Mabey ben at benmabey.com
Sun May 11 17:01:17 EDT 2008

Hey all,
I just found Bryan Helmkamp's (of webrat fame) slides on a presentation 
he did at GoRuCo 2008:


On slides 21-24 he talks about writing good stories and shows gives two 
examples.. the way not to do it and the way to do it.  You can also see 
the video of the presentation at confreaks 
(http://goruco2008.confreaks.com/01_helmkamp.html -- jump to 13:24 to 
see where he talks about the two examples.)  The first is what he calls 
an imperative example:
Scenario: Reject duplicate names

Given I am on the Developers page

When I click the Add Developer button

Then I should see the Add Developer page

When I enter the first name Zed
And I enter the last name Shaw
And I click the Create Developer button

Then I should see the message "Zed was created"
And the Developers list should contain Zed Shaw

When I enter the first name Zed

And I enter the last name Shaw
And I click the Create Developer button

Then I should see an error "There can be only one Zed Shaw"

The second is a declarative example and the same scenario reads like:

Scenario: Reject duplicate names

Given there is a developer Zed Shaw

When I try to add a developer named Zed Shaw

Then I should see an error "There can be only one Zed Shaw"

Bryan argues that the imperative version is a poor choice because it is 
too coupled to the implementation;  keeping a scenario up to date with 
future maintenance changes may be a pain when you have to add or remove 
fields.  Additionally, the declarative version removes all of the noise 
so that the most important features of that story stand out.
The imperative version looks like the "detailed scenarios" that David 
talked about at his ETEC slides 
(http://blog.davidchelimsky.net/articles/2008/04/01/etec-slides.)  On 
slide #75 David gives a good overview of the pros and cons of this 
style.  The pros mentioned are that they are easier to write and easier 
to change.

While my stories may not read quite as bad as the example presented by 
Bryan I have been going down more of the imperative/detailed scenario 
route the majority of the time.  I have done this due to the high reuse 
of steps that it enables.  I haven't ran into maintenance issues with 
them yet but I can understand that point.  The more and more I think 
about it the more I agree with Bryan though.  The declarative version 
does feel a lot better and seems to keep the salient points more 
prominent.  Keeping the stories small, I think, is also more in line 
with the typical user stories in XP and other agile methodologies.  (I 
would like to see someone stick the first example on a 3x5 card :). ) 

I did Use Cases (Alistair Cockburn style) on a project several years ago 
and I remember that revealing anything about the interface or 
implementation was a big no no.  I realize that user stories != use 
cases so I'm trying to find a balance between UI based stories and more 
declarative stories that don't reveal the implementation.  The funny 
thing is that I started out doing more declarative stories but my 
current customer kept wanting to write stories dealing with how the 
forms worked.  It seemed silly to fight the customer on this since the 
app will always be a web app.. so maybe it is just a balancing act we 
have to play on a case by case basis?

I'm curious what everyone else on this list has been doing in this 
regard.  Are you writing declarative scenarios all the time?  Or are you 
reusing a lot of your steps with detailed scenarios?  A little bit of 
both maybe?  If so, how do you decide which type of scenario to use in a 
given case?  Any other thoughts on this matter?


More information about the rspec-users mailing list