For the next challenge, we’ll look at how to create good scenario titles. Instead of asking you to submit full solutions, we’d like you to vote for one of the proposed titles.
Here’s an example scenario outline dealing with choosing a shipping method for an order, based on its price.
Given a user orders an item of USD When the order is dispatched Then the selected shipping method should be | cost | shipping | | 1 | post | | 10 | post | | 49.99 | post | | 50 | courier | | 100 | courier |
Scenario Outline: Item shipping
Scenario Outline: Choose shipping depending on order price
Scenario Outline: Expensive items should use secure shipping
Scenario Outline: Items over 50 USD should use couriers, not regular post
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.
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:
Here are some of the reasons in the first group:
Here are some of the reasons from the second group:
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.
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:
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.
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.
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.
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.
“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.
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.