Catalog
concept#Software engineering#Product management#Delivery#Quality assurance

Specification by Example

A collaborative method to specify requirements via concrete examples and turn them into automatable acceptance tests.

Specification by Example is a collaborative technique for defining requirements using concrete examples that become accurate, automatable acceptance tests.
Established
Medium

Classification

  • Medium
  • Organizational
  • Organizational
  • Intermediate

Technical context

CI/CD (e.g. Jenkins, GitHub Actions)BDD tools (e.g. Cucumber, SpecFlow)ALM/issue tracker (e.g. Jira)

Principles & goals

Examples replace unclear textual requirements.Living documentation must stay in sync with implementation.Tests are living communication artifacts between domain and engineering.
Build
Domain, Team

Use cases & scenarios

Compromises

  • Examples become detached from implementation and get stale.
  • Excessive detail leads to fragile test code.
  • Poor workshop facilitation generates irrelevant scenarios.
  • Focus on business‑relevant examples rather than technical details.
  • Keep examples readable and understandable for business readers.
  • Isolate automation logic from domain example text.

I/O & resources

  • Business goals and user needs
  • Preliminary user stories or features
  • Domain experts and developers in the workshop
  • Explicit examples with acceptance criteria
  • Automated acceptance tests in CI
  • Living documentation as reference

Description

Specification by Example is a collaborative technique for defining requirements using concrete examples that become accurate, automatable acceptance tests. Teams create realistic scenarios, remove ambiguities and produce executable specifications. It fosters shared domain models and reduces rework.

✔

  • Improved communication between business and development.
  • Early, reproducible feedback via automated acceptance tests.
  • Reduced implementation errors and less rework.

✖

  • Requires discipline to maintain and synchronise examples.
  • High initial effort in complex domains.
  • Not all non‑functional requirements can be expressed via examples.

  • Acceptance test coverage

    Percentage of critical requirement examples that are executed automatically.

  • Cycle time requirements→test

    Time from first draft of an example to successful test execution in CI.

  • Bug reproducibility

    Share of reported bugs that can be reproduced via an example.

E-commerce checkout scenarios

Examples describe payment options, multiple items and discounts as executable tests.

Booking flow for travel platform

Scenarios model seat availability, cancellations and pricing rules.

User registration with validation rules

Concrete examples clarify field validation, email verification and error behaviour.

1

Bring stakeholders and developers together for example workshops.

2

Identify core scenarios and formulate them in Given‑When‑Then.

3

Move examples into a testable artifact in a repository.

4

Implement automation adapters to make examples executable.

5

Configure CI pipeline to execute the acceptance suite.

6

Establish regular reviews and maintenance intervals for living documentation.

⚠️ Technical debt & bottlenecks

  • Large collection of stale examples without a cleanup plan.
  • Ad‑hoc test adapters that are not reusable.
  • Monolithic test suites that force long run times.
lack of domain expertiseimmature test infrastructurepoor workshop facilitation
  • Using examples to document implementation details rather than requirements.
  • Writing every tiny behaviour as a separate example.
  • Relying solely on examples for legal requirements.
  • Unclear ownership for maintaining examples.
  • Tight coupling of tests to fragile UI elements.
  • Lack of metrics to measure value.
Domain knowledge and domain modellingFacilitating workshops and creating examplesTest automation and CI integration
Traceability between requirements and implementationTest automation and CI integrationDomain‑driven modelling and ubiquitous language
  • • Time budget for workshops is limited.
  • • Legacy systems hinder automated verification.
  • • Legal requirements may constrain example design.