Specification by example

Specification by example (SbE) replaces traditional requirements documents with a set of concrete, executable examples that illustrate system behavior. These examples are written in a natural-language format, often using a Given-When-Then structure, making them understandable by all stakeholders. Each example serves as both a specification and an acceptance test, ensuring that the software meets the intended behavior. The technique was popularized by Gojko Adzic in his 2011 book Specification by Example and builds on earlier work in test-driven development (TDD) and domain-driven design (DDD).¹ By focusing on examples rather than abstract requirements, SbE reduces ambiguity, improves collaboration, and provides a living documentation system that stays up-to-date with the codebase.

The SbE process typically involves five key steps: specification (stakeholders define examples), automation (examples are turned into automated tests), execution (tests run against the system), validation (results are reviewed), and evolution (examples are updated as the system changes). Benefits include fewer misunderstandings, faster feedback loops, and a single source of truth for requirements. Teams using SbE report up to 50% reduction in defects and significantly shorter release cycles.² The technique is especially effective in environments where requirements are volatile or where multiple teams need to align on a shared understanding of system behavior.

While SbE is widely associated with agile, it originated in the lean software development movement and was influenced by the Ward Cunningham’s FIT framework (Framework for Integrated Test). A common misconception is that SbE is synonymous with BDD; in fact, BDD is a specific implementation of SbE principles. Another lesser-known fact is that SbE can be applied to non-functional requirements, such as security or performance, by using examples that describe expected behavior under specific conditions. The technique also helps in regulatory environments where traceability is required, as each example can be linked to a compliance requirement.³ Some teams integrate SbE with model-based testing to generate test scenarios from examples, further extending automation.

Popular tools for SbE include Cucumber (Gherkin language), FitNesse, SpecFlow (.NET), and Robot Framework. These tools parse structured examples and execute them against the application under test. Adoption of SbE has grown steadily, especially in financial services, healthcare, and e-commerce, where clear requirements are critical. The technique is also taught in many university software engineering courses. The Specification by Example community maintains a collection of case studies and best practices. Despite its benefits, SbE requires a cultural shift towards collaboration and may encounter resistance from teams accustomed to traditional requirements documents.

Given-When-Then

A structured format for writing examples in behavior-driven development, used to describe preconditions, actions, and expected outcomes.

Living documentation

Documentation that is automatically updated from executable specifications, ensuring it remains accurate as the code evolves.