Gherkin feature files

Behaviour is described in Gherkin: Feature, Scenario, and Given / When / Then steps. This page covers how the platform writes it, and the handful of conventions that make a feature file reviewable rather than merely readable.

Structure

A feature file describes one coherent capability. Each scenario describes one situation and its outcome.

Feature: Cancel a subscription

  Background:
    Given a customer "C-88" on the "pro" plan
    And the current billing period ends in 3 days

  Scenario: Cancelling before the renewal date
    When the customer cancels their subscription
    Then the subscription status becomes "cancelled"
    And the customer is not charged at the end of the period
    And a cancellation confirmation is emailed to the customer

  Scenario: Cancelling after the renewal date
    Given the current billing period ends in 2 days
    And the plan does not allow cancellation
    When the customer attempts to cancel their subscription
    Then the request is rejected with code "CANCELLATION_WINDOW_CLOSED"
    And the subscription status remains "active"

Two habits in that file are worth adopting deliberately.

The Background holds shared state, not shared actions. Everything in Background is true before each scenario. If you put a When in a Background, you have hidden the actual sequence, and the reader has to reconstruct it mentally for every scenario.

The negative case is present. The second scenario is the one that carries most of the value. A feature file with only happy paths documents what should happen, not what should not, and the missing half is where the bugs live.

Tags

Tags carry metadata that tooling can act on. The platform uses them for three things.

Targeting. A tag marking a scenario as requiring a third-party sandbox tells the build to provision that sandbox, and to skip the scenario with a clear reason if it cannot.

Traceability. A tag referencing a ticket or requirement ID links the scenario to the thing it came from. This is what makes a coverage map meaningful: not "we have twelve scenarios" but "requirements R-1 through R-9 each have a scenario, and R-10 does not".

Severity. A tag marking a scenario as covering a money-moving path changes how aggressively the build treats it, and how loudly a failure is reported.

Examples tables

Parameterised scenarios are written with an Examples table. One scenario outline, many rows.

Scenario Outline: Refund within the window

  Given the refund window is <window> days
  And order "A-<id>" settled <age> days ago
  When the customer requests a refund
  Then the request is <outcome>

  Examples:
    | id   | window | age | outcome                          |
    | 1042 | 30     | 3   | granted with amount 42.00 EUR   |
    | 1043 | 30     | 31  | refused with REFUND_WINDOW_CLOSED |
    | 1044 | 7      | 3   | granted with amount 42.00 EUR   |

Be careful with outlines. An outline with five rows is five scenarios executed, but it reads as one, and reviewers routinely approve an outline without checking every row. Where the rows differ in kind rather than in value — a granted case and a refused case in the same table — write them as separate scenarios instead. Outlines are for varying data; they are the wrong tool for varying behaviour.

Conventions the platform applies

When the platform drafts a feature file, it follows the conventions already present in your repository. When there are none to follow, it applies these defaults and writes them into your project style guide:

  • Files are named for the capability, not the endpoint: cancel_subscription.feature, not POST_subscriptions_cancel.feature.
  • Steps are written from the actor’s point of view and avoid implementation detail. "When the customer cancels their subscription", not "When the DELETE /subscriptions/{id} handler is invoked".
  • Step phrasing is reused across files wherever the meaning repeats, so that a change in one place is a change in one place.
  • One When per scenario. A scenario with two When steps describes two situations and usually hides a missing case.
  • Explicit values, not placeholders. "the order status becomes refunded" beats "the order status becomes correct". A reader should never have to consult another document to know what a step means.
  • Error codes are asserted literally, not described. The exact code, not "an appropriate error".

The step text is the contract

One thing is easy to miss: in a Gherkin file, the step text is the specification. The step implementation is just plumbing that binds text to code.

That has a direct consequence. If a step says "the customer sees a helpful error", then "helpful" is the specification, and it is untestable. If it says "the request is rejected with code REFUND_WINDOW_CLOSED and a message containing ‘the refund window has closed’", then both halves are checkable.

Write steps so that a reader can tell, without running anything, whether the assertion is strong enough to catch a real defect. The platform grades exactly this — see assertion strength.

Next