Chapter 5. From examples to executable specifications

In the last chapter, you saw a number of techniques to identify and describe valuable features. You also saw how conversations with the stakeholders around concrete examples are a very effective way to build up a common understanding of a problem space. In this chapter, you’ll learn how to express these examples clearly and precisely, in a way that will allow you to transform them into executable specifications and living documentation (see figure 5.1).

The aim of this chapter is to help developers, business analysts, testers, and other interested team members get a solid shared understanding of how to read and write executable specifications in a way that makes it easy to automate them. BDD has a number of well-defined practices to achieve this shared understanding:

5.1. Turning concrete examples into executable scenarios

One of the core concepts behind BDD is the idea that you can express significant concrete examples in a form that’s both readable for stakeholders and executable as part of your automated test suite. You’ll write executable specifications in the native language of your users, and produce test results that report success or failure not in terms of classes and methods, but in terms of the features that the stakeholders requested. Stakeholders will be able to see their own words appear in the living documentation, which does wonders in increasing their confidence that you’ve understood their problems. This is what BDD tools like Cucumber, JBehave, and SpecFlow bring to the table.

This sort of scenario is not only quite readable, it’s also executable: BDD tools like JBehave and Cucumber can read and execute these scenarios to verify your application’s behavior and generate meaningful test reports. These test reports are a central part of the living documentation that will help you understand and maintain the application (see figure 5.3).

5.2. Writing executable scenarios

Scenarios written in this format will make up the core of your executable specifications. But to make them truly executable, you need to integrate them into your projects.

In this section, you’ll see how to do this in both JBehave and Gherkin. Gherkin is the language used by Cucumber and the vast majority of Cucumber-based BDD tools, including SpecFlow (for .NET), Behave (for Python), and many others. JBehave uses a very similar format: there are slight variations between the tools, but I’ll point them out along the way.

5.3. Using tables in scenarios

Scenarios are like application code—you should write with the intention of making readability and maintenance easy. If you’re using your scenarios as living documentation, they’ll outlast the development project by quite a bit, and it’s important to make sure that they’re easy to understand and update in the future.

One way not to do this is to include a lot of duplicated text in your scenarios. In programming, duplication is one of the worst enemies of maintainable code, and the same applies to scenarios. But if you only use the “Given ... When ... Then” notation we’ve discussed so far, it’s sometimes hard to avoid overly wordy scenarios peppered with duplicated text.

5.4. Expressive scenarios: patterns and anti-patterns

Now that you’ve seen the mechanics of writing scenarios in Gherkin and JBehave, it’s time to take things to the next level. In this section we’ll go beyond just seeing how scenarios are structured and written and look at what goes into a good scenario.

5.5. Organizing your scenarios using feature files and tags

In real-world projects, scenarios can become quite numerous, and it’s important to keep them well organized. You may also need to be able to identify and group scenarios in different ways; for example, you might want to distinguish UI-related scenarios from batch-processing scenarios, or identify the scenarios related to cross-functional concerns. In this section, you’ll learn how to organize and group your scenarios to make them easier to understand and maintain.

5.6. Summary

In this chapter you learned about creating executable scenarios:

You’ve now hopefully learned enough to be able to write your own feature definitions, illustrated with concise, expressive scenarios. In the next chapter, you’ll see how to automate and implement this using several different languages and environments.