[Best Practice] Naming Cucumber Scenarios

[QA Collective]

Hello all,

As this is my first post to this forum, G'day from Australia - my name is Andrew.  

I'm currently QA manager of a small team in an agile project that is standing up a completely new solution and to build it, a completely new tool set.

As a project that will have far-reaching impact across an entire government (wide & diverse business audience), I have decided that Cucumber is the best choice when it comes to building a common language to talk about how our solution should behave in fulfilling requirements, and simultaneously automating to reap the full benefits of BDD and eventually, CI.

We are currently in the process of writing up many scenarios from some pre-existing waterfall style Requirements Specifications documents.  I see it as good practice before we have to do this in concert with business people.  Each of my team have read the Cucumber book and we are all aspiring to best practice in the way we write them (concise, incremental, declarative, layered abstraction).

We have a question about best practice in naming scenarios and have turned to guidance in The Cucumber Book, but have interpreted a key sentence differently.  

On pp 34, in a 'Matt says' caption, the final paragraph states:

"A good tip is to avoid putting anything about the outcome (the Then part) of the scenario

into the name and concentrate on summarizing the context and event (Given and When)

of the scenario."

I have interpreted this to mean that the scenario name can include a summary of intended outcome ("Successful payment"=GOOD) but not the details of that outcome ("Payment success message and confirmation email"=BAD).

My colleague has interpreted this to mean that the scenario name should not include any intended outcome ("Successful payment"=BAD) and only include context ("Submit valid payment details"=GOOD).

My argument is that expressing intended outcome is concise, understandable by business and helps 'roll-up' (i.e. can read scenario names without having to read steps).  Perhaps it is not very 'future proof' when things get more complex?

My colleagues argument is that he accepts Matt's advice verbatim and that from reading the scenario, one can assume that "Submit valid payment details" will result in a successful payment.

Which title would people here say is 'best practice', or are we splitting hairs?

Full example (steps are identical):

Scenario: Successful payment

Given I have progressed to payment

And I have entered valid payment details

When I submit payment

Then I see a success message

And I see a new message in my mailbox

Scenario: Submit valid payment details

Given I have progressed to payment

And I have entered valid payment details

When I submit payment

Then I see a success message

And I see a new message in my mailbox

Thanks in advance for all your advice!

Andrew

[Andrew Premdas]

You are splitting hairs a bit here, but thats not neccessarily a bad thing. I wrote this http://pages.andrew.premdas.org/2011/11/18/consistency-in-features.html a very long time ago which has something to say about naming scenarios and seeing them in a wider context.

In this particular case I think I prefer your colleague's scenario because it gives greater scope to write some sad path scenarios that share the same context e.g.

submit valid payment details

submit valid payment details card fails
...

Personally I think you can make the scenario simpler and a bit more expressive by combining the last two steps into something like

Then my purchase should complete

And in the sad paths you can have a different then e.g. Then my purchase should fail card validation

You should define what happens when a purchase completes somewhere else. When you have two steps for your then and you have many scenarios that need to have both steps you are probably hiding a piece of behaviour that needs naming 'purchase completion' and in this case probably its own feature. You really want to define what happens when you complete a purchase (in this case the details of how you communicate with you customer in just one place) rather than repeat it in many scenarios. (consider what happens if say you decide to send a text as well).

There isn't a best practice here. There are tips that can be usefully applied to improve things. One thing about features and scenarios is that they are dynamic things and need to change and evolve as you learn more about your application from the behaviour you create and the thought you put into your problem space. So be careful about trying to get lots of features written and defining all your behaviour without having any actual behaviour. And be careful about casting your application in stone that  is not the way to do Agile.

Good luck

Andrew

--
Posting rules: http://cukes.info/posting-rules.html
---
You received this message because you are subscribed to the Google Groups "Cukes" group.
To unsubscribe from this group and stop receiving emails from it, send an email to cukes+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--

------------------------

Andrew Premdas

blog.andrew.premdas.org

[Eric Kessler]

On Thursday, November 17, 2016 at 1:14:24 AM UTC-5, QA Collective wrote:

<snip>

 

We have a question about best practice in naming scenarios and have turned to guidance in The Cucumber Book, but have interpreted a key sentence differently.  

On pp 34, in a 'Matt says' caption, the final paragraph states:

"A good tip is to avoid putting anything about the outcome (the Then part) of the scenario

into the name and concentrate on summarizing the context and event (Given and When)

of the scenario."

 <snip> 

 

Which title would people here say is 'best practice', or are we splitting hairs?

Full example (steps are identical):

Scenario: Successful payment

Given I have progressed to payment

And I have entered valid payment details

When I submit payment

Then I see a success message

And I see a new message in my mailbox

Scenario: Submit valid payment details

Given I have progressed to payment

And I have entered valid payment details

When I submit payment

Then I see a success message

And I see a new message in my mailbox

I don't see either one of those titles as violating Matt's advice because they both describe only the Action portion of your use case.

My argument is that expressing intended outcome is concise, understandable by business and helps 'roll-up' (i.e. can read scenario names without having to read steps)

