Specification by Example

Rule: write Gherkin in domain language. No DOM selectors, no implementation detail.

Reject: When I click "#submit-btn". Reject: scenarios that use technical IDs the product owner does not recognise. Reject: imperative click-by-click tutorials posing as scenarios.

Generate: declarative scenarios in the ubiquitous language ( When I submit my registration). Step definitions handle the mechanics. The .feature file stays domain-only.

Diagnostic: a stakeholder reads the feature file and recognises every term. If a developer has to translate, the term does not belong in the scenario.

• Stakeholder, developer and tester share one vocabulary, Evans's ubiquitous language by another name. The scenario is the artefact all three sign.
• The AC in the ticket is the scenario in the feature file. The story moves from analysis to development without anybody rewriting the requirement in code-flavoured prose.
• Declarative steps survive a redesign. When I submit the form still passes after the button moves; When I click the third button breaks the morning the layout changes.
• Slots into the four-tenet spec pipeline, P2 Spec-First Execution → AI4 Verifiable Specs → TS2 → TS1 Living Documentation. One artefact, four checkpoints, each owned by the pillar that polices it.
• Coding agents treat the Gherkin as the canonical spec. A declarative scenario in domain words is a target the model can satisfy. An imperative one is a UI script the model reproduces one click at a time.
• One scenario, one behaviour. The and-counting rule keeps the document diff-friendly, the failure modes attributable and the regression net legible.
• A declarative scenario is parameterisation-ready. Pair with TS3 Parameterised Scenarios when the example becomes a table, with property-based tests when the table becomes infinite.

Specification by Example crystallised in 2009-2011. Gojko Adzic's Bridging the Communication Gap (2009)6Gojko AdzicBridging the Communication Gap: Specification by Example and Agile Acceptance Testing (Neuri, 2009). The earlier book that established the practice. Acceptance tests as agreed truth between business and developers. set the practice; Specification by Example (2011)1Gojko AdzicSpecification by Example: How Successful Teams Deliver the Right Software (Manning, 2011). Codifies the practice as seven process patterns and is the canonical reference for the term itself. codified it as seven process patterns. Adzic chose the name deliberately over “BDD” or “ATDD”7Shane Hastie“Interview and Book Review: Specification by Example” (InfoQ, 2011). Asked why he used the term rather than ATDD or BDD, Adzic answers: “It’s the one with the least amount of negative baggage.” He did not want ATDD, which he says focuses “too much on the testing aspect of the process”.: he wanted the term with the least negative baggage, and one that did not reduce the practice to a testing activity.

The lineage runs back through Dan North's 2006 introduction of BDD,8Dan North“Introducing BDD” (dannorth.net, 2006). The article that named the practice. Given/When/Then proposed first as a documentation grammar, second as a testing grammar. where Given/When/Then was already proposed as a documentation grammar, and further back to Eric Evans's Domain-Driven Design (2003), whose ubiquitous language is the source of the “domain language” clause in the TS2 punch.9Eric EvansDomain-Driven Design (Addison-Wesley, 2003). Ubiquitous Language is the source of the “domain language” clause in the TS2 punch. The scenario is the language’s written form. Cucumber's “BDD History” page traces the chain explicitly.10Cucumber documentation“History of BDD”. Traces the lineage from Evans’s ubiquitous language through North’s BDD into the modern Cucumber-era practice. Liz Keogh's “What is BDD?”11Liz Keogh“What is BDD?” (lizkeogh.com, 2015). The shortest accurate definition: examples in conversation to illustrate behaviour. is the cleanest modern compression: examples in conversation to illustrate behaviour.

The declarative-not-imperative rule, often the part working developers most need, is Cucumber's own Writing Better Gherkin guide.2Cucumber documentation“Writing Better Gherkin”. The declarative-versus-imperative rule in Cucumber’s own words: scenarios should describe the intended behaviour rather than the implementation. The Three Amigos pattern (Dinwiddie, 2009)12George Dinwiddie“If you don’t automate acceptance tests?” (blog.gdinwiddie.com, 2009). Dinwiddie uses “three amigos”, a term he says he borrowed from friends at Nationwide: product owner, developer and tester agree how they will know a story is done, however and whenever that conversation happens. names the conversation half: business, development, testing in one room before the code starts. Wynne and Hellesøy's Cucumber Book13Matt Wynne & Aslak HellesøyThe Cucumber Book, 2nd ed. (Pragmatic Bookshelf, 2017). The reference text on operating SBE with a working test runner. is the reference text on putting the practice into a working test runner.

