Writing Great Specifications
Using Specification by Example and Gherkin
Kamil Nicieja
  • MEAP began May 2016
  • Publication in August 2017 (estimated)
  • ISBN 9781617294105
  • 300 pages (estimated)
  • printed in black & white

Specification by Example is a collaborative approach to defining and illustrating software requirements using concrete examples. Gherkin is a business-readable DSL that you use to describe software's behavior as executable test cases that are easy for non-technical folks to understand. Together, Specification by Example and Gherkin offer programmers, designers, and managers an inclusive environment for clear communication, discovering requirements, and building a documentation system.

Writing Great Specifications is an example-rich tutorial that teaches you how to write good Gherkin specification documents that take advantage of Specification by Example's benefits. The book begins by giving you introductions to Specification by Example and Gherkin as well as the big picture of how they work together. After a crash course in Gherkin, you'll go in-depth learning to write the text layer of executable specifications in Gherkin in a clear, understandable, and concise manner. Non-engineers will learn how to make essential contributions to testing without having to learn to write testing code. Engineers and testers will find it helpful in striking a stronger chord with non-technical audiences through automated specifications.

"I would consider this the missing manual for Gherkin."

~ Craig Smith

"This book is the missing link between abstract treatises on the subject of SBE and technical usage."

~ David Madouros

"From just a sheer reading of 5 chapters I was blown away, and learnt so much about how to make business impact through executable specifications."

~ Dane Balia

Table of Contents detailed table of contents


1 Introduction to Specification by Example and Gherkin

1.1 What's a specification?

1.2 Why do teams need specifications?

1.2.1 Defining acceptance criteria in specifications

1.2.2 Building a ubiquitous language into specifications

1.3 Common specification pitfalls

1.3.1 Over-specification

1.3.2 Hand-offs

1.3.3 Under-documentation

1.3.4 Speci-fiction

1.3.5 Test-inability

1.4 Meet Specification by Example and Gherkin

1.4.1 Key process patterns

1.5 Having conversations that identify business needs

1.5.1 Deriving scope from goals

1.5.2 Illustrating requirements with examples

1.5.3 Specifying collaboratively

1.6 Long-term benefits of automating conversations

1.6.1 Automating tests based on examples

1.6.2 Validating frequently

1.6.3 Living documentation

1.7 Capturing conversations as executable specifications

1.8 Making software that matters

1.9 Summary

2 The specification layer and the automation layer

2.1 The layers of executable specifications

2.1.1 The specification layer

2.1.2 The automation layer

2.2 Writing our first Gherkin scenario

2.2.1 Feature

2.2.2 Scenario

2.2.3 Given

2.2.4 When

2.2.5 Then

2.3 Understanding the structure of steps and scenarios

2.4 Testing different outcomes

2.5 How the automation layer and the specification layer interact

2.5.1 Step definitions

2.5.2 Matching steps with step definitions

2.6 Ending Gherkin's crash course

2.7 Answers to exercises

2.8 Summary

3 Mastering the Given-When-Then template

3.1 Choosing the right style for your Gherkin scenarios

3.1.1 Doing outside-in development with Gherkin

3.1.2 Gathering realistic data

3.1.3 Specifying intentions and outcomes over user interface

3.2 Composing Gherkin scenarios

3.2.1 Starting with a Then

3.2.2 Using only one When per scenario

3.2.3 Specifying prerequisites with Givens

3.2.4 Choosing the right abstraction level

3.3 Telling Gherkin stories with impact

3.3.1 Writing warm-up narratives

3.3.2 Vetting acceptance criteria with examples

3.3.3 Exploring contexts by questioning Givens

3.3.4 Exploring outcomes by questioning Thens

3.4 Answers to exercises

3.5 Summary

4 The basics of Scenario Outlines

4.1 Example

4.2 Using Scenario Outlines

4.2.1 Spotting redundancies in Gherkin scenarios

4.2.2 Refactoring redundant scenarios with Scenario Outlines

4.3 The structure of a Scenario Outline

4.3.1 The Examples table

4.3.2 Parameters

4.3.3 The Scenario Outline keyword

4.4 The advantages of Scenario Outlines

4.4.1 Scenario Outlines make feature files shorter

4.5 Growing and maintaining Scenario Outlines

4.6 The disadvantages of Scenario Outlines

4.7 Summary

5 Choosing examples for Scenario Outlines

5.1 Example

5.2 Writing outside-in Scenario Outlines

5.2.1 Collecting examples for outside-in Scenario Outlines

5.2.2 Writing outside-in Scenario Outlines out of collected examples

5.3 Finding key examples for Scenario Outlines

5.3.1 Domain-specific examples

5.3.2 Counterexamples

5.3.3 Exploratory outcomes

5.3.4 Boomerangs

5.4 Avoiding Scenario Outlines anti-patterns

5.4.1 Typical data type attacks

5.4.2 Simple combinatorial outcomes

5.4.3 Database models

