Ruby Forum RSpec > Are you writing "imperative" or "declarative" scenarios in your stories?

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.

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?

Thanks,
Ben

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

>  -- jump to 13:24 to see where he talks about the two examples.)   
> When I enter the first name Zed
>
> When I try to add a developer named Zed Shaw
> 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.

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

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

On Sun, May 11, 2008 at 4:01 PM, Ben Mabey <ben@benmabey.com> wrote:
> 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?

When I first started writing stories for rails apps, I primarily used
the declarative form, just because they were easier to implement and
reusing steps was generally difficult anyhow. It was just the natural
style that I'd hit upon when writing them for small projects I used to
play with rbehave / the story runner.

Once webrat came about, I moved toward the imperative form, with a lot
of steps that were just english forms of the webrat helpers ("When I
click the link ...", "When I select Foo from the Bar menu", etc). This
was really nice, since I was able to write a number of scenarios
almost entirely without implementing any steps. Mix in some
GivenScenario and you could get fairly detailed paths through the
application with minimal effort.

But then, I'd come back to a story and have to, god forbid, think
about what the meaning was. The story description and scenario name
will hint at it, but the meat was tough to pick out of the steps. Too
many times, I'd had to sit down with a coworker while we figured out,
"why did we write this?"

So for the past few months I've come full circle, and I prefer short,
high-level scenarios that describe the *feature*, not the particular
way it might be performed within the current interface. I don't get to
reuse steps as often, but with a few helper methods mixed into
Spec::Story::World, it hasn't been an issue. The scenarios themselves
are terse and get right to the point.

It has made a *big* difference in how useful my stories are as
documentation, and maintenance is significantly easier when the UI is
tweaked. It hasn't really affected my level of confidence in them
serving as tests -- it either fails or it doesn't -- but the other
wins have been worth it.

That said, some of my scenarios, especially when first tinkering on a
new feature, still read like a howto manual for a web browser. "Click
this button", "Type XYZ in this field", etc. One or two of those don't
bother me, but I move on to more abstract language -- Bryan's "When I
add Zed Shaw" -- once it's solid enough to elide the details.
Sometimes I go back and edit the initial scenarios, sometimes I don't.

Kyle

On Sun, May 11, 2008 at 5:01 PM, Ben Mabey <ben@benmabey.com> wrote:

> where he talks about the two examples.)  The first is what he calls an
>
> And I click the Create Developer button
>
> future maintenance changes may be a pain when you have to add or remove
> the majority of the time.  I have done this due to the high reuse of steps
> find a balance between UI based stories and more declarative stories that
> other thoughts on this matter?
>

I've been doing both with more scenarios leaning towards imperative than
declarative.  I find that my stories tend to be more of a mixture of the
imperative/declarative styles mentioned. For example I would have 
probably
written:

----------------------------------------------------------------------------
Scenario: Reject duplicate names

Given there is a developer named Zed Shaw in the system
And a user at the add a developer page
When they enter the first name Zed
And they enter the last name Shaw
And they click the Create Developer button
Then they should see an error "There can be only one Zed Shaw"
-------------------------------------------------------------------------------------

I think there are other benefits of going the declarative route as well,
such as creating a nicer set of re-usable helper methods sooner. When 
you
have more granular steps it seems there is less pain and discomfort 
upfront
associated with writing less re-usable pieces of code.  When you go the
declarative route all of your code is pushed together without the 
granular
step boundaries, forcing you to face up and extract out methods which 
reveal
the intent of the step.

David Chelimsky wrote:
>> also see the video of the presentation at confreaks 
>>
>>
>>
>> is too coupled to the implementation;  keeping a scenario up to date 
> To be clear - I mean that the step definitions themselves are easier 
> 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.

> "Given that I am logged in as Joe Smith" or "Given that I am logged in 
>> 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.
> Exactly!!!!!!
>> 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

Kyle Hargraves wrote:
> the declarative form, just because they were easier to implement and
> application with minimal effort.
> reuse steps as often, but with a few helper methods mixed into
> Spec::Story::World, it hasn't been an issue. The scenarios themselves
> are terse and get right to the point.
>   
Good point.  So, do you just define all your helpers in your helper.rb
file or do you monkey patch it in each of the step files?
> add Zed Shaw" -- once it's solid enough to elide the details.
> Sometimes I go back and edit the initial scenarios, sometimes I don't.
>
> Kyle
> _______________________________________________
> rspec-users mailing list
> rspec-users@rubyforge.org
> http://rubyforge.org/mailman/listinfo/rspec-users
>   

Thanks for sharing your experience.  In your case have you had a
customer help writing the scenarios or are you creating them yourself?

-Ben