In the Prickles canon, TS2 is the third link in a four-tenet pipeline. P2 Spec-First Execution commands writing the AC up front. AI4 Verifiable Specs commands writing it as something a machine can grade. TS2 commands writing it declaratively in domain words. TS1 takes the resulting check and turns it into the documentation. The chain is the operating principle and TS2 is its testing-side phrasing rule.

17 external sources, ranked by author authority. The first five are the canon; expand to see the rest, including the qualifiers and the named opposers. Each links out to its primary source.

1. 01
   Specification by ExampleSupports

   Gojko Adzic · 2011

   Codifies the practice as seven process patterns. The canonical reference. Adzic chose the term over BDD or ATDD for the cleanest description of the artefact: a specification, illustrated by examples, that the team agreed on.
2. 02
   Bridging the Communication Gap: Specification by Example and Agile Acceptance TestingSupports

   Gojko Adzic · 2009

   The earlier book that established the practice. Acceptance tests as agreed truth between business and developers; SBE’s grounding in the conversation half.
3. 03
   Introducing BDDSupports

   Dan North · 2006

   The article that named BDD; Given/When/Then proposed first as a documentation grammar, second as a testing grammar. The structural ancestor of Cucumber’s Gherkin.
4. 04
   What is BDD?Supports

   Liz Keogh · 2015

   “Using examples in conversation to illustrate behaviour.” The shortest accurate definition of the practice TS2 names.
5. 05
   Conversational Patterns in BDDSupports

   Liz Keogh · 2011

   The conversation-first idea. “BDD isn’t about the tools”. The spec is the discussion the team has, with the Gherkin file as its written record.

6. 06
   Writing Better GherkinSupports

   Cucumber documentation · 2020+

   The declarative-versus-imperative rule, in Cucumber’s own words. The shortest published source for the writing-style half of TS2.
7. 07
   BDD OverviewSupports

   Cucumber documentation · 2020+

   Cucumber’s three-practice idea: discovery, formulation, automation. SBE compressed into the loop a working team runs every sprint.
8. 08
   The Cucumber Book, 2nd ed.Supports

   Matt Wynne & Aslak Hellesøy · 2017

   The reference text on putting the practice into a working test runner. Hellesøy created Cucumber; he and Wynne, with Steve Tooke, wrote the canonical book on operating it.
9. 09
   Domain-Driven Design: Ubiquitous LanguageSupports

   Eric Evans · 2003

   The concept TS2 inherits from. The team’s ubiquitous language is the source of the “domain language” clause in the punch. The scenario is its written form.
10. 10
    If you don’t automate acceptance tests...Supports

    George Dinwiddie · 2009

    The post where Dinwiddie uses “three amigos”, a term he borrowed from friends at Nationwide: product owner, developer and tester agree how they will know a story is done, however and whenever they meet. The conversation half SBE depends on.
11. 11
    SpecificationByExample (bliki)Supports

    Martin Fowler · 2004

    Fowler says the phrase struck him at a workshop at XP/Agile Universe in 2002. Fowler’s idea: the example is what the spec turns into when it stops being abstract.
12. 12
    Three Amigos (Agile Alliance glossary)Supports

    Agile Alliance · 2010+

    The canonical glossary entry. Three perspectives in one room: business asks “what problem are we trying to solve?”, development asks “how might we build a solution to solve that problem?”, testing asks “what about this, what could possibly happen?”.
13. 13
    Given, When, Then (bliki)Supports

    Martin Fowler · 2013

    The clearest mainstream restatement of the Gherkin grammar as a documentation primitive. Fowler distinguishes the literary form from the test form. Both are SBE.
14. 14
    What’s in a Story?Supports

    Dan North · 2007

    The original story template plus acceptance criteria as scenarios. The cross-pillar bridge between user-story practice and SBE’s declarative scenario.
15. 15
    Anti-PatternsQualifies

    Cucumber documentation · 2020+

    Names two failure modes: feature-coupled step definitions and conjunction steps. The boundary between SBE and step-script imitation.
16. 16
    Why Don’t People Use Formal Methods?Opposes

    Hillel Wayne · 2019

    Background for Wayne’s natural-language critique. Sets up the argument that example-based specs cannot encode invariants, only their instances.
17. 17
    Integrated Tests Are A ScamOpposes

    J. B. Rainsberger · 2009

    Treats the integrated test SBE produces as a confidence-trick. Collaborators can drift while the scenario passes. The strongest published objection at the test-fidelity layer.

Seventeen sources, three stances. The supports above are the canon: Adzic, North, and Keogh on Specification by Example and BDD. The one qualifier, Cucumber's Anti-Patterns page, names two ways a step file goes wrong: step definitions that cannot be reused across features, and conjunction steps that combine several things into one. The opposers hold the steelman the reply has to address.