Acceptance & BDD — Middle Level¶

Roadmap: Testing → Acceptance & BDD

The Three Amigos, the declarative-vs-imperative discipline that makes Gherkin worth writing, and the tooling that runs it — Cucumber, SpecFlow, Behave, Godog.

Table of Contents¶

1. Introduction
2. Prerequisites
3. Glossary
4. Core Concept 1 — The Three Amigos
5. Core Concept 2 — Declarative, Not Imperative: the #1 Gherkin Discipline
6. Core Concept 3 — Scenario Outlines and Examples Tables
7. Core Concept 4 — Background, Tags, and Organising Features
8. Core Concept 5 — Step Definitions Done Well
9. Core Concept 6 — The Tooling Landscape
10. Real-World Examples
11. Mental Models
12. Common Mistakes
13. Test Yourself
14. Cheat Sheet
15. Summary
16. Further Reading
17. Related Topics

Introduction¶

Focus: the collaboration ritual (Three Amigos), the writing discipline that separates valuable Gherkin from brittle noise (declarative not imperative), and a working knowledge of the tooling that binds specs to code.

You can read a scenario and wire a step definition. The middle-tier skills are the ones that decide whether a BDD suite helps or rots: holding the Three Amigos conversation, writing scenarios in durable business language instead of fragile UI scripts, parameterising with examples tables, and keeping step definitions clean. Get these right and the suite becomes living documentation; get them wrong and it becomes the slowest, most brittle layer you own.

Prerequisites¶

• You can read and write a basic Gherkin scenario and a step definition (Junior Level).
• You write unit and integration tests comfortably (Unit Testing, Integration Testing).
• You've worked from user stories / tickets with a product owner.
• You understand the test pyramid well enough to know acceptance tests should be few (Test Strategy & the Pyramid).

Glossary¶

Core Concept 1 — The Three Amigos¶

The Three Amigos is the conversation that is BDD. Before a story is built, three perspectives meet:

The session runs ~30 minutes and produces a set of concrete examples that become the acceptance criteria that become the scenarios. The magic is the questions. QA naturally asks about the empty case, the boundary, the failure; dev surfaces the technical edge; business decides what actually matters. A 30-minute conversation routinely prevents days of building the wrong thing.

The conversation is the deliverable. The Gherkin is the written record of what was agreed. If you skip the conversation and just write Gherkin, you have a record of one person's assumptions — which is exactly what BDD exists to prevent.

