"That's all very well, but how do I know that it works?"
"What will that actually look like on screen?"
It can be hard to nail down a feature file. Some people like to argue over the wording of the preamble and jump into the scenario writing (much) later. Some prefer to get on with writing concrete examples to help jumpstart their thinking, and frame the story with the acceptance criteria later.
"So what's the point of this feature again?"
Whichever way we approach writing our feature files, it’s important that we iterate over our wording. Let’s not neglect either our acceptance criteria, or scenarios detailing concrete example behaviour. Without both, we’re making it hard for our developers to implement a feature, and making it hard for us to understand its purpose a few months down the line.
"Can you give me an example of that?"
It’s very easy to conflate the concept of scenarios with acceptance criteria: they aren’t the same thing. Scenarios are concrete examples of acceptance critera: they help flesh out and explore complex criteria, and ground them in reality. Without concrete examples it can be hard to get a handle on where to start when implementing a feature, and it’s difficult to wrap our minds around what needs to be done.
Lack of acceptance criteria: hesitation and confusion
Here’s a feature without acceptance criteria:
When we skip the acceptance criteria and jump straight into examples, we lose context. It’s hard to see how and why this feature exists, and who is using it?
Example scenarios aren’t good at describing design and user experience constraints on a feature. Developers will be tempted to rush straight through the implementation without paying attention to the detail. They’re also no good at communicating the need for other edge cases. Is there something else that we’ve missed here? What about distinguising between biological and adoptive parents, for instance? Or checks for age to ensure the father could be old enough to have children?
Lack of concrete example scenarios: haziness and obfuscation
We might be tempted to shoe-horn all that information into the scenario:
This isn’t a real scenario any more. We’re trying to describe several different things in one place. It could be implemented as several different scenarios joined together, but by itself the lack of concreteness means that we can’t easily reason about it, and it’s also nigh on impossible to automate without skipping some of the intent. Using ‘Given’, ‘When’ and ‘Then’ does not automatically make something a concrete example - all this information belongs in the preamble.
Combining acceptance criteria with real examples
Let’s try and combine both these techniques:
Have a look at the acceptance criteria as listed in the preamble. They state both the reason for the story and they flesh out some more of the thinking. You can often leave the feature like this up until the point I want to work it, with criteria in bullet form. If the feature is complex and there’s a danger information will be lost, I’d recommend writing down examples during the planning of the story in order to properly capture the behaviour (like I’ve done here with the second scenario), but you don’t need to do this for every scenario until you come to automate it.
Think back on what you have just read. This post would have been hard to understand without the two examples above. Without concrete examples, it’s very easy to gloss over content.
Alternatively, if this post had just consisted of the two features above, followed by “Don’t do this! Any comments?”, our natural reaction would have been one of confusion. Don’t do what exactly? And what exactly should we do instead?
Just like a blog post without an example, or a teaching workshop without a practical element, if there’s no concrete example then acceptance criteria can lead to wishy-washing thinking. Similarly, if we just sit down and start working on something concrete without any clear context, we’ll struggle to see the reasons for doing it and we’ll miss edge cases. When you have both, that’s when you know you’ll understand.
Personally, I tend to the second error: because I can read code, I sometimes fall into the trap of not making my examples concrete enough. Which of these two do you more tend towards?
For more, see Liz Keogh’s post on this topic from last year. For a slightly different point of view, check out Antony Marcano’s thoughts on scenario oriented acceptance criteria. Antony argues for using scenario titles as our list of criteria. I find it helpful to keep Scenario titles and Acceptance Criteria separate, as I don’t think there is always a clear mapping between the two. One is an evolution of the other, and it’s useful even when the scenario titles are written to keep the Acceptance Criteria around for context. What do you think?