[rspec-devel] Stories vs. examples

Dan North tastapod at gmail.com
Tue Nov 6 08:43:23 EST 2007

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

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,

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://rubyforge.org/pipermail/rspec-devel/attachments/20071106/ee8c7a82/attachment-0001.html 

More information about the rspec-devel mailing list