rspec users - May 2008 - 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 Sun, May 11, 2008 at 4:01 PM, Ben Mabey <ben at 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 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.
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,
> Ben

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


--
Zach Dennis
http://www.continuousthinking.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://rubyforge.org/pipermail/rspec-users/attachments/20080511/5be11a13/attachment-0001.html>

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

Kyle Hargraves wrote:
> On Sun, May 11, 2008 at 4:01 PM, Ben Mabey <ben at 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.
>   
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?
> 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
> _______________________________________________
> rspec-users mailing list
> rspec-users at 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