[rspec-users] Step matchers

Zach Dennis zach.dennis at gmail.com
Mon Oct 15 20:14:00 EDT 2007

I agree with the start of this thread with Pat Maddox stating,

  "I think we all know that the readability of steps isn't great right

My argument in the thread [0, 1] that may have sparked Pat's initial
implementation of StepMatcher's  asked the question about what value
is being added by adding arbitrary arguments to story part
descriptions. It seems that adding arbitrary arguments, and increasing
the "cody-ness" in our story files is a step in the wrong direction. I
like where Pat is going.

David Chelimsky has pointed out that doing something similar to what
Pat has implemented could allow us to remove quotes completed as the
stories themselves could live in a completely "code-free" text file

Although this is the ideal it seems to be a less pragmatic solution
then one which strives to accomplish both the customer ideal (or holy
grail as Dave refers to it) and one that works well with developers
and their tools. A more pragmatic solution appears to be striking a
good balance between both audiences. A way to allow customers to
clearly define and update stories and a way for developers to
implement them without becoming burdened with unnecessary steps in the

To me adding a story parser to parse a text file adds overhead to the
rspec team and to developers and customers using it. In a way I fear
that the textual freedom of a raw text file will lead to many gray
area's both on the rspec's implementation of it and also for
developers trying to explaining to their customers why or why they
cannot do something. I don't know if this is greater then the
conversation that already has to take place though. I personally don't
know customer's who write the final draft of an acceptance test.

Wincet Colaitua brings up a good point [3] in regards to StepMatchers:

  "My main concern here is that you're now having to keep two files in
  sync to have the stories work properly."

It is difficult to maintain consistency among plain english sentences
when there is no meaning behind the sentence structure. It seems to be
an additional burden to the developer to have remember that how to
conform to a potential regular expression defined somewhere in a step
matcher. It is not a simple one to one translation, especially as
different people write different kinds of StepMatchers. Each
StepMatcher may have it's own idiot which could become painful to
maintain or figure out after the fact.

Wincent also brings up in the same post [3]

 "The great thing about the Story Runner in its current form (and RSpec too)
  is that you can start off by writing a skeleton using a natural-language-like
  Ruby DSL, and then you flesh it out with code to fulfill its purpose"

This is the part of Story Runner that I want to hold onto. In my
opinion a worthwhile balance to start exploring is one that does the
following things:

* creates an easy one to one mapping between a description and a method
* remove do/end blocks, they are not needed and are a negative for the customer
* keeps story's clean and tidy, not full of unnecessary code artifacts

An implementation of this is the test/unit StoryRunner project that
I've been working on.

It is similar to rspec's implementation but it does the three things
listed above. A nicely color formatted example can be found at

A few things to note about the example:

* Story's do not use do/end blocks to organize scenarios. It is not
needed. Scenario's belong to the last Story declaration preceding it.

* Scenario's do use do/end blocks to nest their story parts.

* Descriptions used for Given, Then, When and And translate to a
method call. The rules are simple. Take the description, downcase it
and strip out punctuation. Replace whitespace with underscores and try
to find a method. If one exists, call it. If one doesn't exist strip
the first word, and try again. Repeat until there are no words left.
If no method was matched then raise an exception with the original
description string.

The idea behind this is that you create a clean way to write and
maintain Story's. It minimizes the "cody" aspects while still allowing
you to write executable ruby code.

The helper methods which are implemented follow a simple convention
for translating a  sentence description into a helper method and the
implementation of the story's are implemented in well named helper
methods (which i think adds to maintainability over StepMatchers).

The test/unit story runner still allows argument passing, but it is
encouraged when it adds value and not for arbitrary pieces of
information which do nothing for the test but increase the difficulty
of readability.

I really enjoy this thread and I'm very excited to see what will come
out of these recent threads,

Zach Dennis

0 - http://rubyforge.org/pipermail/rspec-users/2007-October/003690.html
1 - http://rubyforge.org/pipermail/rspec-users/2007-October/003703.html
2 - http://rubyforge.org/pipermail/rspec-users/2007-October/003708.html
3 - http://rubyforge.org/pipermail/rspec-users/2007-October/003729.html

More information about the rspec-users mailing list