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

David Chelimsky dchelimsky at gmail.com
Sun May 11 18:05:41 EDT 2008

On May 11, 2008, at 4:01 PM, Ben Mabey wrote:

> Hey all,
> I just found Bryan Helmkamp's (of webrat fame) slides on a  
> presentation he did at GoRuCo 2008:
> http://www.brynary.com/2008/4/26/story-driven-development-slides- 
> posted
> 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.

To be clear - I mean that the step definitions themselves are easier  
to write and change - not the supported scenarios. In general, I think  
the overall maintenance cost is higher with this approach. But I don't  
agree that it is a definitively poor choice.

There's another factor to consider here - the human factor. Scenarios  
have an audience with whom they are trying to communicate something.  
The appropriate level of granularity is going to be driven in part by  
the communication needs of the audience. Working with FitNesse, I've  
encountered some stakeholders who really need to see every field  
represented and others who are perfectly happy with a more abstract  
representation. This needs to be accounted for when choosing the  
appropriate level of granularity.

Also, I find that even when there is a need for high levels of  
granularity in some cases, this doesn't need to happen throughout a  
suite of scenarios. For example, let's say that I've got an app that  
has to run in a browser, on the desktop and through a command line  
interface. I might have three separate scenarios to describe the login  
process. I might have one scenario that is high level enough that I  
can let it drive three different sets of step definitions. Regardless,  
this would only be required for the login scenario. Any other scenario  
that requires that the user is logged in can simply say something like  
"Given that I am logged in as Joe Smith" or "Given that I am logged in  
with the 'administrator' role", etc.

> 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 :). )

It is not necessary to include the scenarios on the card. What goes on  
the card is the narrative.

> 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?

Definitely a little of both. As with all things, there are always pros  
and cons to be weighed and the key to the craft is having a number of  
tools at your disposal and the wisdom to understand which tool to pull  
out when.


> Thanks,
> Ben

More information about the rspec-users mailing list