A lightweight example-mapping layout for the session (Matt Wynne's technique):

  ┌─ STORY (yellow): Apply a discount code at checkout
  │
  ├─ RULE (blue): A code gives a percentage off the subtotal
  │    ├─ EXAMPLE (green): SAVE10 on a $100 cart → $90
  │    └─ EXAMPLE (green): SAVE10 on an empty cart → still empty, no error
  │
  ├─ RULE (blue): Expired codes are rejected
  │    └─ EXAMPLE (green): code expired yesterday → "This code has expired"
  │
  └─ QUESTION (red): Do codes stack with an active sale?   ← unresolved!

Those red questions are the gold: they're the ambiguities you'd otherwise discover mid-sprint. You answer them before estimating, not after committing.

Core Concept 2 — Declarative, Not Imperative: the #1 Gherkin Discipline¶

This is the single most important writing skill in BDD. A scenario should describe what the user is trying to do, not the mechanical steps of doing it.

Imperative (the anti-pattern):

Scenario: Login
  Given I open the browser at "/login"
  And I type "alice@example.com" into the field "#email"
  And I type "hunter2" into the field "#password"
  And I click the button "#login-submit"
  Then I wait 2 seconds
  And I see the element ".dashboard-header"

Declarative (the same intent):

Scenario: Registered user logs in successfully
  Given I am a registered user
  When I log in with valid credentials
  Then I land on my dashboard

Why the declarative version is strictly better:

The mechanical detail (#email, click, wait 2 seconds) doesn't vanish — it moves down into the step definition, where it belongs and where a developer maintains it. The Gherkin stays a stable description of behaviour. An imperative Cucumber suite is the most common reason teams come to hate BDD: it's slow, it's brittle, and it reads like a macro recording instead of a specification.

Core Concept 3 — Scenario Outlines and Examples Tables¶

When one rule has many examples, don't copy-paste scenarios. Use a Scenario Outline with an Examples table:

Feature: Password strength

  Scenario Outline: Passwords are accepted or rejected by policy
    Given I am registering a new account
    When I choose the password "<password>"
    Then registration is "<result>"
    And I see the message "<message>"

    Examples:
      | password      | result   | message                        |
      | abc           | rejected | Too short (minimum 8)          |
      | password      | rejected | Too common                     |
      | Tr0ub4dor&3   | accepted |                                |
      | correct horse | rejected | Add a number or symbol         |

The outline runs once per row, substituting <placeholders>. This is specification by example in its purest form: the table is the policy, readable by anyone, and each row is an independent test. It's also the natural home for boundary values that came out of the Three Amigos questions (exactly 8 chars? what about whitespace?).

Core Concept 4 — Background, Tags, and Organising Features¶

Background factors out Given steps shared by every scenario in a feature — but keep it short; a long Background usually means your scenarios are over-specified.

Feature: Shopping cart

  Background:
    Given I am a logged-in customer
    And the catalogue contains a "Widget" priced at $20

  Scenario: Add a single item
    When I add 1 "Widget" to my cart
    Then my cart total is $20

Tags select and group scenarios:

@checkout @smoke
Scenario: Successful purchase with a saved card
  ...

Then run subsets: cucumber --tags "@smoke", or exclude work-in-progress with --tags "not @wip". Common tags: @smoke (fast critical path), @wip (skip in CI), @slow, @regression. Tags are how you keep an acceptance suite runnable in stages instead of an all-or-nothing 40-minute block.

Core Concept 5 — Step Definitions Done Well¶

Step definitions are real code and deserve real care. Two rules dominate.

1. Share state through a context object ("world"), not globals. Each scenario gets a fresh world so scenarios stay isolated.

# pytest-bdd: state flows through fixtures
@given("I am a logged-in customer", target_fixture="session")
def logged_in():
    return create_session(user=make_user())

@when(parsers.parse('I add {qty:d} "{product}" to my cart'))
def add_to_cart(session, qty, product):
    session.cart.add(product, qty)

@then(parsers.parse("my cart total is ${total:d}"))
def assert_total(session, total):
    assert session.cart.total() == total

The equivalent in Go with Godog, where the world is a struct:

type cartCtx struct {
    session *Session
}

func (c *cartCtx) iAmALoggedInCustomer() error {
    c.session = NewSession(MakeUser())
    return nil
}

func (c *cartCtx) iAddToMyCart(qty int, product string) error {
    return c.session.Cart.Add(product, qty)
}

func (c *cartCtx) myCartTotalIs(total int) error {
    if got := c.session.Cart.Total(); got != total {
        return fmt.Errorf("expected total %d, got %d", total, got)
    }
    return nil
}

func InitializeScenario(ctx *godog.ScenarioContext) {
    c := &cartCtx{}
    ctx.Step(`^I am a logged-in customer$`, c.iAmALoggedInCustomer)
    ctx.Step(`^I add (\d+) "([^"]*)" to my cart$`, c.iAddToMyCart)
    ctx.Step(`^my cart total is \$(\d+)$`, c.myCartTotalIs)
}

2. Drive the system at the right layer — usually below the UI. A declarative step like When I log in with valid credentials should call the service/API layer, not click through a browser, whenever the scenario isn't specifically testing the UI. This is what keeps acceptance tests fast and stable. Reserve actual browser-driving for the handful of scenarios that genuinely verify the UI.

Core Concept 6 — The Tooling Landscape¶

Gherkin is portable; the runner depends on your stack. The tool is the least important decision — collaboration matters far more — but you should know the field:

Most tools can also generate living documentation — an HTML report of features and their pass/fail state — so the specs that drove development double as always-current docs. (Tools like Serenity BDD and Pickles specialise in this.) That's a genuine benefit, but only if the scenarios are declarative and readable; living docs generated from imperative click-scripts document nothing.

Real-World Examples¶

• Insurance quoting. Premium rules are genuinely complex (age bands, region, claims history). A Scenario Outline with 25 rows becomes the authoritative spec the actuaries, devs, and QA all read from. Here the collaboration payoff is huge — the domain is exactly where shared language pays.
• A team that hated Cucumber. Three developers wrote 400 imperative scenarios that drove a Selenium browser. The suite took 45 minutes, was flaky, and no business person ever read it. They had paid the full cost of BDD (the automation tax) and received none of the benefit (collaboration). The fix wasn't more Gherkin — it was deleting most of it and pushing the assertions down to API-level tests.
• Tag-staged CI. A fintech runs @smoke (12 scenarios, 90 s) on every push and the full @regression set nightly, keeping fast feedback while still covering breadth.

Mental Models¶

• Gherkin is an interface, step definitions are the implementation. Keep the interface in business language and stable; let the implementation absorb churn.
• The table is the spec. A Scenario Outline with a well-chosen Examples table often communicates a rule better than a paragraph of prose.
• One scenario, one behaviour. If you need "and then also…", it's two scenarios.
• Drive low, assert in business terms. Talk to the API in step definitions; phrase the Gherkin as user intent.
• The Amigos meeting is the product; the .feature file is the receipt.

Common Mistakes¶

• Imperative scenarios. Click-by-click UI scripts in Gherkin — brittle, unreadable, the #1 cause of BDD regret. Phrase intent; push mechanics into step definitions.
• Skipping the Three Amigos. Writing scenarios alone reduces BDD to a verbose unit-test dialect with all the cost and none of the shared understanding.
• Driving everything through the browser. Makes the suite slow and flaky. Drive below the UI unless the scenario is specifically about the UI.
• Bloated Background. Shared setup creeping toward "set up the whole world" signals over-specified scenarios.
• Leaky shared state. Globals between step definitions cause order-dependent flakes; use a per-scenario world/context.
• Too many acceptance tests. They belong near the top of the pyramid — few and stable. Hundreds of them is a pyramid inverted into an ice-cream cone.

Test Yourself¶

1. Who are the Three Amigos and what does each contribute?
2. Rewrite this imperative step declaratively: When I click "#add-to-cart" then click "#cart-icon" then click "#checkout".
3. When should you reach for a Scenario Outline instead of multiple Scenarios?
4. Why should When I log in usually hit the API rather than drive a browser?
5. What is the risk of a long Background?
6. A team has 400 Cucumber tests, all browser-driven, written by developers, that no PO reads. What have they actually built — and what's the fix?

Cheat Sheet¶

THREE AMIGOS  (before coding, ~30 min)
  Business: what & why   Dev: feasibility & edges   QA: how it breaks
  Output = concrete examples → acceptance criteria → scenarios
  Red "question" cards = the ambiguities you just saved a sprint on.

DECLARATIVE > IMPERATIVE
  BAD : Given I type "x" into "#email" / click "#submit"
  GOOD: Given I am a registered user / When I log in
  Mechanics live in step definitions, not Gherkin.

SCENARIO OUTLINE
  Scenario Outline: ...
    When I choose "<password>"   Then registration is "<result>"
    Examples: | password | result |

ORGANISE
  Background  = shared Givens (keep short)
  @tags       = select/skip subsets (@smoke, @wip, @regression)

STEP DEFS
  - share state via per-scenario world/context (no globals)
  - drive BELOW the UI unless testing the UI

TOOLS: Cucumber (Java/JS/Ruby) · SpecFlow/Reqnroll (.NET)
       Behave & pytest-bdd (Python) · Godog (Go)
  Living docs = HTML generated from passing, readable scenarios.

Summary¶

The middle tier is where BDD lives or dies. The Three Amigos conversation — business, dev, QA agreeing on concrete examples before coding, with example mapping surfacing the unresolved questions — is the actual practice; the .feature file is its receipt. The decisive writing skill is declarative, not imperative: describe user intent in Gherkin and push UI mechanics down into step definitions, so the suite survives redesigns and stays readable. Scenario Outlines with Examples tables turn complex rules into specification by example; tags and a lean Background keep the suite organised and stageable; and clean step definitions share per-scenario state and drive the system below the UI. The tooling — Cucumber, SpecFlow, Behave, pytest-bdd, Godog — is the smallest decision; collaboration is the largest.

Further Reading¶

• Specification by Example — Gojko Adzic (the canonical treatment of examples-as-specs).
• BDD in Action — John Ferguson Smart (Three Amigos, living documentation, tooling end to end).
• Matt Wynne — Introducing Example Mapping (the red/blue/green/yellow card technique).
• The Cucumber for Java Book / Cucumber docs — declarative-vs-imperative guidance.

Related Topics¶

• Junior Level — acceptance vs unit, first scenario, step definitions.
• Senior Level — BDD-as-collaboration in depth, when it pays, acceptance in the pyramid.
• Test Strategy & the Pyramid — keeping acceptance tests few and high.
• End-to-End Testing — driving the UI when a scenario truly needs it.
• The test-driven-development skill — the inner loop BDD's outer loop wraps.