rspec users - Apr 2009 - Best practices: How small to make examples?

Hi,

How small should examples be?

Let''s say I have a form, should there be one example per field? If
there''s a
dropdown, should I describe the dropdown and have one example per option? I
thought that at first but now, because of the duplication and sheer
verbosity, it seems too much.

So what do you think?

Brandon

On 5 Apr 2009, at 03:56, Brandon Olivares wrote:
> Hi,
>
> How small should examples be?
>
> Let''s say I have a form, should there be one example per field? If
> there''s a
> dropdown, should I describe the dropdown and have one example per  
> option? I
> thought that at first but now, because of the duplication and sheer
> verbosity, it seems too much.
>
> So what do you think?
http://blog.jayfields.com/2007/06/testing-one-assertion-per-test.html

Again, I would urge you to listen to the tests and question whether  
writing unit tests for your views is worthwhile. If you''re finding it  
a hassle, there might be a reason for that :)

Matt Wynne
http://blog.mattwynne.net
http://www.songkick.com

On Sun, Apr 5, 2009 at 4:24 AM, Matt Wynne <matt at mattwynne.net>
wrote:
> On 5 Apr 2009, at 03:56, Brandon Olivares wrote:
>
>> Hi,
>>
>> How small should examples be?
>>
>> Let''s say I have a form, should there be one example per
field? If there''s
>> a
>> dropdown, should I describe the dropdown and have one example per
option?
>> I
>> thought that at first but now, because of the duplication and sheer
>> verbosity, it seems too much.
>>
>> So what do you think?
>
> http://blog.jayfields.com/2007/06/testing-one-assertion-per-test.html
or http://rubyurl.com/yCt3
>
> Again, I would urge you to listen to the tests and question whether writing
> unit tests for your views is worthwhile. If you''re finding it a
hassle,
> there might be a reason for that :)
There is a trend these days away from isolated view specs. My own
opinion is that this is *generally* a good thing *if* you''ve got
something like cucumber scenarios that take you through the views in
question.

That said, I''m not yet convinced that view specs shouldn''t
still be
part of your toolkit. I generally use RSpec and Cucumber these days,
and I like to progress in small, verifiable steps. So let''s say I set
up a cucumber scenario in the declarative style:

Given I register for a conference
Then my name should be on the list of conference attendees
And the conference should be my list of conferences

Note that lack of "When I fill in ..." sort of steps. The first given
is going to take care of the details of filling in the form. This way,
if something about the form changes, I need to change the underlying
step definition, but I don''t need to revisit all the scenarios that
use it. So lets say the form has 10 fields split out into two pages.
That''s going to take some time to get working, and the whole time
I''m
developing the parts, I''m going to have this one failing step.

In a case like this, I might spec the view using rspec, so that I can
add one field at a time and verify each field as its done. This way
I''m getting green bars every minute or so, which keeps me relaxed as I
go.

But that''s me. And I don''t do it or recommend doing it for
everything
all the time. Paraphrasing Matt, "listen to your specs."

Cheers,
David

>
> Matt Wynne
> http://blog.mattwynne.net
> http://www.songkick.com
>
> _______________________________________________
> rspec-users mailing list
> rspec-users at rubyforge.org
> http://rubyforge.org/mailman/listinfo/rspec-users
>

On Sun, Apr 5, 2009 at 5:20 AM, David Chelimsky <dchelimsky at gmail.com>
wrote:
> Given I register for a conference
> Then my name should be on the list of conference attendees
> And the conference should be my list of conferences
If I were describing ''register for a conference'' in this
scenario,
then I would think it important to specify the steps that are used:

 Given I am logged in
 And I go to the registration page
 And I fill in the email field
 And I click "Register"
 Then my name should be on the list of conference attendees
 And the conference should be my list of conferences

That''s the level of detail the story would have, so that''s
what I want
to show works.

On the other hand, this could simply be describing what appears on the
screen when I am registered for a conference (as opposed to how I got
there). In that case, the Given would simply add a database row. But
there would be a different story for the process of filling out the
form.