5.4.4 Classes of equivalence

5.5 Answers to exercises

5.6 Summary

6 The life cycle of executable specifications

6.1 End-to-end overview of the process

6.2 Understanding business goals

6.3 Analyzing requirements with examples

6.3.1 Conveying requirements as user stories

6.3.2 Collecting examples

6.3.3 Refining user stories with examples

6.4 Deriving scenarios from examples

6.5 Refining scenarios

6.6 Iterating specifications over time

6.6.1 Validating the specification suite

6.6.2 Evolving the documentation system

6.7 Summary

7 Living documentation

7.1 Living documentation in action

7.2 Writing documentation

7.2.1 Defining important domain concepts

7.2.2 Documenting decisions using briefs

7.3 High-level overview of the documentation process

7.4 Who creates living documentation?

7.4.1 Creating documentation through all-team specification workshops

7.4.2 Creating documentation through the Three Amigos meetings

7.4.3 Creating documentation through individual persons

7.5 Choosing the right audience for your living documentation

7.5.1 Who's a minimally qualified reader?

7.5.2 Finding the perfect MQR in your organization

7.6 Answers to exercises

7.7 Summary

8 Organizing scenarios into a specification suite

8.1 Is organizing scenarios by features a good idea?

8.2 Organizing scenarios by user stories

8.2.1 Introducing the new Ability keyword

8.2.2 Understanding the structure of user stories

8.2.3 Analyzing the relationship between user stories and executable specifications

8.3 What about non-functional requirements?

8.3.1 Dealing with non-functional requirements according to Specification by Example

8.3.2 Can Gherkin specify non-functional requirements?

8.3.3 Introducing the Business Need keyword

8.3.4 Using the Business Need keyword to identify new stakeholders

8.4 Answers to exercises

8.5 Summary

9 Refactoring Features into Abilities and Business Needs

9.1 Analyzing user stories on a practical example

9.2 Refactoring Features into Abilities

9.2.1 Deriving new scenarios from user stories

9.2.2 Starting with simple Features

9.2.3 Adding scenarios over time

9.2.4 Splitting huge Features into small Abilities

9.3 Recognizing and refactoring Business Needs

9.3.1 Adding functional scenarios to Business Needs

9.3.2 Identifying new stakeholders with Business Needs

9.3.3 Refactoring functional scenarios in Business Needs into individual Abilities

9.4 Summary

10 Building a domain-driven specification suite

10.1 Distilling business domains from a ubiquitous language

10.1.1 Spotting different domains in your scenarios

10.1.2 Distilling the core domain from your scenarios

10.1.3 Distilling subdomains accompanying the core domain

10.2 Creating a domain model from distilled domains

10.2.1 The domain model and the specification suite

10.2.2 Why are good domain models important?

10.2.3 What makes a good domain model in software?

10.3 Building a domain-driven specification suite in practice

10.3.1 Distilling subdomains from unequivocal scenarios

10.3.2 Distilling subdomains from mixed scenarios

10.3.3 Distilling subdomains from other scenarios

10.3.4 Creating a specification suite from distilled domains

10.4 Answers to exercises

10.5 Summary

11 Managing large projects with bounded contexts

11.1 Analyzing domain concepts in context

11.1.1 Spotting false cognates

11.1.2 Dealing with false cognates

11.1.3 Spotting duplicate concepts

11.2 Modeling specification suites as bounded contexts

11.2.1 Understanding bounded contexts

11.2.2 Splitting a large specification suite into multiple bounded contexts

11.2.3 Managing bounded contexts with context maps

11.2.4 Drawing context maps

11.3 Fitting DDD into a Specification by Example process

11.4 Summary


Appendix A: A Executing specifications with Cucumber

A.1 Configuring the environment

A.2 Preparing scenarios for automation

A.3 Writing the tests in a test-driven manner

A.3.1 Defining prerequisites with Givens

A.3.2 Taking actions with Whens

A.3.3 Testing consequences with Thens

A.4 Writing implementation code based on tests

A.5 Executing the working specification

A.6 Executing Scenario Outlines

A.7 Testing systems end-to-end with Capybara

A.8 Summary

What's inside

  • Writing Gherkin specification documents
  • Using good practices to refactor Gherkin documents in legacy projects
  • Designing test cases
  • Team Collaboration with Gherkin
  • Managing a suite of multiple Gherkin documents

About the reader

This book is a teaching resource for product and design people, programmers and testers.

About the author

Kamil Nicieja began his career as an engineer, then moved to product management. He is now running his own startup. Because of Kamil's experience, he knows Specification by Example's benefits, both in development and in business.

Manning Early Access Program (MEAP) Read chapters as they are written, get the finished eBook as soon as it’s ready, and receive the pBook long before it's in bookstores.
MEAP combo $44.99 pBook + eBook + liveBook
MEAP eBook $35.99 pdf + ePub + kindle + liveBook

FREE domestic shipping on three or more pBooks