Gherkin

Gherkin is a small, structured language for describing software behavior as examples. Each file has a .feature extension and contains one Feature made of Scenarios, and each scenario is a list of steps beginning with Given (context), When (action) and Then (expected outcome). Tools such as Cucumber match each step to a step definition in code, so the same text is both documentation and an automated test.

Example

Feature: Password reset

  Background:
    Given a registered user "ada@example.com"

  Scenario: Reset link is sent for a known email
    When she requests a password reset for "ada@example.com"
    Then a reset email is sent to "ada@example.com"
    And the link expires after 30 minutes

  Scenario Outline: Weak passwords are rejected
    When she sets her new password to "<password>"
    Then she sees the error "<message>"

    Examples:
      | password | message                       |
      | abc      | Use at least 12 characters    |
      | password | This password is too common   |

And a matching step definition in Java with Cucumber:

@When("she sets her new password to {string}")
public void setNewPassword(String password) {
    resetPage.setPassword(password);
}

Keywords worth knowing

• And / But continue the previous step type, for readability.
• Background runs before every scenario in the file. Keep it short.
• Scenario Outline with Examples runs the scenario once per table row, which is data-driven testing in Gherkin form.
• Tags such as @smoke or @wip above a scenario let you select subsets to run.
• Rule (Gherkin 6 and later) groups scenarios under the business rule they illustrate.

Writing good scenarios

• One behavior per scenario. Several When/Then pairs usually means two scenarios.
• Declarative, not imperative. “When she requests a password reset” beats three steps about typing into fields and clicking buttons.
• Concrete values. Real examples (“120.00”, “Gold”) catch misunderstandings that vague phrases (“a large order”) hide.
• Third person or consistent persona. Mixing “I”, “the user” and named personas makes the step library sprawl.