formulating-gherkin

name	formulating-gherkin
description	Use when writing or reviewing Gherkin features, especially after discovering examples or edge cases that reveal a new business rule

Formulating Gherkin

When examples reveal a rule, make the rule visible in the feature file.

Core Habit

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"

Guidelines

• Use Rule: for a business/domain rule, not an implementation mechanism.
• Put scenarios that demonstrate the same rule under the same Rule:.
• If a scenario discovers a new rule, add or split out a new Rule: section.
• Keep scenario names as concrete examples of the rule, not restatements of it.
• Prefer several small Rule: groups over one long pile of loosely related scenarios.
• When reviewing a feature, ask: “What rule does this scenario prove?” If the answer is unclear, reformulate, or discuss with your human
• If a scenario appears to illustate multiple rules, consider splitting it

Smell

A feature with many scenarios and no Rule: sections is probably hiding the acceptance criteria. Extract the rules and group the scenarios around them.