bdd-formulation

BDD Formulation

Formulation is the craft of writing Gherkin that serves as living documentation. Good scenarios are concrete examples of business rules, not test scripts.

Core Habit

When examples reveal a rule, make the rule visible in the feature file: group related scenarios under a Rule: keyword that states the rule they illustrate.

Rule: Manual blockers replace the existing manual blocker

  Scenario: Adding another manual blocker updates the reason
    Given I add the yak "deploy"
    And I add manual blocker to "deploy" with reason "waiting on vendor"
    When I add manual blocker to "deploy" with reason "waiting on review"
    Then the JSON yak "deploy" should have exactly one manual blocker with reason "waiting on review"

BRIEF Check

From Seb Rose, scenarios should be:

• Business language: terms stakeholders understand.
• Real data: vivid, concrete examples.
• Intention revealing: say what matters, not how the UI works.
• Essential: every line serves the rule.
• Focused: one rule per scenario, short enough to read.

Guidelines

• Use Rule: for a business/domain rule, not an implementation mechanism.
• Keep scenario names as concrete examples of the rule, not restatements of it.
• If a scenario discovers a new rule, add or split out a new Rule: section.
• If a scenario appears to illustrate multiple rules, split it.
• Prefer several small Rule: groups over one long pile of loosely related scenarios.
• Carry one consistent narrative through a feature where possible.
• Put cross-cutting assertions, such as output or logging, on existing scenarios rather than in separate rules.

Review Questions

• What rule does this scenario prove?
• Does the Example name add information beyond the Rule?
• Is every line essential?
• Is the data concrete and business-readable?
• Would a feature with no Rule: sections be clearer if its rules were extracted?