Gherkin Language: Syntax, Format & Examples

What is Gherkin Language?

Gherkin is a business-readable language that helps you describe business behavior without going into implementation details. It is a domain-specific language for defining tests in Cucumber format. It uses plain language to describe use cases and lets users remove logic details from behavior tests.

The text in Gherkin acts as documentation and as the skeleton of your automated tests. The Gherkin format is based on TreeTop Grammar, which exists in more than 37 languages, so you can write Gherkin in over 37 spoken languages. The script serves two primary purposes: it documents user scenarios, and it provides the basis for writing automated BDD tests.

Why Gherkin?

Without a shared, plain-language format, business and technical teams describe requirements differently, which causes misunderstandings. Gherkin gives everyone a single, structured vocabulary that reads like ordinary English yet maps directly to executable tests.

Gherkin Syntax

Gherkin is a line-oriented language, just like YAML and Python. Each line is called a step and starts with a keyword. Tabs or spaces are used for indentation. A comment can be added anywhere but must start with a # sign. The interpreter reads each line after removing Gherkin keywords such as Given, When, and Then.

Feature: Title of the Scenario
  Given [Preconditions or Initial Context]
  When [Event or Trigger]
  Then [Expected output]

A Gherkin document has the extension .feature and is simply a test file with a descriptive extension. Cucumber reads the Gherkin document and executes a test to validate that the software behaves as the Gherkin syntax describes.

Important Terms Used in Gherkin

The main keywords are Feature, Background, Scenario, Given, When, Then, And, But, and Scenario Outline. Cucumber has no strict naming rules, but a clear naming convention helps.

Feature

The file should have the extension .feature, and each feature file should describe only one feature. The Feature keyword begins with Feature: followed by a space and the feature name.

Scenario

Each feature file may have multiple scenarios, and each scenario starts with Scenario: followed by the scenario name.

Background

The Background keyword adds context to the scenario. It can contain steps shared by every scenario; the difference is that those steps run before each scenario.

Given

The Given keyword puts the system in a known state before the user starts interacting with it. It defines the precondition or context:

Given I am on "/."

When

The When keyword defines the action performed by the user:

When I perform "Sign In."

Then

The Then keyword defines the outcome observed after the action in the When step. You should only verify noticeable changes:

Then I should see "Welcome Tom."

And & But

You may have multiple Given, When, or Then steps. The And and But keywords add extra steps for readability:

And I enter "EmailAddress" with "tomjohn@gmail.com."
But I should see "Welcome Tom."

Given, When, Then, And, and But are all test steps. The interpreter does not raise an error if you swap them, but the scenario will not read sensibly, so use each keyword for its intended purpose.

Gherkin Examples

Example 1: A login feature for a social networking site.

Feature: Login functionality of a social networking site
  Given I am a registered user
  When I enter my username
  And I enter my password
  Then I should be redirected to the home page

Gherkin analyzes each step written in the feature file, and the steps in the feature file must match those in the step definition file.

Example 2: A user authentication scenario with a Background.

Feature: User Authentication

Background:
  Given the user is already registered on the website

Scenario: Successful login
  Given the user is on the login page
  When the user inputs the correct email address
  And the user inputs the correct password
  And the user clicks the Login button
  Then the user should be authenticated
  And the user should be redirected to their dashboard

Best Practices of Using Gherkin

• Each scenario should execute separately and independently.
• Every feature should be executable on its own.
• Step information should be shown independently.
• Connect your scenarios with your requirements and track which scenarios belong to each requirement.
• Create modular, easy-to-understand steps and combine common scenarios.
• Describe what the system does, not how it does it.

Advantages of Gherkin

• Gherkin is simple enough for non-programmers to understand.
• Programmers can use it as a solid base to start their tests.
• It makes user stories easier to digest and targets business requirements.
• Business executives and developers can both read the same script.
• Gherkin test cases link acceptance tests directly to automated tests.
• The writing style makes it easier to reuse code across tests.

Disadvantages of Gherkin

• It requires a high level of business engagement and collaboration.
• It may not work well in every scenario.
• Poorly written tests can increase test-maintenance cost.

FAQs