methodatlas
Method guideAgile

Specification by Example

A practical method guide: clarify prerequisites and materials, understand the complete process, and look up outputs, pitfalls, and stop criteria.

ComplexityMedium
Time60-90 min pro Feature
Participants3-6
FormatWorkshop
MaturityCanonical
Plan Specification by Example
01

Prerequisite

What needs to be finished first

Complete firstSmall business change

The story or rule is small enough for concrete examples.

Oversized scope creates disconnected scenarios and hides rules.
Complete firstThree Amigos

Domain/Product, Development, and Test contribute their perspectives.

Without role diversity, important examples and questions remain hidden.
02

Preparation

What needs to be ready before start

Materials

Story or rule, real cases, four-colour Example Mapping cards, domain vocabulary, feature file, and test access.

People / roles

Product/domain expert · developer · tester · optional facilitator

Pre-read

Select a small change, gather known rules and incidents, and invite a domain decision maker.

Time needed

25–45 minutes of Discovery per small story; Formulation and Automation follow

Setup

Keep story, rules, examples, and questions separate; formulate Gherkin only after shared Discovery.

03

Core question

The one question this method answers

Which concrete examples show that the business rule is correctly, completely, and testably understood?

04

Flow

Phases with goal, actions, output and pitfall

Specification by Example connects Discovery, Formulation, and Automation. Business, development, and test roles clarify rules with realistic examples, express them in domain language, and keep executable specifications aligned with system behaviour.

Rule-example specification

Fictional worked example

Each row connects a business rule to one concrete example and remaining clarification.

Rule-example specification
ExampleBusiness ruleGiven: contextWhen: eventThen: outcomeOpen question or boundary
Cancellation exactly 24 hours beforeBoundary exampleCancellation is free until and including 24 hours before start.Appointment starts 20 June at 10:00; €120 paid.Customer cancels 19 June at 10:00.€120 is refunded in full; confirmation shows €0 fee.Which timezone determines start and cancellation time?

  1. 1. Business rule

    Cancellation exactly 24 hours before
    Cancellation is free until and including 24 hours before start.

  2. 2. Given: context

    Cancellation exactly 24 hours before
    Appointment starts 20 June at 10:00; €120 paid.

  3. 3. When: event

    Cancellation exactly 24 hours before
    Customer cancels 19 June at 10:00.

  4. 4. Then: outcome

    Cancellation exactly 24 hours before
    €120 is refunded in full; confirmation shows €0 fee.

  5. 5. Open question or boundary

    Cancellation exactly 24 hours before
    Which timezone determines start and cancellation time?

One example illustrates one rule. Resolve questions before Formulation or defer them visibly.

Cucumber: Behaviour-Driven Development

  1. 1

    Discover

    Explore rules with examples

    Goal

    Build shared understanding of the rule, boundaries, and open questions.

    Inputs for this step

    • Small story or business change
    • Domain expert, developer, and tester
    • Known rules and incidents

    Actions

    • Name business rules rather than UI steps.
    • Collect typical, boundary, and counter-examples for each rule.
    • Separate unanswered questions and slice scope.

    Output

    Example map

    Rules · examples · questions · scope

    Quality check

    Does each example illustrate one rule?

    Pitfall

    The conversation jumps straight into Gherkin or click paths and hides domain uncertainty. Return to plain-language rules, examples, and expected effects.

    Timing: 20–30 minutes

  2. 2

    Formulate

    Write readable specifications

    Goal

    Express selected examples with context, event, and expected outcome.

    Inputs for this step

    • Example map
    • Shared domain vocabulary
    • Resolved questions

    Actions

    • Name examples by business effect.
    • Given states relevant context, When the event, Then the observable result.
    • Remove irrelevant UI and implementation details.

    Output

    Executable specification

    Rule · Example · Given · When · Then

    Quality check

    Can a domain expert review behaviour without implementation knowledge?

    Pitfall

    Scenarios contain click paths and selectors, so a UI change breaks the business specification. Raise steps to domain actions and observable outcomes.

    Timing: 15–30 minutes

  3. 3

    Automate

    Connect examples to the system

    Goal

    Integrate executable examples as fast, reliable delivery feedback.

    Inputs for this step

    • Agreed specification
    • Test access and data
    • Product code

    Actions

    • Choose an appropriate automation level.
    • Keep test data and step definitions maintainable.
    • See the example fail first, then implement behaviour.

    Output

    Automated examples

    Specification · test binding · result

    Quality check

    Does failure explain a business-relevant reason?

    Pitfall

    Every example is automated through a slow end-to-end UI and becomes brittle. Automate at the lowest level that still expresses the business behaviour.

    Timing: Varies per example

  4. 4

    Maintain

    Keep living specifications current

    Goal

    Synchronise rules, examples, automation, and system behaviour when change occurs.

    Inputs for this step

    • Executable specification
    • Test results
    • New business decisions

    Actions

    • Update examples before implementing a rule change.
    • Remove redundant examples without losing boundaries.
    • Change or delete obsolete specifications with the code.

    Output

    Living documentation

    Current rules · examples · test status

    Quality check

    Does every green example still describe relevant behaviour?

    Pitfall

    Scenarios remain green but explain obsolete rules or implementation details only. Assign rule ownership and review specification with code.

    Timing: Ongoing

05

Artifact

What comes out at the end

Sketch: what the artifact looks like

