Bdd

Precompiled BDD (Behavior-Driven Development) Manual

Quick use: BDD writing and testing steps

1. Clarify behavior first: write down Who / What / Why, business rules, concrete positive and negative examples, and unanswered questions; do not start from a test framework or UI steps.
2. Draft Gherkin: express the Given context, When event, and Then observable outcome in domain language; run the wording through the quality gate in section 7 before writing glue code.
3. Run the specification for feedback: run .feature files with Cucumber/Cucumber.js and first observe undefined, pending, or failed results to prove the scenario can drive the missing behavior.
4. Add step definitions and the smallest implementation: step definitions only connect scenarios to system behavior; production code should only do enough to pass the current example.
5. Refactor and add boundaries: keep scenario language stable, extract helpers/World/hooks, add important boundary cases or counterexamples, and report the red/green process plus unresolved questions.

If you are only reviewing BDD/Gherkin, stop at steps 1–2 and the checklist in section 14. Enter steps 3–5 only when the user explicitly asks for implementation or testing.

Preflight decision: do not default to Cucumber

Use this small decision filter before treating something as a BDD/Cucumber candidate:

• Stable, clear behavior: the code or behavior to be tested is not temporary scaffolding, pure framework code, migration glue, or an exploratory implementation that has not taken shape yet.
• Business purpose first: the scenario explains a business purpose in the project, user intent, or an observable outcome, not internal implementation details.
• Sentences fit the project domain: after writing a BDD sentence, check whether it helps people imagine — and genuinely fits — this project's actual real use cases.
• If the sentence is abstract or fragmented, or is merely a natural-language translation of a technical test, first rewrite the scenario or reconsider whether this point needs a BDD test at all.

0. The standard definition comes before tools

Behavior-driven development — Wikipedia:

> “Behavior-driven development (BDD) is an agile software development method centered around collaboration between business and IT professionals that have a stake in finding a solution for a complex problem. The core objective is to achieve a shared understanding of the problem.”

> “BDD involves use of a domain-specific language (DSL) using natural-language constructs ... that can express the behavior and the expected outcomes.”

This skill starts from that definition: BDD is an agile development method centered on collaboration, shared understanding, business language, concrete examples, and expected behavior. BDD can be implemented with Cucumber/Gherkin, other frameworks, or lightweight documentation; Cucumber is not BDD itself, but the classic executable-specification reference bundled with this skill.

When using this skill, ask first: “Have we reached shared understanding through concrete examples?” Then ask: “Do these examples need to be automated with Cucumber.js?” Do not reverse the order by equating BDD with “writing .feature tests.”

1. What this skill is: precompiled documentation, not a link list

This skill precompiles Wikipedia’s BDD definition, the official Cucumber BDD/Gherkin/Cucumber.js documentation, anti-patterns, and the JavaScript 10-minute tutorial into a manual an AI agent can use immediately. Future agents using this skill should treat this document as the default standard reference instead of assuming they will return to the web and reinterpret the docs.

Bundled content covers:

• BDD’s definition, goals, misconceptions, roles, and collaboration workflow.
• The Discovery → Formulation → Automation workflow.
• Minimal rules for Example Mapping, Three Amigos, User Stories, and Acceptance Criteria.
• Gherkin syntax, scenario writing style, good/bad examples, and anti-patterns.
• Cucumber.js project layout, step definitions, World/state, hooks, configuration, result semantics, and the official JavaScript example.

Intentionally not bundled: complete API documentation, every formatter/plugin/parallel/retry/sharding option, and every language implementation detail. When exact configuration parameters or library-version behavior matters, consult the official API/README.

2. Source fidelity: reference layers

Layer 1: BDD definition

• Behavior-driven development — Wikipedia: defines BDD around collaboration between business and IT stakeholders, with the goal of forming shared understanding of the problem; it often uses a natural-language DSL to express behavior and expected outcomes; BDD has a historical relationship with TDD, but its purpose is not test syntax — it is shared understanding and business language.

Layer 2: BDD practice model

• Cucumber BDD guide: BDD is an ongoing collaborative practice that uses concrete real-world examples for Discovery, Formulation, and Automation.
• Cucumber myths: conversations are more important than capturing conversations, and captured conversations are more important than automating conversations; automating scenarios after code is written can be test automation, but it is not the full BDD practice; using Cucumber does not mean you are doing BDD.
• Discovery workshop / Example Mapping / Who does what: explain how team roles and card-based examples clarify scope.

