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, notPOST_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
Whenper scenario. A scenario with twoWhensteps 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.