[rspec-devel] Stories vs. examples

Alvin Schur a.schur at nucleus.com
Tue Nov 6 13:39:45 EST 2007

Are stories intended to mean "it worked in one case" to indicate a 
feature is present instead of being an exhaustive description of how 
edge cases are handled?

Are stories supposed to be comprehensive enough to pass a rigorous 


> ------------------------------
> Message: 9
> Date: Tue, 6 Nov 2007 13:43:23 +0000
> From: "Dan North" <tastapod at gmail.com>
> Subject: Re: [rspec-devel] Stories vs. examples
> To: rspec-devel <rspec-devel at rubyforge.org>
> Message-ID:
> 	<d559d8430711060543g5d8954fbu157afcc177e847a1 at mail.gmail.com>
> Content-Type: text/plain; charset="iso-8859-1"
> Hi Ian.
> I find it helps to think about the audience for your documentation. (It is
> documentation after all, it just happens to run, which is rather nice.)
> For the specs, the audience is developers. They want to know what an object
> of a particular type - or more specifically in a particular role - does,
> which other objects it interacts with and why. This audience wants to see
> progress without leaving their IDE or editor, which is why we put effort
> into making TextMate plugins and why we want to play nice with all the
> Test::Unit runners.
> For the stories, the audience is testers, analysts and ultimately the
> various stakeholders who are requesting the features. They want to know what
> the system does and how to interact with it to get work done. They don't
> really care what happens under the hood. Typically they are non-technical
> (or less technical than developers) which is why we think there is so much
> value in making their documentation look like documentation - just plain
> words on a page. Even better, if you can give them green words on a page
> when the feature is implemented and working, or red words on a page when the
> feature isn't working, or grey words for unimplemented features, they can
> see progress in a living document. Now make that document editable, like a
> regular document, and you are well on your way to acceptance testing
> Nirvana.
> So the process (described as "outside in" as opposed to "top down" or
> "bottom up") starts by expressing a feature request as a story, driving out
> the scenarios that define "done" for that story and automating the steps
> that make up the scenarios. Then you use code-level examples to drive
> inwards (that word "drive" again) from the outermost objects that the steps
> identified. All the time you want to implement just enough behaviour to get
> the steps to work, to drive the scenarios. Then you're done and you go to
> the pub for a well-earned drink. Hence "beer-driven development".
> Hope that helps,
> Dan
> On 11/6/07, Ian Dees <undees at gmail.com> wrote:
>> Hi, all.
>> I'm posting a philosophical question here, rather than cluttering up
>> the tracker for the patch where it originated.
>> Quoth David, in response to some fuzzy thinking on my part:
>>> Stories are not just another way to express examples - they're a
>> completely different animal.
>> The offending clause of mine: "stories are another way to write your
>> tests.... examples are meant for small, targeted descriptions of your
>> code's behavior... stories are suited to longer, more detailed
>> narratives."
>> The intent wasn't to say that stories are a different syntax for
>> examples; it was that stories and examples are two different syntaxes
>> for two different test-writing purposes.  But now I'm wondering if I
>> even have _that_ right.
>> In Rails-land, the distinction is much clearer: you typically see
>> examples for testing code, and stories for testing applications (in
>> the blog posts I've read, anyway).
>> But in GUI-land, the picture blurs a great deal: you're always testing
>> applications, but sometimes you're giving a tiny example of how one
>> feature works, and at other times you're writing a story about several
>> steps of an interaction between the customer and the UI.
>> Anyone want to jump into these muddy waters?
>> _______________________________________________
>> rspec-devel mailing list
>> rspec-devel at rubyforge.org
>> http://rubyforge.org/mailman/listinfo/rspec-devel

More information about the rspec-devel mailing list