Three Amigos: Dev, QA, BA Collaboration

Gherkin Syntax Deep Dive

Gherkin is the language used to write BDD scenarios. It is deliberately simple — the entire syntax fits on one page.

The Keywords

Writing Good Steps

Steps should describe behaviour, not implementation:

# Bad — describes implementation
Given I navigate to /login and fill in the email field with "user@test.com"

# Good — describes behaviour
Given I am on the login page
When I sign in as "user@test.com" with password "secret"

The step definition handles the implementation details. The Gherkin stays readable by non-technical stakeholders.

Background

Use Background for steps that apply to all scenarios in a file:

Feature: Shopping cart

  Background:
    Given I am logged in as a customer
    And my cart is empty

  Scenario: Add a product
    When I add "Widget A" to my cart
    Then my cart should contain 1 item

  Scenario: Add two products
    When I add "Widget A" to my cart
    And I add "Widget B" to my cart
    Then my cart should contain 2 items

Scenario Outline + Examples

Scenario Outline: Login validation
  Given I am on the login page
  When I enter email "<email>" and password "<password>"
  Then I should see the error "<error_message>"

  Examples:
    | email           | password | error_message              |
    | not-an-email    | secret   | Please enter a valid email |
    |                 | secret   | Email is required          |
    | user@test.com   |          | Password is required       |
    | user@test.com   | wrong    | Invalid credentials        |

Each row in the Examples table generates an independent scenario execution.

Docstrings and Data Tables

For multi-line content:

When I submit the following JSON:
  """
  {"name": "Widget A", "price": 9.99}
  """

For structured data in steps:

When I add the following products to my cart:
  | Product  | Quantity |
  | Widget A | 2        |
  | Widget B | 1        |