Layer 3: executable-specification implementation reference

• Gherkin reference: Feature, Rule, Scenario/Example, Given/When/Then, Background, Scenario Outline, Examples, Doc Strings, Data Tables, Tags, language.
• Cucumber.js docs and 10-minute tutorial: demonstrate the minimal JavaScript loop from undefined → pending/failed → passing → refactor/Examples.
• Anti-patterns / Better Gherkin / FAQ: provide maintainability boundaries and anti-patterns.

3. Core BDD standards

3.1 Goal: shared understanding, not test coverage

The core BDD question is not “Did the tests run?” It is whether business, development, and testing/quality have reached shared understanding of the same problem space, business rules, and observable behavior.

Signs you are actually doing BDD:

• Did the team discuss concrete examples before writing implementation?
• Is behavior expressed in business language instead of technical implementation language?
• Are examples written as checkable specifications rather than abstract wishes?
• Can a business stakeholder or user representative read and confirm them?
• Does automation serve specification feedback instead of replacing specification discussion?

3.2 Relationship between BDD and TDD

BDD was historically influenced by TDD, but do not reduce BDD to TDD with “Given/When/Then test syntax.” The Wikipedia summary emphasizes understanding the problem space and writing it down with business language, real data, intention-revealing wording, and necessary, focused examples.

Remember BRIEF:

• Business language: business terms, not class names, table names, or button names.
• Real data: real/concrete data, not foo, bar, or user1.
• Intention revealing: reveal intent so readers understand why the behavior matters.
• Essential: keep only essential semantics, not irrelevant implementation steps.
• Focused: each example focuses on one behavior/rule.

3.3 BDD is not these things

• Not Cucumber-specific: Cucumber/Gherkin is a common implementation, not the definition of BDD.
• Not post-hoc automation after code is complete: that can be acceptance automation / characterization testing, but it is not the full BDD practice.
• Not a UI interaction script: .feature files describe what, not how.
• Not a giant test-case repository: excessive data combinations belong in helpers/builders; feature files should keep the key examples.
• Not something one person writes in isolation: Discovery requires collaboration.

4. BDD workflow: Discovery → Formulation → Automation

The Cucumber BDD documentation describes day-to-day BDD as three kinds of practice: Discovery, Formulation, and Automation. The order matters: conversation first, capture second, automation last.

4.1 Discovery: discover behavior and scope

Goal: technical and non-technical stakeholders explore a small user story together, finding rules, examples, boundaries, counterexamples, and questions.

Working rules:

• Discuss one small story or small change at a time. If it cannot be clarified in 25–30 minutes, the story may be too large or may require more research.
• Hold discovery just in time before development so details are not lost and plans can still adapt to new facts.
• Cover at least the Three Amigos perspectives: product/business, development, and testing/quality.
• Ask for examples before asking for technical implementation.
• Record unknowns explicitly instead of guessing.

When no real three-way meeting exists, an AI agent should simulate the three perspectives, but it must mark which points are inference and which require user confirmation.

4.2 Three Amigos: three necessary voices

• Product owner / business representative: decides scope, value, and which boundaries belong to the current story.
• Tester / quality voice: raises boundaries, failure paths, missing stories, and ways the system can break.
• Developer / technical voice: identifies implementation constraints, dependencies, hidden complexity, and automation feasibility.

Important: scenario language should initially be established by the whole team; once the team matures, developers and testers may pair on Gherkin, but active product/business review is still needed.

4.3 Example Mapping: separate stories, rules, examples, and questions

Before development, use Example Mapping to clarify acceptance criteria quickly:

• Story (yellow card): the current user story.
• Rules / acceptance criteria (blue cards): constraints, rules, and acceptance criteria.
• Examples (green cards): concrete examples that illustrate rules.
• Questions (red cards): unanswered questions or assumptions.
• New stories (record separately): discovered work that is deferred out of scope.

Continue the conversation until the team believes the current story scope is clear, or time runs out. Do not hard-code unanswered questions into the specification.

4.4 User Story and Acceptance Criteria

A User Story is a small slice of valuable functionality used for planning and prioritization. Good stories often satisfy INVEST: Independent, Negotiable, Valuable, Estimable, Small, Testable.

Common story format:

As an 
I want a 
So that 

