Gherkin Basics

Gherkin is the plain-English format letsrunit uses for test scenarios. Each .feature file describes one feature and one or more scenarios.

File structure

Feature: Shopping cart

  Background:
    Given I'm on page "/shop"

  Scenario: Add item to cart
    When I click button "Add to cart"
    Then The page contains text "1 item in cart"

  Scenario: Remove item from cart
    When I click button "Add to cart"
    And I click button "Remove"
    Then The page contains text "Cart is empty"

Keyword	Purpose
Feature	Names the feature being tested (one per file)
Background	Steps that run before every scenario in the file
Scenario	A single test case
Given	Sets up the initial state
When	Describes an action
Then	Asserts an outcome
And / But	Continues the previous Given, When, or Then

With and without Background

Use Background when most scenarios share the same starting point.

Feature: Dashboard

  Background:
    Given I'm on page "/login"
    When I set field "Email" to "admin@example.com"
    And I set field "Password" to "secret"
    And I click button "Sign in"

  Scenario: View user list
    When I click link "Users"
    Then The page contains text "All users"

  Scenario: View settings
    When I click link "Settings"
    Then The page contains text "Account settings"

Custom parameter types

letsrunit extends Cucumber with three parameter types used across the step library:

Type	Accepts	Example
{locator}	Any locator expression	button "Sign in", field "Email", `#submit`
{value}	String, number, date expression, or array	"hello", 42, date of tomorrow, ["A", "B"]
{keys}	Quoted key or key combination	"Enter", "Control+A", "Shift+Tab"

See Locators for the full locator syntax and Step Reference for every available step.