How to name your scenario? Write a good scenario title.

You voted for one of the proposed scenario titles. This article shows the results, an analysis of the votes, and some general ideas on how to create good scenario titles.

And the winner is…

Out of the five choices, the clear winner is “Choose shipping depending on order price”. The second most popular one was “Expensive items should use secure shipping”. Perhaps surprisingly, the reasons why people selected those two seem to be very similar. In general, the explanations fit into two groups:

1. expressing the purpose of the examples that follow, and
2. being resilient to change

Here are some of the reasons in the first group:

• It describes the scenario purpose.
• Expresses the intent of the scenario, rather then the implementation details.
• Expresses a purpose for the difference in shipping method.
• It seems like this is domain reason behind scenario.
• It explains the general reasoning behind the examples.
• Subject matter experts could easily recognise whether that intent is the essence of the scenario or not.
• It describes the functionality broadly yet with enough detail to understand the specific variables.

Here are some of the reasons from the second group:

• If the rules change then the title remains the same and the when/then is the only thing that changes.
• The threshold value could change, or the selected ‘secure’ transport could change, without the intent being different.
• It doesn’t tell you exactly what expensive means, so when the amount changes the title won’t
• It expresses a rule, it focuses on an outcome that is of value to the user, but isn’t so reliant on the implementation detail as the courier based title.

People voting for the first option (“Item Shipping”) have not provided any explanations. Several people who voted for the fourth option (“Items over 50 USD should use couriers, not regular post”) liked it because it was concrete and testable.

The single vote for the “Other” option suggested using a unique identifier from the work tracking system.

So, what makes a good scenario title?

Discarding the less popular options, let’s focus on the top two. Deciding between good or bad is, of course, a very contextual question. Picking a good title also depends on personal preferences. However, I believe that the titles similar to “Choose shipping depending on order price” are often more useful than the ones like “Expensive items should use secure shipping”.

The big difference between them is that the former does not provide a specific outcome, but talks about a more general intent. The latter explains a specific outcome that helps to fulfil that intent. Philip W summarised this point nicely when explaining his vote:

Item shipping is too vague. The others are expected outcomes, not the business scenario. You could compare it to the expected outcome of “The computer’s screen should turn on” but really the scenario you are testing is “Boot up the computer”.

A more general title provides scope for a better discussion. If we’re thinking about “boot up the computer”, we might discuss cases when the screen should not turn on. If we’re just focusing on “the screen should turn on”, we might miss some important boundaries. Of course, if a title is too generic then it stops being useful, since the scope of the discussion will be too broad. Good titles need to balance this need for a wider scope and enough specificity to provide a frame for a good discussion. But this is just one aspect of good titles. Useful titles can be help in several situations:

1. From an analysis perspective, a title sets the scope for a discussion, and helps people decide if they have enough examples or if important boundaries still need to be investigated.
2. From a documentation perspective, a title helps to identify if some content is relevant. People looking for information should be able to quickly decide if they need to keep reading the section below a title or skip it. They should also be able to find relevant scenarios quickly based on keywords in titles.
3. From a testing perspective, looking at the titles should provide a good overview of the coverage for tests that succeeded, or identify problem areas for tests that failed. People should not have to read and understand individual examples for this.

For all those purposes, listing specific outcomes is less useful than providing general intent. Of course, there are exceptions. One notable situation is if it would be difficult to demonstrate the examples for both the cheap and expensive items in the same outline. A potential solution would be to break the set into two separate outlines, each with their own title. “Expensive items should use secure shipping” could be a perfectly nice title for the group containing only examples for expensive items.

This brings us to a potentially useful heuristic for good titles. The most important role for a title is to clearly provide the scope for the contained block of scenarios or examples. This is true both for the feature title and the scenario titles. “Item shipping” is too broad for this specific scenario, but it might fit the scope of the whole feature file nicely.

If all the examples for selecting a shipping method based on price fit into a single scenario outline, I would use the more general title:

Feature: Item shipping

Scenario Outline: Choose shipping depending on order price
...