BDD does not require every feature file to use that format, but it does require answers to:

• Who: who benefits?
• What: what capability is needed?
• Why: why is it valuable?
• Acceptance: what concrete behavior proves it is done?

4.5 Formulation: write examples as readable, automatable specifications

Goal: write clearly discussed examples in a form both people and tools can understand. In the Cucumber ecosystem, this is usually Gherkin.

Formulation requirements:

• Use domain language.
• Be concrete without becoming technical.
• Describe behavior (what), not implementation (how).
• Keep each scenario focused on one behavior/rule.
• Keep scenarios independent and runnable in any order.
• Verify only observable outcomes in Then.

4.6 Automation: connect specifications to the system

Goal: automate one example at a time, using failure feedback to drive the smallest implementation.

Standard rhythm:

1. Write the scenario, run Cucumber, and see undefined.
2. Add step definitions, run again, and see pending or failed results.
3. Have the step definition call system behavior, and assert in Then.
4. See a failure first (red), proving the example catches the missing behavior.
5. Implement the smallest code needed to pass (green).
6. Refactor implementation and step definitions while keeping scenario language stable.
7. Add the next example or Scenario Outline, and continue the loop.

If the user only asks to “write Gherkin,” do not implement production code on your own. Enter full automation and red/green only when the user asks to “implement with BDD.”

5. Cucumber’s place in this skill

Cucumber is a tool that connects Gherkin executable specifications to code. It reads .feature files, matches step definitions, executes system behavior, and reports results. It is the classic implementation of BDD automation, but not the only possible implementation.

When using Cucumber, still follow the BDD order:

1. First discuss examples.
2. Then write Gherkin.
3. Finally write step definitions and implementation.

Do not skip Discovery just because a project already has Cucumber installed. Do not assume every BDD task is a JavaScript project just because this skill includes Cucumber.js examples. If the project uses another language/framework, carry over the principles and Gherkin language, and replace the automation layer.

6. Precompiled Gherkin quick manual

6.1 Files and top-level structure

A .feature file can contain only one Feature.

@billing
Feature: Subscription billing
  Customers should be charged according to their active plan
  so that access and revenue remain aligned.

  Rule: Active paid subscribers keep access

    Scenario: Paid subscriber can read paid article
      Given Priya has an active basic subscription
      When Priya opens the paid article "Scaling Rails"
      Then Priya can read the article

Recommended: indent by two spaces. Comments can only be added at the start of a new line with #; Gherkin does not support block comments.

6.2 Feature

Feature: gives the high-level capability and groups related scenarios. Keep the title short; use the free-form description underneath for business context, value, and a rule list. The free-form description does not affect execution, but it appears in reports.

A good Feature description answers Why / Who / What:

Feature: Account balance
  As a mobile bank customer
  I want to see balances for my accounts
  So that I can make informed spending decisions

Do not write a Feature as a technical module name:

Feature: AccountController GET /api/v1/accounts JSON serializer

Unless your product is the API contract itself, this is not business language.

6.3 Rule

Rule: represents a business rule and groups several scenarios that illustrate it. A rule should have one or more examples.

Feature: Transfer limits

  Rule: Transfers above the daily limit are rejected

    Scenario: Alice exceeds her daily limit
      Given Alice has already transferred $900 today
      When Alice tries to transfer $200 to Bob
      Then the transfer is rejected
      And Alice is told her remaining daily limit is $100

Using Rule prevents feature files from becoming unstructured lists of scenarios.

6.4 Scenario / Example

Scenario and Example are synonyms in Gherkin. A scenario is a concrete example that illustrates a business rule and is also an executable test.

The official guidance is that each example should have roughly 3–5 steps; too many steps weaken the specification/documentation value. If a one-sentence title cannot explain the purpose of a scenario, it usually needs to be split.

6.5 Given / When / Then

• Given: initial context that puts the system into a known state. Avoid user-interaction details.
• When: the event or action triggered by a user or external system.
• Then: the expected outcome, which must verify the actual result with assertions.
• And / But: continue the previous step type for readability.
• *: can be used to write a list of similar steps.

Scenario: Transfer within the daily limit
  Give

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [xz-dev](https://github.com/xz-dev)
- **Source:** [xz-dev/bdd-skill](https://github.com/xz-dev/bdd-skill)
- **License:** MIT

Install and usage instructions live in the source repository linked above.