top of page

Specification by Example: A Hands-On Tutorial

  • Contributor
  • May 1
  • 5 min read

Specification by Example (SBE) is the discipline of using concrete examples to drive shared understanding of requirements. Instead of arguing about abstract requirements, the team builds specific examples of expected behavior together. The examples become the specification, and (ideally) they become executable tests.

This guide is a hands-on tutorial without the heavy tooling.

The Core Idea

Take a requirement: "Discount applies for premium customers."

Abstract discussion produces disagreement about edge cases that no one notices until implementation.

Example-driven discussion:

  • Premium customer, $100 cart → discount applies, total $90

  • Standard customer, $100 cart → no discount, total $100

  • Premium customer, $0 cart → no discount, total $0

  • Premium customer, $1000 cart → discount applies, total $900

  • Newly-upgraded premium customer on existing cart → ?

The last example surfaces an ambiguity. Does the upgrade apply retroactively? When? The team discusses; resolves; updates the examples.

This is the SBE practice: concrete examples surface ambiguity before code is written.

How It Differs From Other Practices

vs. Test-Driven Development: TDD is for engineers; SBE is for cross-role collaboration.

vs. BDD: BDD often refers to specific tools (Cucumber). SBE is the underlying practice; BDD is one implementation.

vs. User stories with acceptance criteria: SBE produces examples that are the criteria. Stories often have abstract criteria; SBE makes them concrete.

The boundaries blur. The core SBE practice — collaborating on examples — works regardless of which framework you nominally use.

The Workflow

A typical SBE flow:

  1. Identify requirements (typically from a user story or feature spec)

  2. Pick scenarios worth examples (happy path, edge cases, negative)

  3. Build examples together (three amigos: PM, dev, QA)

  4. Refine examples until they're unambiguous

  5. Implement the feature

  6. Verify the implementation against the examples

  7. Maintain examples as the feature evolves

The collaborative phase (steps 2-4) is the heart of SBE.

The Three Amigos

The collaboration typically involves three roles:

  • Business (PM, business analyst): captures intent

  • Development (engineer): assesses feasibility and surfaces technical details

  • Testing (QA): considers verification and edge cases

Each brings a different perspective. The conversation among them produces examples that no role alone would have generated.

In smaller teams, one person might wear two hats. The key is that the perspectives are represented, not that there are exactly three people.

Picking Examples

Good examples are:

  • Concrete: specific numbers, names, values

  • Diverse: cover happy path, edge cases, negative scenarios

  • Realistic: plausible for actual users

  • Minimal: the simplest example that exercises the behavior

  • Independent: each example stands alone

A working set: 5-10 examples per significant behavior. Enough to surface edge cases; not so many that maintenance is unworkable.

What Examples Look Like

A worked set for the discount example:

Premium discount rules:

Example 1: Standard customer
- Customer type: Standard
- Cart subtotal: $100.00
- Expected discount: $0.00
- Expected total: $100.00

Example 2: Premium customer
- Customer type: Premium
- Cart subtotal: $100.00
- Expected discount: $10.00 (10%)
- Expected total: $90.00

Example 3: Premium customer with zero cart
- Customer type: Premium
- Cart subtotal: $0.00
- Expected discount: $0.00
- Expected total: $0.00

Example 4: Premium customer with small cart (rounding)
- Customer type: Premium
- Cart subtotal: $9.99
- Expected discount: $0.99 (rounded down from $0.999)
- Expected total: $9.00

Example 5: Newly upgraded premium customer
- Customer was Standard
- Mid-session, upgrade to Premium
- Existing cart subtotal: $100.00
- Expected discount: $10.00 (applies immediately to current cart)
- Expected total: $90.00

