Best practices: How small to make examples?


#1

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


#2

On 5 Apr 2009, at 03:56, Brandon O. wrote:

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 :slight_smile:

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


#3

On Sun, Apr 5, 2009 at 4:24 AM, Matt W. removed_email_address@domain.invalid wrote:

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 :slight_smile:

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


#4

On Sun, Apr 5, 2009 at 5:20 AM, David C. removed_email_address@domain.invalid
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


#5

On Sun, Apr 5, 2009 at 1:03 PM, Mark W. removed_email_address@domain.invalid wrote:

And I go to the registration page
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
removed_email_address@domain.invalid
http://rubyforge.org/mailman/listinfo/rspec-users


Zach D.
http://www.continuousthinking.com
http://www.mutuallyhuman.com


#6

On Sun, Apr 5, 2009 at 10:56 AM, David C. removed_email_address@domain.invalid
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.
:slight_smile: 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


#7

On Sun, Apr 5, 2009 at 12:03 PM, Mark W. removed_email_address@domain.invalid wrote:

And I go to the registration page
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


#8

On Sun, Apr 5, 2009 at 11:16 AM, Zach D. removed_email_address@domain.invalid
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


#9

On Sun, Apr 5, 2009 at 10:03 AM, Mark W. removed_email_address@domain.invalid 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


#10

On Sun, Apr 5, 2009 at 3:05 PM, Mark W. removed_email_address@domain.invalid wrote:

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.

behavior of the app, not “merely” the UI.

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


#11

On Sun, Apr 5, 2009 at 1:37 PM, David C. removed_email_address@domain.invalid
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