Sometimes, they can be combined. But my point is that scenarios still
have to describe how the user relates to the form and ''Given I
register for a conference'' doesn''t do that. When you do have a
scenario that includes this level of detail, you don''t need a view
spec, IMO. And you can still code step-by-step.

///ark

On Sun, Apr 5, 2009 at 12:03 PM, Mark Wilden <mark at mwilden.com>
wrote:
> On Sun, Apr 5, 2009 at 5:20 AM, David Chelimsky <dchelimsky at
gmail.com> wrote:
>
>> Given I register for a conference
>> Then my name should be on the list of conference attendees
>> And the conference should be my list of conferences
>
> If I were describing ''register for a conference'' in this
scenario,
> then I would think it important to specify the steps that are used:
>
> ?Given I am logged in
> ?And I go to the registration page
> ?And I fill in the email field
> ?And I click "Register"
> ?Then my name should be on the list of conference attendees
> ?And the conference should be my list of conferences
>
> That''s the level of detail the story would have, so
that''s what I want
> to show works.
>
> On the other hand, this could simply be describing what appears on the
> screen when I am registered for a conference (as opposed to how I got
> there). In that case, the Given would simply add a database row. But
> there would be a different story for the process of filling out the
> form.
Not necessarily. More on that below.
>
> Sometimes, they can be combined. But my point is that scenarios still
> have to describe how the user relates to the form and ''Given I
> register for a conference'' doesn''t do that.
Scenarios have to do no such thing. Scenarios are a
communication/collaboration tool. What they contain should support
that role, and is going to vary greatly from team to team. What you
describe might be right for your team, but that doesn''t mean
it''s
right for mine.

Keep in mind that the more imperative the scenarios are, the more of a
maintenance burden they become. The scenario I described above could
be run against a set of step definitions that run against a browser,
an API, a desktop app or even a command line shell. We could support
all of those interfaces and not have to change the scenario to do so.
That''s a huge amount of flexibility. The tradeoff is that you
don''t
see the details of the scenarios. For some that is a deal breaker. But
for others, not so much.
> When you do have a
> scenario that includes this level of detail, you don''t need a view
> spec, IMO. And you can still code step-by-step.
Agreed.

David
>
> ///ark
> _______________________________________________
> rspec-users mailing list
> rspec-users at rubyforge.org
> http://rubyforge.org/mailman/listinfo/rspec-users
>

On Sun, Apr 5, 2009 at 1:03 PM, Mark Wilden <mark at mwilden.com>
wrote:
> On Sun, Apr 5, 2009 at 5:20 AM, David Chelimsky <dchelimsky at
gmail.com> wrote:
>
>> Given I register for a conference
>> Then my name should be on the list of conference attendees
>> And the conference should be my list of conferences
>
> If I were describing ''register for a conference'' in this
scenario,
> then I would think it important to specify the steps that are used:
>
> ?Given I am logged in
> ?And I go to the registration page
> ?And I fill in the email field
> ?And I click "Register"
> ?Then my name should be on the list of conference attendees
> ?And the conference should be my list of conferences
>
> That''s the level of detail the story would have, so
that''s what I want
> to show works.
>
> On the other hand, this could simply be describing what appears on the
> screen when I am registered for a conference (as opposed to how I got
> there). In that case, the Given would simply add a database row. But
> there would be a different story for the process of filling out the
> form.
>
> Sometimes, they can be combined. But my point is that scenarios still
> have to describe how the user relates to the form and ''Given I
> register for a conference'' doesn''t do that. When you do
have a
> scenario that includes this level of detail, you don''t need a view
> spec, IMO. And you can still code step-by-step.
It seems that when developers write scenarios they often walk through
everything logically and fill in every input field from a scenario.
When my customers write scenarios they don''t do this, they tend to
think higher level. They write: "Given I register for a conference".

Over time I''ve found I lean towards the scenarios remaining higher
level.  When scenarios too detailed oriented for how "registering for
a conference is done" then it becomes a maintenance burden any time
how registering for a conference is updated.  I like allowing my
scenario to remain expressive about the behaviour of the app while
leaving out the details about every form field being filled in. In a
way it''s parallel with refactoring a public method. You can change the
details w/o changing how everything uses it. I find that''s akin to
scenarios. They should only change when the actual behaviour changes
(or at least that''s my goal to shoot for), not necessarily when the UI
gets reworked, or input fields get added or removed.