Example 6: Downgraded customer
- Customer was Premium
- Mid-session, downgrade to Standard
- Existing cart subtotal: $100.00
- Expected discount: $10.00 (discount given when added applies; downgrade doesn't retroactively remove)
- Expected total: $90.00

Six examples, each specific. The last two surface non-obvious behavior (handling of plan changes mid-session) that abstract requirements wouldn't have.

Surfacing Ambiguity

The most valuable moments in SBE are when an example surfaces ambiguity.

"What about a customer who upgrades mid-session?" → no one knew. The example forces a decision.

When ambiguity surfaces:

  • Discuss the right behavior

  • Add the example with the decided behavior

  • Note the decision in the examples (as comment if needed)

Each ambiguity caught at SBE time is one not caught during implementation, QA, or production.

Executable Specifications

The goal of "executable specifications" is that the examples become tests directly.

In Cucumber-style BDD, Gherkin syntax achieves this:

Scenario: Premium customer discount
  Given a Premium customer
  And a cart with subtotal $100.00
  When checkout is processed
  Then discount should be $10.00
  And total should be $90.00

Step definitions translate the Gherkin into test code.

For teams without BDD tooling, the same effect can be achieved by writing test cases that directly mirror the examples:

def test_premium_customer_discount():
    customer = Customer(type="Premium")
    cart = Cart(subtotal=100.00)
    
    result = checkout(customer, cart)
    
    assert result.discount == 10.00
    assert result.total == 90.00

The tests look like the examples. They're directly traceable.

Lightweight SBE Without Tools

You don't need Cucumber or any specific tool. The practice can be:

  1. Run three-amigos sessions

  2. Capture examples in a shared doc (or PR comments)

  3. Have developers translate examples into normal tests

  4. Keep the example doc updated as the team learns

This captures the SBE value with minimum tooling overhead.

When SBE Helps Most

Particularly valuable when:

  • Business rules are complex

  • Edge cases are likely

  • Multiple stakeholders need alignment

  • Regulatory or compliance specs need traceability

  • The team has previously had post-launch surprises

Less useful when:

  • The feature is technically simple

  • One person has all the context

  • The team is highly aligned by default

Maintaining Examples

As the product evolves:

  • Update examples when behavior changes

  • Add examples when new edge cases are discovered

  • Remove examples for behavior that's been removed

  • Version examples with the feature

A stale example is misleading. The example doc should match current reality.

Anti-Patterns

Examples written after the code. Documents what happened, not what was intended. Skips the discovery value.

Abstract examples. "Customer has a discount." No specific values; surfaces no edges.

Implementation in examples. "Database returns the discount value of 10%." That's implementation; examples should be black-box.

Too many examples. 50 examples for a simple rule. No one maintains them; they go stale.

No collaboration. Developer writes examples alone. Defeats the purpose.

Combining With Tests

The complete pattern:

  • Examples are the specification (during discovery)

  • Tests verify the examples (during development)

  • Both are maintained together

When a behavior changes, the example updates first; then the test updates to match. The example is the source of truth; the test verifies it.

For executable specifications (Cucumber-style), the example is the test. For non-BDD setups, the example and the test are separate but closely tied.

A Worked Three-Amigos Session

For a new "search ranking" feature:

  • PM brings the requirement: "Search should rank more relevant results higher."

  • Dev asks: "How is 'relevance' calculated?"

  • QA asks: "How do we know if it's working?"

The conversation produces examples:

  • Search for "shoe" → product "running shoe" ranks higher than article "shoe shopping tips" (products outrank articles for product searches)

  • Search for "review" → article "review of shoes" ranks higher than product "running shoe" (articles outrank products for content searches)

  • Search for an exact product name → that product is the top result

  • Search for a misspelling → fuzzy match returns the right product

The session produces 8-12 concrete examples. Implementation can now begin with a clear target. Tests can verify each example. The product evolves with reference to specific behaviors, not abstract intent.

Key Takeaway

Specification by Example uses concrete examples to drive shared understanding. Collaborate on examples (three amigos: PM, dev, QA). Use specific values; cover happy path, edge cases, and negative scenarios. Examples surface ambiguity that abstract requirements hide. Examples become tests (executable specifications if using BDD tools, regular tests otherwise). Maintain examples as the product evolves. The practice works without specific tools — the collaboration is the point.

Related reading

Keep learning. This article is part of the Test Automation path in the ShiftQuality Learning Center. Build test automation that lasts, with ROI you can defend.

bottom of page