authoring-feature-files

Authoring Feature Files

A .feature file is the shared contract between engineering and a non-technical stakeholder. Its single test of quality: can a product or compliance person read it and confirm the behavior is correct?

When to write one

Before implementing any user-visible behavior change, when a stakeholder outside engineering needs to sign off, or when the behavior has enough variants to warrant executable documentation.

How

1. Create the feature file. Write features/<slug>.feature using the Feature template at the end of this skill. Create features/ if needed.

2. Write the Feature: from the user story. Capture role, capability, and business value. This is the why.

3. Write scenarios as outcomes. Name each scenario after the result, not the action ("Overdue customer is blocked from checkout", not "Test checkout"). Cover the happy path plus the meaningful edge cases — typically three to seven scenarios. Do not generate dozens from one story.

4. Use business language, never UI language.

   • Good: Given a customer with an overdue invoice
   • Bad: Given the user clicks the blue "Pay" button UI-language steps lock the spec to the current implementation and break on every redesign.

5. Stay declarative. State what behavior is expected, not the click-by- click procedure. The step definitions handle the how.

6. Use Background for shared preconditions and Scenario Outline + Examples when one behavior varies only by input — do not copy-paste near- identical scenarios.

After authoring

• Have the stakeholder read it. If they cannot, rewrite in plainer language.
• Wire step definitions in code (Cucumber / Behave / pytest-bdd / SpecFlow). Steps must be real code, not prompts — agents tend to summarize multi-step scenarios if asked to "execute" Gherkin directly.
• An unrun feature file is stale documentation, not a contract. Keep it green.

Feature template

Create features/<slug>.feature with this structure:

Feature: <capability in plain language>
  # One or two sentences of context: who benefits and why this behavior exists.
  As a <role>
  I want <capability>
  So that <business value>

  Background:
    # Steps common to every scenario below. Keep it minimal — only true
    # preconditions, no test data noise.
    Given <a shared precondition>

  Scenario: <the happy path, named as an outcome>
    Given <a known starting state in domain terms>
    When <the event or action the actor takes>
    Then <the observable outcome>
    And <a further expected outcome, if any>

  Scenario: <a meaningful edge case, named as an outcome>
    Given <a different starting state>
    When <the same or related action>
    Then <the different expected outcome>

  Scenario Outline: <a behavior that varies by input>
    Given <a starting state using <placeholder> values>
    When <an action involving "<input>">
    Then <the outcome should be "<result>">

    Examples:
      | input    | result   |
      | <value1> | <value1> |
      | <value2> | <value2> |