I also don''t think the scenario should try to relate the forms on the
UI to the user. There are better tools for this job: wireframes,
screen mockups, and the actual UI itself. It sounds like you may have
an expectation that the scenarios should read like step by step
instructions for using the app? An interesting idea, but it adds an
additional responsibility to the scenarios which I think will
ultimately convolute the value they are trying to express. At least it
has when I tried to do that months back.


> ///ark
> _______________________________________________
> rspec-users mailing list
> rspec-users at rubyforge.org
> http://rubyforge.org/mailman/listinfo/rspec-users
>


-- 
Zach Dennis
http://www.continuousthinking.com
http://www.mutuallyhuman.com

On Sun, Apr 5, 2009 at 10:03 AM, Mark Wilden <mark at mwilden.com>
wrote:
> Sometimes, they can be combined. But my point is that scenarios still
> have to describe how the user relates to the form
Scenarios should describe how a user relates to the application.
Whether you choose to do that by using fine- or course-grained stories
is context-dependent - what level of explicitness makes your customer
happy, other test coverage, etc.

> and ''Given I
> register for a conference'' doesn''t do that. When you do
have a
> scenario that includes this level of detail, you don''t need a view
> spec, IMO. And you can still code step-by-step.
True.  Although you invariably lose defect isolation when you do it
this way.  There are a lot more potential causes of failure when you
go through the whole stack than when you render a view in isolation.
Whether defect isolation is valuable enough to incur the cost of view
specs is up to you.

Pat

On Sun, Apr 5, 2009 at 11:16 AM, Zach Dennis <zach.dennis at gmail.com>
wrote:
>
> It seems that when developers write scenarios they often walk through
> everything logically and fill in every input field from a scenario.
> When my customers write scenarios they don''t do this, they tend to
> think higher level. They write: "Given I register for a
conference".
My customers give me mockups and indeed specify what fields must be filled in.
>?When scenarios too detailed oriented for how "registering for
> a conference is done" then it becomes a maintenance burden any time
> how registering for a conference is updated.
Fine, but then you''ve shifted the maintenance burden to your view
specs.
> ?I like allowing my
> scenario to remain expressive about the behaviour of the app while
> leaving out the details about every form field being filled in.
In many cases, if not most, what the user types is part of the
behavior of the app. Not for merely descriptive information - agreed.
But in my current app, most fields lead to differences in behavior.
E.g., the challenge is public, Zach has been invited to it, it expires
on a certain day, etc. I consider this information essential to the
behavior of the app, not "merely" the UI.

Of course, I''ve always felt that the UI is the most important part of
the app, anyway. I feel that if certain user actions lead to certain
physical output, then I''ve fufllled the requirements of the app.
> I also don''t think the scenario should try to relate the forms on
the
> UI to the user. There are better tools for this job: wireframes,
> screen mockups, and the actual UI itself. It sounds like you may have
> an expectation that the scenarios should read like step by step
> instructions for using the app? An interesting idea, but it adds an
> additional responsibility to the scenarios which I think will
> ultimately convolute the value they are trying to express. At least it
> has when I tried to do that months back.
You have to test this stuff somewhere. And perhaps I''m just
old-school, but to me, a user story does indeed specify what the user
does. If it''s too general, that makes its acceptance criteria
problematic.

///ark

