Specification by Example

Purpose

Specification by Example (SBE) bridges the gap between business intent and working software. By defining requirements as concrete, testable examples before development begins, the team builds shared understanding and produces living documentation that doubles as automated tests.

At a glance

How to run

1. Identify the feature (5 min) — Select a feature or user story to specify.
2. Derive business rules (15 min) — What are the rules that govern this feature? List each as a simple statement.
3. Illustrate with examples (25 min) — For each rule, create concrete examples: Given [context], When [action], Then [outcome]. Include happy paths, edge cases, and error scenarios.
4. Refine examples (10 min) — Remove redundant examples. Ensure each example tests exactly one rule.
5. Agree on automation (5 min) — Decide which examples will become automated acceptance tests and in what framework (Cucumber, SpecFlow, FitNesse).

Materials needed

• Feature or user story description
• Given-When-Then template
• Shared document or specification tool
• Examples from past features as reference

Pitfalls & common mistakes

• Examples too abstract — Use concrete data ("John deposits $100") not vague placeholders ("a user deposits money").
• Too many examples — Each rule needs 2–4 examples, not 20. Redundant examples add maintenance cost.
• No automation — Examples that stay in documents rot quickly. Automate them.
• Only testers participate — The value comes from the three-amigos conversation: business, dev, and test.

Inclusion & accessibility

• Write examples in plain business language, not code.
• Share the feature description in advance.
• Allow non-technical participants to propose examples in their own words.

Variations

• Example Mapping — Use coloured cards to structure the conversation (see ag_example_mapping).
• BDD workshops — Behaviour-Driven Development sessions focused on writing Gherkin scenarios.
• Living documentation — Generate documentation from automated examples.

When NOT to use this

• For exploratory or spike work where the outcome is uncertain.
• If the team has no automated test infrastructure — set that up first.

Source & further reading

• Adzic, G. (2011). *Specification by Example*. Manning.
• North, D. (2006). "Introducing BDD." dannorth.net