Writing Great Specifications
Using Specification by Example and Gherkin
Kamil Nicieja
Foreword by Gojko Adzic
  • October 2017
  • ISBN 9781617294105
  • 304 pages
  • printed in black & white

Does a great job taking concepts from good architectural practices and applying them to the world of collaborative specifications.

From the Foreword by Gojko Adzic, author of Specification by Example

Writing Great Specifications is an example-rich tutorial that teaches you how to write good Gherkin specification documents that take advantage of the benefits of specification by example.

Table of Contents detailed table of contents

Foreword

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.3 Defining important domain concepts

7.3.1 Writing lexical definitions

7.3.2 Writing illustrative definitions

7.3.3 Using glossaries

7.3.4 Naming important domain concepts

7.4 Documenting decisions using briefs

7.4.1 Using warning notes to highlight problematic areas

7.4.2 Using context notes to deepen the business context

7.4.3 Using maintenance notes for internal purposes

7.5 High-level overview of the documentation process

7.6 Who creates living documentation?

7.6.1 Creating documentation through all-team specification workshops

7.6.2 Creating documentation through the Three Amigos meetings

7.6.3 Creating documentation through individual persons

7.7 Choosing the right audience for your living documentation

7.7.1 Who's a minimally qualified reader?

7.7.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

Appendixes

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

About the Technology

The clearest way to communicate a software specification is to provide examples of how it should work. Turning these story-based descriptions into a well-organized dev plan is another matter. Gherkin is a human-friendly, jargon-free language for documenting a suite of examples as an executable specification. It fosters efficient collaboration between business and dev teams, and it's an excellent foundation for the specification by example (SBE) process.

About the book

Writing Great Specifications teaches you how to capture executable software designs in Gherkin following the SBE method. Written for both developers and non-technical team members, this practical book starts with collecting individual feature stories and organizing them into a full, testable spec. You'll learn to choose the best scenarios, write them in a way that anyone can understand, and ensure they can be easily updated by anyone.

What's inside

  • Reading and writing Gherkin
  • Designing story-based test cases
  • Team Collaboration
  • Managing a suite of Gherkin documents

About the reader

Primarily written for developers and architects, this book is accessible to any member of a software design team.

About the author

Kamil Nicieja is a seasoned engineer, architect, and project manager with deep expertise in Gherkin and SBE.


Buy
combo $44.99 pBook + eBook + liveBook
eBook $35.99 pdf + ePub + kindle + liveBook

FREE domestic shipping on three or more pBooks

The missing manual for writing great specifications. I wish this book had existed five years ago!

Craig Smith, Unbound DNA

Will jolt you into best practices, give you fresh perspectives, and reinvigorate your commitment to this business-critical skill.

Dane Balia, Hetzner

The complete book on how to write great specifications. Most of us know bits and pieces, but to truly grok it, you need this excellent guide.

Kumar Unnikrishnan, Thomson Reuters