Specification by Example · Beispiele als SpezifikationStory, Regeln und konkrete Beispiele gemeinsam schärfen und als ausführbare Acceptance Tests in Tabellenform übergeben
Specification by ExampleDas Visual zeigt Story, Regeln, konkrete Given-When-Then-Beispiele, Grenzfälle, Acceptance Tests und offene Fragen.Anforderungen über konkrete Beispiele eindeutig machenBusiness, Test und Engineering formulieren Beispiele so präzise, dass daraus lebende Spezifikation und Acceptance Tests werden.Story / Featurewelches Verhalten soll eindeutigwerden?Regelnfachliche Aussagen als prüfbare SätzeBeispieltabelleGivenWhenThenE1Konto aktivBestellung > LimitFreigabe nötigE2Limit erreichtRabatt steigtWarnung zeigenE3Daten fehlenSendenFehler erklärenAcceptance TestsBeispiele werden ausführbar undbleiben lebende DokumentationOffene Fragenunklare Regeln zurück ins RefinementBeispiele konkret statt ProsaGrenzfälle aktiv suchenfachlich lesbar,technisch prüfbar
Form

Versioned Rule/Example specification with question log, automation binding, and test status.

Versioning / ownership

Retain date, author, source state, and decision status for each revision; do not overwrite earlier results.

Tool alternatives
  • Example Map
  • Gherkin or another executable specification
  • Automation and CI test report

specification-by-example-working-template.md

Plan Specification by Example with real scope, suitable roles, and a clear decision objective.

Specification by Example: Worksheet

Question

To be confirmed

Desired outcome

To be confirmed

Scope

Establish and review the practice Time: 25–45 minutes of Discovery per small story; Formulation and Automation follow

Complete this worksheet on paper or in your own document during the work.

Preparation for this scope

Method setup

  • Materials: Story or rule, real cases, four-colour Example Mapping cards, domain vocabulary, feature file, and test access.
  • Roles: Product/domain expert · developer · tester · optional facilitator
  • Advance information: Select a small change, gather known rules and incidents, and invite a domain decision maker.
  • Overall time needed: 25–45 minutes of Discovery per small story; Formulation and Automation follow
  • Setup: Keep story, rules, examples, and questions separate; formulate Gherkin only after shared Discovery.

Prepare for the work steps

Discover: Explore rules with examples

  • Small story or business change
  • Domain expert, developer, and tester
  • Known rules and incidents

Formulate: Write readable specifications

  • Example map
  • Shared domain vocabulary
  • Resolved questions

Automate: Connect examples to the system

  • Agreed specification
  • Test access and data
  • Product code

Maintain: Keep living specifications current

  • Executable specification
  • Test results
  • New business decisions

Rule-example specification

ExampleRuleInitial contextEventObservable outcomeQuestion · boundary
Cancellation exactly 24 hours before
  • Cancellation exactly 24 hours before: Boundary example

Describe business behaviour; omit UI and implementation detail.

Cucumber: Behaviour-Driven Development

Discover: Explore rules with examples

Expected artifact: Example map

Rules · examples · questions · scope

Entry:

...

  • Does each example illustrate one rule?

Formulate: Write readable specifications

Expected artifact: Executable specification

Rule · Example · Given · When · Then

Entry:

...

  • Can a domain expert review behaviour without implementation knowledge?

Automate: Connect examples to the system

Expected artifact: Automated examples

Specification · test binding · result

Entry:

...

  • Does failure explain a business-relevant reason?

Maintain: Keep living specifications current

Expected artifact: Living documentation

Current rules · examples · test status

Entry:

...

  • Does every green example still describe relevant behaviour?

Open questions and next steps

...

Method guide: https://methodatlas.meierhoff-systems.de/en/methods/specification-by-example/run-sheet

06

Example output

Concrete filled scenario, fictional example

Fictional example for orientation. Counts and timings describe this case and are not universal requirements.

specification-by-example-beispiel.md

Concrete filled scenario, fictional example

Fictional example: rule 'Free cancellation until 24 hours before start'. Example: start 20 June 10:00, cancellation 19 June 09:59, paid €120, expected refund €120. Boundary: cancellation at 19 June 10:00 is also free because it is exactly 24 hours. Question: which timezone applies?

07

Pitfalls

Recognize symptoms and steer against them

Quick overview, the full text is in the matching phase in the flow

  1. Explore rules with examplesThe conversation jumps straight into Gherkin or click paths and hides domain uncertainty.View in phase
  2. Write readable specificationsScenarios contain click paths and selectors, so a UI change breaks the business specification.View in phase
  3. Connect examples to the systemEvery example is automated through a slow end-to-end UI and becomes brittle.View in phase
  4. Keep living specifications currentScenarios remain green but explain obsolete rules or implementation details only.View in phase
08

Stop criteria

When to pause, resolve prerequisites, or choose another approach

Every entry follows the method and links to evidence or explicitly marked uncertainty.
The next decision, owner, and review date are visible where required.

Method after Gojko Adzic. Curated with 1 sources.

Sources: Cucumber: Behaviour-Driven Development

Flow, timeboxes, and pitfalls are editorially curated practice recommendations based on the listed sources.

Where to go next?

Paper illustration of Acceptance Criteria Workshop with a method-specific labelled workspace.
Agile
Acceptance Criteria Workshop

Uses the living specification as the basis for explicit acceptance criteria per story.

Paper illustration of Scrum with its method-specific working model.
Agile
Scrum

Keeps the executable specification as part of the sprint's definition of done.

Finished the method guide?

Go to the profile for purpose, similar methods, and sources or continue to the next method in the catalog.

Go to profileMore methods