Writing Great Specifications
Using Specification by Example and Gherkin
Kamil Nicieja
  • MEAP began May 2016
  • Publication in Summer 2017 (estimated)
  • ISBN 9781617294105
  • 250 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.

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 the ubiquitous language in specifications

1.3. Common specification pitfalls

1.3.1. Analysis paralysis

1.3.2. Rejection of documentation

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 text layer and the automation layer

2.1. The layers of executable specifications

2.1.1. The text layer

2.1.2. The automation layer

2.2. Writing our first Gherkin scenario

2.3. Understanding the structure of steps and scenarios

2.4. Testing different outcomes

2.5. How the automation layer and the text layer interact

2.5.1. Step definitions

2.5.2. Matching steps with step definitions

2.6. Ending Gherkin's crash course

2.7. Summary

2.8. Exercises

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

3.5. Exercises

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.4.2. Scenario Outlines organize feature files by high-level business rules

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 good 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. Summary

5.6. Exercises

6. The life cycle of executable specifications

6.1. End-to-end overview of the process

6.2. Understanding high-level goals

6.3. Analyzing scope through examples

6.3.1. Writing a user story

6.3.2. Generating examples and acceptance criteria

6.3.3. Refining the scope of user stories with examples

6.4. Deriving scenarios from examples

6.5. Implementing the specification and refining key examples

6.6. Iterating executable specifications over time

6.6.1. Validating frequently to keep the specification suite consistent

6.6.2. Evolving the living documentation system

6.7. Summary

7. Living documentation

7.1. Seeing 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.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. Summary

7.7. Exercises

8. Organizing scenarios into specifications

8.1. Organizing scenarios

8.1.1. Organizing scenarios by features

8.1.2. Organizing scenarios by user stories

8.1.3. Organizing scenarios by requirements

8.2. Using functional requirements to organize scenarios

8.2.1. The Ability keyword

8.2.2. Choosing the granularity level for your specifications

8.3. What about non-functional requirements?

8.3.1. Non-functional requirements and Specification by Example

8.3.2. Non-functional requirements and Gherkin

8.3.3. Using the Business Need keyword to identify new stakeholders

8.4. Summary

8.5. Exercises

8.5.1. Rewrite the Feature line from listing 8.6 into an Ability with a clear outcome and a stakeholder.

8.5.2. Can you identify more non-functional requirements?

8.5.3. Think of some other examples of behavioral functions that could be derived from non-functional requirements. You can use the requirements you came up with in the previous exercise.

8.5.4. Add a two-factor authentication scenario as another quality measure to the Business Need for security.

8.5.5. Split the Business Need for security into two Abilities: one for having secure passwords, one for two-factor authentication.

9. Domain design in a specification suite

9.1. Distilling business domains from the ubiquitous language

9.1.1. Spotting different domains in your scenarios

9.1.2. Distilling the core domain from your scenarios

9.1.3. Distilling subdomains from your scenarios

9.2. Creating a domain model from distilled domains

9.2.1. The domain model and the specification suite

9.2.2. Why are good domain models important?

9.2.3. What makes a good domain model in software?

9.3. Modeling specification suites within bounded contexts

9.3.1. Translating domain concepts between bounded contexts

9.3.2. Integrating bounded contexts as unified models

9.4. Working with multiple specification suites through context maps

9.4.1. What is a context map?

9.4.2. Drawing context maps

9.5. The high-level overview of the domain modeling process

9.6. Exercises

9.7. 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
MEAP eBook $35.99 pdf + ePub + kindle

FREE domestic shipping on three or more pBooks