Gherkin Keywords

Gherkin is the business-readable language behave uses for feature files. It is a small, fixed vocabulary: only a dozen keywords, combined with free-text descriptions. Learning the keywords precisely is the prerequisite for writing scenarios that map cleanly onto Python step functions.

The Core Keywords

Keyword	Purpose
Feature	Top-level container; one feature file describes one capability or user story.
Scenario	A single example of the behavior, executed independently.
Given	Known state before an action occurs.
When	The action or event under test.
Then	Observable outcome that is asserted.
And / But	Continue the previous keyword kind (Given, When, or Then).
Scenario Outline	A template scenario run once per row of a data table.
Examples	The data table of an outline; header row names substitution variables.
Background	Steps common to every scenario in the feature.
Rule (optional)	Grouping construct for related scenarios within a feature.

How And and But Are Parsed

Behave rewrites each And and But into the keyword of the preceding step. In the scenario below, behave dispatches all four steps as Then steps — your Python functions must therefore be registered with @then, not with whatever English word the file displayed:

Scenario: Successful login
  Given the user exists with email "[email protected]"
  When the user logs in with password "correct-horse"
  Then the dashboard is displayed
    And a welcome message is shown
    But no warning banner is displayed

Descriptions and Comments

Text between a keyword line and the first step is free description and is never executed. Lines starting with a hash are comments and are ignored entirely. Use them for stakeholder context, links, and authorship notes — do not encode behavior in comments:

Feature: Password reset
  This email feature covers password resets.
  Migrated from manual QA checklist #42; see JIRA AUTH-73.

  Scenario: Request a reset link
    # only happy path in this file; rate limits covered elsewhere
    Given a registered user with a known email
    When the user requests a password reset
    Then an email is sent within 60 seconds

Naming Scenario Parts

Good titles act as executable documentation. Prefer declarative, outcome-focused phrasing. Scenario titles are referenced by behave options such as --name, so keep them stable when reports or CI filters on them.

Scenario title: "Order total includes sales tax", not "Check order math".
Given steps: past tense or present state — "a customer is logged in".
When steps: present-tense actions the system or user takes.
Then steps: assertions with concrete, observable values.

Tags Belong to the Vocabulary Too

Lines beginning with @ above features and scenarios are tags — arbitrary labels such as @smoke, @wip, or @slow used for filtering with --tags and for hook selection. Tags are technically not Gherkin keywords but are part of the same lexical layer and are covered in their own chapter.

@authentication @smoke
Feature: Login

  @happy-path
  Scenario: Valid credentials sign in
    Given valid credentials are supplied
    Then the session starts

Structural Words Versus Step Words

Split the vocabulary into two roles: structural keywords (Feature, Scenario, Background, Examples, Rule) organize the document and never become steps; step keywords (Given, When, Then, And, But plus the multiline extensions Docstring and table rows) each correspond to exactly one Python function call at runtime. Keeping the two roles in mind makes parsing errors and matching failures easy to diagnose.

Summary

Gherkin provides a fixed set of structural and step keywords; behave rewrites And/But into the preceding keyword and treats descriptions and comments as inert text. Master these few terms and the rest of behave is Python-side implementation work.