Gherkin Basics

Learn the fundamentals of Gherkin syntax for writing tests

Gherkin Basics

Gherkin is a plain-text language that uses a simple structure to describe software behavior. TestFlowKit uses Gherkin to make tests readable by everyone on your team.

What is Gherkin?

Gherkin is a Business Readable, Domain Specific Language that lets you describe software behavior without detailing how that behavior is implemented.

File Structure

Gherkin files use the .feature extension and follow a specific structure:

Feature: Feature Name
  Feature description goes here.
  It can span multiple lines.

  Background:
    Given common setup steps

  Scenario: First scenario
    Given some precondition
    When some action
    Then expected result

  Scenario: Second scenario
    Given another precondition
    When another action
    Then another result

Keywords

Feature

Every .feature file starts with a Feature keyword followed by a name and optional description:

Feature: Shopping Cart
  As a customer
  I want to manage items in my cart
  So that I can purchase products

Scenario

A Scenario is a concrete example that illustrates a business rule:

Scenario: Add item to empty cart
  Given the cart is empty
  When I add a product to the cart
  Then the cart should contain 1 item

Background

Background allows you to add context to all scenarios in a feature file. It runs before each scenario:

Feature: Account Management

  Background:
    Given the user is logged in
    And the user goes to the "settings" page

  Scenario: Change email
    When the user enters "new@email.com" into the "email" field
    ...

  Scenario: Change password
    When the user enters "newpassword" into the "password" field
    ...

Steps

Steps are the building blocks of scenarios. Each step starts with a keyword:

KeywordPurposeExample
GivenSetup/PreconditionGiven the user is logged in
WhenAction/EventWhen the user clicks "submit"
ThenExpected outcomeThen the "success" message should be visible
AndAdditional stepAnd the cart total is "$50"
ButNegative assertionBut the "error" should not be visible

ℹ️ Step Keywords are Interchangeable: Gherkin treats Given, When, Then, And, and But as interchangeable. The distinction is for human readability only. TestFlowKit matches steps by their text pattern, not the keyword.

Data Tables

Use data tables to pass structured data to steps:

Scenario: Fill registration form
  Given the user goes to the "register" page
  When the user fills the form with:
    | field    | value           |
    | name     | John Doe        |
    | email    | john@example.com|
    | password | secret123       |
  And the user clicks the "submit" button

Doc Strings

For multi-line text, use doc strings (triple quotes):

Scenario: Submit feedback
  Given the user goes to the "feedback" page
  When the user enters the following into the "message" field:
    """
    This is a multi-line message.
    It can contain special characters: @#$%
    And preserves formatting.
    """

Tags

Tags allow you to organize and filter scenarios:

@smoke @critical
Feature: Authentication

  @login
  Scenario: Valid login
    ...

  @login @negative
  Scenario: Invalid password
    ...

  @registration
  Scenario: New user signup
    ...

Run specific tagged tests:

# Run smoke tests
tkit run --tags @smoke

# Run login tests excluding negative cases
tkit run --tags "@login and not @negative"

Scenario Outline

Use Scenario Outline with Examples to run the same scenario with different data:

Scenario Outline: Login with different credentials
  Given the user goes to the "login" page
  When the user enters "<email>" into the "email" field
  And the user enters "<password>" into the "password" field
  And the user clicks the "login" button
  Then the "<result>" should be visible

  Examples:
    | email              | password  | result        |
    | valid@example.com  | correct   | dashboard     |
    | invalid@example.com| wrong     | error_message |
    | empty              | empty     | error_message |

Best Practices

1. Write Declarative Steps

Focus on what the user wants to achieve, not how they do it:

Declarative (Good):

Given the user is logged in as admin

Imperative (Avoid):

Given the user goes to the "login" page
And the user enters "admin@example.com" into the "email" field
And the user enters "adminpass" into the "password" field
And the user clicks the "login" button

Use macros to encapsulate imperative steps into declarative ones.

2. Keep Scenarios Independent

Each scenario should be self-contained and not depend on other scenarios.

3. Use Meaningful Names

Scenario names should clearly describe what is being tested:

# Good
Scenario: User receives validation error when submitting empty form

# Bad  
Scenario: Test form validation

Next Steps