On Sun, Apr 5, 2009 at 10:56 AM, David Chelimsky <dchelimsky at gmail.com>
wrote:
> What you
> describe might be right for your team, but that doesn''t mean
it''s
> right for mine.
Agreed.
> Keep in mind that the more imperative the scenarios are, the more of a
> maintenance burden they become.
I do work on this code, so I have some idea of the maintenance burden.
:)  But as I said to Zach, you still have the maintenance burden if
you defer this level of detail to view specs.
> The scenario I described above could
> be run against a set of step definitions that run against a browser,
> an API, a desktop app or even a command line shell. We could support
> all of those interfaces and not have to change the scenario to do so.
> That''s a huge amount of flexibility.
I am actually not a big fan of "flexibility." It''s great if
it''s free,
but I don''t find it persuasive in and of itself. I think this aligns
with the original principles of XP. I have had projects where a new
interface was required at some point. But the vast majority have not.
> The tradeoff is that you don''t
> see the details of the scenarios. For some that is a deal breaker. But
> for others, not so much.
I was really describing the way I approach scenarios, not prescribing
anything for others. I really hate writing view and controller specs,
and I''ve found (so far, at least), that describing user interaction in
scenarios obviates them and is better for communication with users.
Other people''s mileage may certainly vary.

///ark

On Sun, Apr 5, 2009 at 3:05 PM, Mark Wilden <mark at mwilden.com>
wrote:
> On Sun, Apr 5, 2009 at 11:16 AM, Zach Dennis <zach.dennis at
gmail.com> wrote:
>>
>> It seems that when developers write scenarios they often walk through
>> everything logically and fill in every input field from a scenario.
>> When my customers write scenarios they don''t do this, they
tend to
>> think higher level. They write: "Given I register for a
conference".
>
> My customers give me mockups and indeed specify what fields must be filled
in.
>
>>?When scenarios too detailed oriented for how "registering for
>> a conference is done" then it becomes a maintenance burden any
time
>> how registering for a conference is updated.
>
> Fine, but then you''ve shifted the maintenance burden to your view
specs.
View specs the domain of me and my co-developers. We are free to
maintain them using all the knowledge that we have about maintaining
code. Shifting the burden away from the scenarios to view specs
actually reduces the overall cost, in my view, as we don''t need to
have a meeting every time I want to refactor something.
>
>> ?I like allowing my
>> scenario to remain expressive about the behaviour of the app while
>> leaving out the details about every form field being filled in.
>
> In many cases, if not most, what the user types is part of the
> behavior of the app. Not for merely descriptive information - agreed.
> But in my current app, most fields lead to differences in behavior.
> E.g., the challenge is public, Zach has been invited to it, it expires
> on a certain day, etc. I consider this information essential to the
> behavior of the app, not "merely" the UI.
>
> Of course, I''ve always felt that the UI is the most important part
of
> the app, anyway. I feel that if certain user actions lead to certain
> physical output, then I''ve fufllled the requirements of the app.
>
>> I also don''t think the scenario should try to relate the forms
on the
>> UI to the user. There are better tools for this job: wireframes,
>> screen mockups, and the actual UI itself. It sounds like you may have
>> an expectation that the scenarios should read like step by step
>> instructions for using the app? An interesting idea, but it adds an
>> additional responsibility to the scenarios which I think will
>> ultimately convolute the value they are trying to express. At least it
>> has when I tried to do that months back.
>
> You have to test this stuff somewhere. And perhaps I''m just
> old-school, but to me, a user story does indeed specify what the user
> does. If it''s too general, that makes its acceptance criteria
> problematic.
It''s not about old-school or new-school or any school. It''s
about the
individual needs of your team, and what it is you need to communicate.
What you''re doing is perfectly fine if the details of every
interaction need to be communicated at this level.

Also, this isn''t necessarily an all or nothing deal. One way
I''ve
approached this that works well is to have a single scenario that
describes the details we''re talking about, and a lot more scenarios
that are more declarative. Now you have the best of all worlds.

FWIW,
David
>
> ///ark
> _______________________________________________
> rspec-users mailing list
> rspec-users at rubyforge.org
> http://rubyforge.org/mailman/listinfo/rspec-users
>

On Sun, Apr 5, 2009 at 1:37 PM, David Chelimsky <dchelimsky at gmail.com>
wrote:
>
> Also, this isn''t necessarily an all or nothing deal. One way
I''ve
> approached this that works well is to have a single scenario that
> describes the details we''re talking about, and a lot more
scenarios
> that are more declarative. Now you have the best of all worlds.
That''s what I do. One member of our team believes that every scenario
has to follow the UI all the way from login to the end result. I don''t
go that far.

///ark