Specification by Example
A collaborative approach to defining software requirements using concrete examples that serve as both living documentation and automated tests.
Also known as: SBE, Example-Driven Development, Executable Specifications
Category: Techniques
Tags: agile, requirements, testing, software-development, documentation
Explanation
Specification by Example (SBE) is a collaborative approach to software development where requirements, tests, and documentation are defined through concrete, real-world examples rather than abstract statements. These examples serve triple duty: they specify what the system should do, they form the basis of automated tests, and they become living documentation that stays synchronized with the code.
**Core idea:**
Instead of writing abstract requirements like "the system should handle discounts correctly," SBE uses concrete examples:
| Cart Total | Discount Type | Expected Total |
|------------|--------------|----------------|
| $100 | 10% off | $90 |
| $50 | $10 coupon | $40 |
| $30 | 10% off + $5 coupon | $22 |
These examples are unambiguous, testable, and immediately reveal edge cases (what about combining discounts? what if discount exceeds total?).
**The SBE process:**
1. **Derive scope from goals**: Start with business goals, not solution features
2. **Specify collaboratively**: Business, development, and testing work together (Three Amigos) to define examples
3. **Illustrate with examples**: Use concrete scenarios instead of abstract specifications
4. **Refine the specification**: Remove ambiguity, add edge cases, simplify
5. **Automate literally**: Turn examples directly into automated tests using BDD tools (Cucumber, SpecFlow, FitNesse)
6. **Validate frequently**: Run automated examples as part of CI/CD to ensure the system matches the specification
7. **Evolve living documentation**: As the system changes, update the examples to maintain a single source of truth
**Key principles:**
- **Examples over abstractions**: Concrete scenarios communicate more clearly than general statements
- **Collaboration over handoffs**: Specifications emerge from conversation, not documents thrown over walls
- **Living documentation over static docs**: Automated examples never go stale because failing tests catch discrepancies
- **Just enough, just in time**: Specify in detail only what you are about to build
**Benefits:**
- Eliminates ambiguity in requirements
- Catches misunderstandings before coding starts
- Creates a regression test suite as a by-product of requirements definition
- Documentation stays current automatically
- Reduces the gap between what was specified and what was built
**Relationship to BDD:**
SBE and BDD are closely related. BDD provides the Given-When-Then format and tooling for automating examples. SBE provides the broader methodology for how to use examples to drive the entire development process. SBE is the "what and why"; BDD is often the "how."
Related Concepts
← Back to all concepts