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

[Ben Mabey]

David Chelimsky wrote:
> 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.
Great point.  Lower level specs (unit tests) are meant for developer use 
only and I think that is the mentality that I was getting trapped in for 
the scenarios as well.  Instead of considering just our  confidence and 
yearning for a better design the confidence of the customer also needs 
to be addressed and accounted for.

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

Ahh, yes.  Thanks for setting me straight on that.
>
>> 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.
>
> Exactly!!!!!!
>
>> 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?
>
>
> Exactly!!!!!!
>
>> 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.
>
> Cheers,
> David

Thanks for your thoughts.  This helped me clear things up and confirmed 
what I was thinking.

-Ben