New nesting level/abstraction: stories

[jfinkhaeuser]

One of the practical weaknesses of gherkin currently is IMHO that the "feature" abstraction doesn't quite match how product managers/owners (PMOs) think of software.

Most PMOs think of a feature as a fairly large concept, such as "account settings" or "shopping cart", etc. The cucumber use of features lends itself much more strongly to think of features as user stories; in fact, I've seen mentioned in many best practice documentations that the feature description should be in the form of a "As a role/In order to achieve benefit/I want goal/desire" triplet, i.e. a classical user story.

The result is that what is intuitively grasped as a feature cannot be mapped onto a single feature file.

I would suggest to extend the Gherkin syntax with an optional Story keyword, that acts much as the feature keyword now does.

Feature:
  Shopping cart

  Story:
    As a role
    In order to achieve benefit
    I want goal/desire

    Scenario: some scenario for the story
      Steps

• The Story has no functional use, other than:
  • be taggable, including executing only scenarios under a matching story
  • be referencable via file.feature:linenumber, also for execution
• As a nice to have, Gherkin might be just aware enough of the user story triplet to parse "As a", "In order to" and "I want" so that they can be highlighted similar to "Given", "When", "Then"
  • Even more nice to have: highlight them also if they appear under Feature, see the next point.
• Having the Story optional means if it's absent, the old-style Feature -> Scenario hierarchy can be used, which keeps this backwards compatible.

[enkessler]

So...something similar to RSpec's arbitrarily nested 'describe' blocks?

I am guessing that you want to be able to include multiple stories in the same feature? I can see the benefit, but my first thought is that features are going to get LONG. Not wanting to read through a massive feature file is what encourages many people to have multiple smaller features as files that are then grouped under a larger feature as a folder.

--shopping_cart
    |
    |__empty_cart.feature
    |__save_cart.feature

If you don't intend to have multiple stories in the same feature file, then...I don't see the point. You can already write your narrative in whatever shape that you want to, so go ahead and stick "Story:" on it while you are at it. The extra place to hang tags and execute from would be pretty redundant because Feature is right there. All that you are really getting at that point is a different keyword that people are more comfortable with (which, admittedly, is not worthless because communication is important). Oh! Could we simply have a Story keyword that is an alias for Feature? Similar to how Give/When/Then are all the same thing under the covers?

Side note: highlighting sounds like the IDE's responsibility, not Gherkin's.

[aslakhellesoy]

A Story is a temporary planning artefact. It's an increment. I don't think it has a place in Gherkin.

@mattwynne summarised it well a few years ago: http://blog.mattwynne.net/2010/10/22/features-user-stories/comment-page-1/

[jfinkhaeuser]

Taking this blog post, I read:

User Stories are a planning tool. They exist until they’re implemented, and then they disappear, absorbed into the code.

The understanding we're sharing is that feature files should contain a description of the software as-is, not about its history. Fair enough.

Quoting the article linked in what Matt's post, http://dannorth.net/whats-in-a-story/ , we get this:

This, then, is the role of a Story. It has to be a description of a requirement and its business benefit, and a set of criteria by which we all agree that it is “done”.

There's a question that arises from Matt's post, and that remains somewhat unanswered, and that is how feature files can be used to document what shouldn't work. That's still part of the specifications, of "how the system behaves today". To take the example, if BarCorp's cards are just never to be accepted, that fact also needs to be documented.

I get the impression that Matt focuses exclusively on the "it is done" part to call stories a planning tool, and perhaps echoes the developer mentality here; every PMO and QA person I've met to date focuses (almost) exclusively on the "requirements and benefits" part.

In other words, I honestly think you're doing feature files as a team communications tool a disservice by presenting user stories in the way you do here.

@enkessler Yes, highlighting can be the IDEs task, but if the Gherkin parser understands something, cucumber can better agree with every IDE about what is and isn't part of the specs. Still, it's a nice to have, not a big thing.

[mattwynne]

In other words, I honestly think you're doing feature files as a team communications tool a disservice by presenting user stories in the way you do here.

@jfinkhaeuser I'm confused. Can you articulate more about what you mean?

[jfinkhaeuser]

It's part of team communications to find common terminology.