If there are too many examples for a single outline, but the structure of all the examples is the same, I would probably just split examples into two blocks, each with titles documenting the scope:

Feature: Item shipping

Scenario Outline: Choose shipping depending on order price

Given a user orders an item of  USD
When the order is dispatched
Then the selected shipping method should be 


Examples: Cheap items should be sent with the least expensive method
| cost    | shipping    |
| 1       | post        |
...

Examples: Expensive items should use secure shipping
| cost    | shipping    |
| 50      | courier     |
...

Lastly, if the structure of the examples differ (for example if we need to consider the delivery country for courier selection), I would probably use two different outlines. We could use the Rule keyword to provide a high-level grouping of outlines in this case.

Feature: Item shipping

Rule: Choose shipping depending on order price

Scenario Outline: Cheap items should be sent with the least expensive method

Given a user orders an item of  USD
When the order is dispatched
Then the selected shipping method should be 

Examples: 
| cost    | shipping    |
| 1       | post        |
...

Scenario Outline: Expensive items should use secure shipping

Given a user orders an item of  USD
And the delivery country is 
When the order is dispatched
Then the selected shipping method should be 

Examples: 
| cost    | country | shipping |
| 50      | FR      | DHL      |
...

For some more general guidelines, here are five tips for writing scenario titles.

Set the scope using search keywords

One of the best heuristics to describe scope is to imagine searching for the information in the scenario. What would you type into a search engine? Those keywords can serve as an excellent title, even if they don’t form a grammatically correct sentence.

From that perspective, “item shipping” would be too vague. This scenario is about a specific aspect of item shipping, and looking just for shipping could return too many irrelevant results. Conversely, “Items over 50 USD should use couriers, not regular post” is too specific.

I’d probably throw away the word “Choose”, and keep just “Order shipping based on price”. Or, in fact, add a keyword for the aspect of shipping we’re describing – such as a shipping type or shipping method. So “Shipping method based on price” could work nicely in this case.

Avoid using titles for cross-linking – use tags instead

A large set of feature files works best when it’s good documentation about a system, almost like a book. Books usually have two ways of discovering content. Chapter and section titles usually form a hierarchy, and feature and scenario titles should do the same. The hierarchy helps to organise thoughts in a structured way. But good books also have an index at the back, used to cross-link items and provide an alternative view to the main hierarchy. Feature files should support that way of cross linking as well.

With the guideline to use title as search keywords, people are sometimes tempted to put too much information in a title and overcomplicate it. For example, it might be important to relate scenarios with user stories or work items, especially for teams that use a work item ticketing system.

Resist the urge to add secondary index information into titles, and keep them to the bare minimum that sets the scope. Use tags instead. Check the post on How to fix a chain of dependent scenarios for an example of that trick.

Write the body of the scenario first, then write the title

When people start from the title and then add examples, they sometimes widen or narrow down the scope during the discussions. The examples show the result of the conversations, but the titles rarely get updated.

Delay agreeing on a title until you write the examples. This will allow you to split, merge or rephrase the examples as you see fit, without being constrained by a predefined scope. Once you have a consistent set of examples, decide on the best title for it.

Don’t repeat the data from the examples

“Items over 50 USD should use couriers, not regular post” is a single example, not a valid title for a whole group of scenarios. The examples are there to make things concrete and testable, a title doesn’t need to achieve that level of detail, and it shouldn’t even try. The titles are there to help us see the proverbial forest for the trees.

Repeating the data from the examples is often a sign that the author wanted to write the scenario in a different way, but could not do it because they wanted to reuse existing step definitions. The title then acts a summary, kind of a comment in the style of “this is what I really wanted to say here”. If you spot a case such as that, the right way to clean it up would be to rephrase the examples and make them direct to the point.

Don’t explain the logic in a title – use descriptions instead

Explaining the business reasons behind a rule, clarifying the structure of examples and providing additional context might be important to put somewhere, but scenario titles are not a good place for that. Complicated titles are misleading.

Combine titles with scenario descriptions to provide all that additional information. Check out the post about the rules for good descriptions for some nice examples of that in action.