6 From examples to executable specifications

In the last chapter, you saw how conversations with the stakeholders around business rules and 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 6.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:

6.1 Turning concrete examples into executable scenarios

6.2 Writing executable scenarios

6.2.1 A feature file has a title and a description

6.2.2 Describing the scenarios

6.2.3 The “Given ... When ... Then” structure

6.2.4 Ands and buts

6.2.5 Comments

6.3 Using tables in scenarios

6.3.1 Using tables in individual steps

6.3.2 Using tables of examples

6.3.3 Pending scenarios

6.4 Organizing your scenarios using feature files and tags

6.4.1 The scenarios go in a feature file

6.4.2 A feature file can contain one or more scenarios

6.4.3 Organizing the feature files

6.4.4 Using a flat directory structure

6.4.5 Organizing feature files by stories or product increments

6.4.6 Organizing feature files by functionality and capability

6.4.7 Annotating your scenarios with tags

6.4.8 Provide background and context to avoid duplication

6.5 Rules and Examples

6.6 Expressive scenarios: patterns and anti-patterns

6.6.1 The art of Good Gherkin

6.6.2 What does bad Gherkin look like

6.6.3 Good scenarios are declarative, not imperative

6.6.4 Good scenarios do one thing, and one thing well

6.6.5 Good scenarios have meaningful actors

6.6.6 Good scenarios focus on the essential and hide the incidental

6.6.7 Gherkin scenarios are not test scripts