I'd argue that you want your readers to have to read the steps in order to see the outcome. If you provide too many details, your readers' brains will still be in 'glossing over this' mode by the time that they find the information that they actually care about.

Think of your test suite as a library. Your different file folders are different shelves, your feature files are individual books, and your scenarios are chapters in a given book. Enable your readers to find what they are looking for by having good organization, not by putting spoilers in the table of contents. ;)

Eric K

[George Dinwiddie]

Andrew,

For scenario names, I prefer to think of the feature files in terms of
documentation rather than tests. A few years from now, when you or
someone else is looking to understand the current system, what will you
(or they) be looking for.

When I look at it this way, Matt's advice is a good starting point.

For example, I would be unlikely to be searching for "successful
payment" and "failed payment." In fact, there are likely to be multiple
reasons for "failed payment."

I'm far more likely to look for descriptions of the different
significant conditions, to see how each is handled.

Scenario: valid payment details
Scenario: invalid card number
Scenario: missing CVV number
Scenario: mismatch between name and card
Scenario: payment processor declines
Scenario: payment processor fails to reply
Scenario: payment processor technical error

The name of the scenario is sufficient to know that the situation has
been considered. It's better to read the scenario to know the outcome
that is expected. Putting the outcome in the title leads to unwarranted
assumptions and, over time, obsolete statements.

- George

On 11/16/16 8:40 PM, QA Collective wrote:
> Hello all,
>
> As this is my first post to this forum, G'day from Australia - my name
> is Andrew.
>
> I'm currently QA manager of a small team in an agile project that is
> standing up a completely new solution and to build it, a completely new
> tool set.
>
> As a project that will have far-reaching impact across an entire
> government (wide & diverse business audience), I have decided that
> Cucumber is the best choice when it comes to building a common language
> to talk about how our solution should behave in fulfilling requirements,
> and simultaneously automating to reap the full benefits of BDD and
> eventually, CI.
>
> We are currently in the process of writing up many scenarios from some
> pre-existing waterfall style Requirements Specifications documents. I
> see it as good practice before we have to do this in concert with
> business people. Each of my team have read the Cucumber book and we are
> all aspiring to best practice in the way we write them (concise,
> incremental, declarative, layered abstraction).
>
> We have a question about best practice in naming scenarios and have
> turned to guidance in The Cucumber Book, but have interpreted a key
> sentence differently.
>
> On pp 34, in a 'Matt says' caption, the final paragraph states:

> /
> /
> /"A good tip is to avoid putting anything about the outcome (the Then
> part) of the scenario/
> /into the name and concentrate on summarizing the context and event
> (Given and When)/
> /of the scenario."/
> /
> /

> I have interpreted this to mean that the scenario name can include a
> summary of intended outcome ("Successful payment"=GOOD) but not the
> details of that outcome ("Payment success message and confirmation
> email"=BAD).
> My colleague has interpreted this to mean that the scenario name should

> not include *any* intended outcome ("Successful payment"=BAD) and *only*

> include context ("Submit valid payment details"=GOOD).
>
> My argument is that expressing intended outcome is concise,
> understandable by business and helps 'roll-up' (i.e. can read scenario
> names without having to read steps). Perhaps it is not very 'future
> proof' when things get more complex?
>
> My colleagues argument is that he accepts Matt's advice verbatim and

> that from reading the scenario, one can /assume/ that "Submit valid

> payment details" will result in a successful payment.
>
> Which title would people here say is 'best practice', or are we
> splitting hairs?
>
> Full example (steps are identical):
>

> *Scenario: Successful payment*
>
> /Given I have progressed to payment/
> /And I have entered valid payment details/
> /When I submit payment/
> /Then I see a success message/
> /And I see a new message in my mailbox/
> *
> *
> *Scenario: Submit valid payment details*
>
> /Given I have progressed to payment/
> /And I have entered valid payment details/
> /When I submit payment/
> /Then I see a success message/
> /And I see a new message in my mailbox/

>
> Thanks in advance for all your advice!
>
> Andrew
>

> --
> Posting rules: http://cukes.info/posting-rules.html
> ---
> You received this message because you are subscribed to the Google
> Groups "Cukes" group.
> To unsubscribe from this group and stop receiving emails from it, send

> an email to cukes+un...@googlegroups.com
> <mailto:cukes+un...@googlegroups.com>.

> For more options, visit https://groups.google.com/d/optout.

--

----------------------------------------------------------------------
* George Dinwiddie * http://blog.gdinwiddie.com
Software Development http://www.idiacomputing.com
Consultant and Coach http://www.agilemaryland.org
----------------------------------------------------------------------

[QA Collective]

Hello all,

Thank-you kindly for your considered replies.  Perhaps George's reply was the last because he articulated it so succinctly in a way that tactfully reminds us that simple and effective documentation is timeless, so this should be the objective rather than too much focus on specific syntax beyond what Cucumber provides.

I also really liked your examples George, they of course helped illustrate your point far more quickly and relevantly than you could have described it in further detail.  We have already been using our understanding from your response in adjusting existing scenarios and writing our new ones.

Thanks all,

Andrew