I currently suspect - I may be wrong - that your use of "feature != story" comes from focusing on the "done" part of user stories, which lets you interpret them as primarily a planning tool. I know from experience that most developers think that way.

I also know from experience that QA and PMOs don't typically focus on the "done" part, and focus more on the "requirements and benefits" part of user stories (in that order, i.e. QA on "requirements" and PMOs on "benefits").

Therefore if a user story is a planning tool for some team members, and a documentation tool for others, cucumber/gherkin does not help team communications by emphasizing only one interpretation.

My naive approach was to split feature and story in the way described above, but there might well be much better alternatives.

[jfinkhaeuser]

As a general rule and corollary to my previous comment, it doesn't typically help for one term to mean different things to different people. Usually it's better to find two or more related terms and have everybody understand their relation to each other. That's what this is all about.

[mattwynne]

it doesn't typically help for one term to mean different things to different people

Absolutely! The word "requirements" to me means "business rules". Is that what it means to you too?

[mattwynne]

I've gotta also say that:

I've seen mentioned in many best practice documentations that the feature description should be in the form of a "As a role/In order to achieve benefit/I want goal/desire" triplet, i.e. a classical user story.

I totally disagree with that practice, and I always tell people to be more imaginative and expansive with their feature descriptions where possible. You'll find very few of them in Cucumber's own feature documentation, for example.

[jfinkhaeuser]

Regarding "requirements": I was quoting the Dan North blog post, but yes, requirements as meaning business rules sounds almost right to me.

One minor issue I have with this is that some necessary details can get lost in this.

For example, I often see PMOs define business rules as relatively fuzzy from an engineering perspective, for example "invalid email addresses must not be accepted".

It's then in the QA realm to extract from these fuzzy business rules hard acceptance criteria, such as listing all the email examples that must work, and those that must not work.

In terms of test automation - not in terms of BDD as such - it makes sense to encapsulate the acceptance criteria in test scenarios; from a pure business rules point of view, that might be too much detail.

Realistically speaking, it's much more likely for a QA engineer to be a cucumber practitioner than it is for a PMO, so there's going to be some friction about how much detail should be in a requirement - more business rule or more acceptance criteria.

Still, that's a decision dictated so much by intra-team practicalities I don't think cucumber/gherkin can enforce one usage over another. I do lean towards one or the other depending on whether I put on my PMO or QA hat :)

[jfinkhaeuser]

Regarding "user story triplets as feature descriptions": I'm not claiming the cucumber team does that, nor do I claim it's best practice. I just see it used that way very often.

The main problem that I see, to quote myself, is this:

Therefore if a user story is a planning tool for some team members, and a documentation tool for others, cucumber/gherkin does not help team communications by emphasizing only one interpretation.

Splitting the feature and story concepts was just the solution that seemed to appeal to teams I've worked with the most. I'd be equally happy about other terminology, and am sure better terminology can be found.

From an implementation point of view, though, I think an optional structure element to subdivide features would be ideal. I'm less in favour of SubFeature as that doesn't quite solve my main problem quoted above.

I hope this is beginning to make some sense by now!

[merrua]

@jfinkhaeuser This was very interesting. I have a question, what about Epics? They are widely used throughout the industry. What is the breakdown between Epic, Feature, Story in this use case? Also could the story be resolved by just tagging sets of feature scenarios? Like @story_storyname

[aslakhellesoy]

@merrua : http://blog.mattwynne.net/2010/10/22/features-user-stories/comment-page-1/

[merrua]

@jfinkhaeuser Is that wrong link copied in? That's the same article one as above? Lots of companies would put the checkout v1 at the story level (through a few scenarios in a feature). Others would put v1, v2, v3 at the epic level. And tagging could be used to express stories or epics depending on the level you add them at. I'm interested in if a particular method becomes more maintainable, or if its more a reflection of each organisations internal structure or culture.

[aslakhellesoy]

@merrua yes it's the same link as above - I forgot I had already pasted it.

An Epic is a planning artefact, just like a story (just bigger). It has no place in feature files. As you suggest yourself, tags is the recommended mechanism for grouping features.

[mattwynne]

A term that Liz Keogh uses instead of "Epic" is "Capability". It means the same thing, but is IMO a much more descriptive name than Epic which essentially just means "big story".

I often advise people to organise their features into sub-directories, each named after a different capability of the system.