====== Gherkin ======

**Gherkin** je doménově specifický jazyk (DSL – Domain-Specific Language) určený k popisu **chování softwarového systému** v rámci metodiky **Behavior-Driven Development** (**BDD**). Gherkin je čitelný jak pro lidi, tak pro stroje – umožňuje psát testovací scénáře v **přirozeném jazyce**, které lze následně automaticky spustit jako funkční testy (např. pomocí nástroje [[Cucumber]]).

Cílem Gherkinu je vytvořit **„živou dokumentaci“**, která je vždy aktuální, protože je součástí testovací sady.

===== Struktura dokumentu Gherkin =====

Gherkinové soubory mají příponu **.feature** a obsahují popis jedné funkcionality systému. Každý soubor se skládá z:

  * **Popisku funkce** (Feature),
  * **Jednoho nebo více scénářů** (Scenario),
  * **Kroků** (Steps), které popisují předpoklady, akce a očekávané výsledky.

===== Klíčová slova (anglická – doporučená) =====

| Klíčové slovo | Účel | Česká alternativa (lokální) |

| **Feature**   | Nadpis a popis celé funkce | **Požadavek**, **Funkce** |
| **Scenario**  | Konkrétní testovací případ | **Scénář** |
| **Given**     | Počáteční stav (předpoklady) | **Za předpokladu**, **Mám** |
| **When**      | Uživatelská akce nebo událost | **Když** |
| **Then**      | Očekávaný výsledek | **Pak** |
| **And / But** | Připojení dalšího kroku stejného typu | **A**, **Ale** |

> 💡 **Doporučení**: I když Gherkin podporuje lokalizaci (včetně češtiny), **v praxi se důrazně doporučuje používat anglická klíčová slova**, protože:
> - většina nástrojů (Cucumber, IDE pluginy) lépe podporuje angličtinu,
> - zajišťuje lepší kompatibilitu v mezinárodních týmech,
> - step definitions (implementace kroků) jsou téměř vždy v angličtině.

===== Příklad Gherkin souboru (anglicky) =====

<code gherkin>
Feature: User login

  As a registered user
  I want to log in to the system
  So that I can access my personal dashboard

  Scenario: Successful login with valid credentials
    Given the user "alice" exists with password "secret123"
    When I enter "alice" and "secret123" into the login form
    And I click the "Login" button
    Then I should be redirected to the dashboard
    And I should see a welcome message "Welcome, alice!"

  Scenario: Login fails with invalid password
    Given the user "alice" exists with password "secret123"
    When I enter "alice" and "wrongpass" into the login form
    And I click the "Login" button
    Then I should see an error message "Invalid username or password"
</code>

===== Parametry a tabulky =====

Gherkin umožňuje znovupoužití kroků pomocí **parametrů** a **datových tabulek**.

==== Parametry ve složených závorkách ====

Kroky mohou obsahovat proměnné – např. `"alice"` nebo `"secret123"` – které jsou předány do implementace kroku jako argumenty.

==== Datové tabulky (Data Tables) ====

Pro testování více vstupů ve stejném scénáři lze použít tabulky:

<code gherkin>
Scenario: Login with various invalid inputs
  Given I am on the login page
  When I try to log in with the following credentials:
    | username | password   |
    | alice    | wrong123   |
    | bob      | incorrect  |
    |          | secret123  |
  Then I should see the error message "Invalid username or password" for each attempt
</code>

==== Scénářové osnovy (Scenario Outline) + Příklady (Examples) ====

Pro spuštění stejného scénáře s různými vstupy se používá **Scenario Outline**:

<code gherkin>
Scenario Outline: Login with different valid users
  Given the user "<username>" exists with password "<password>"
  When I log in as "<username>" with password "<password>"
  Then I should be on the dashboard

  Examples:
    | username | password   |
    | alice    | secret123  |
    | bob      | mypass456  |
    | eve      | qwerty789  |
</code>

Tento scénář se spustí **třikrát** – jednou pro každý řádek v sekci **Examples**.

===== Pravidla psaní dobrých Gherkin scénářů =====

  * **Zaměř se na „co“, ne „jak“** – popisuj cíl uživatele, ne technické detaily (např. „Když přidám zboží do košíku“, ne „Když kliknu na tlačítko s ID #add-cart“).
  * **Každý scénář by měl mít jeden jasný cíl** – testuj jednu věc.
  * **Vyhněte se podmínkám** (`if`, `unless`) – raději vytvořte samostatné scénáře pro každý případ.
  * **Používej přirozený jazyk** – scénář by měl být srozumitelný i pro nevývojáře.
  * **Nepřetěžuj Gherkin technickými detaily** – ty patří do implementace kroků, nikoli do `.feature` souboru.

===== Lokalizace Gherkinu =====

Gherkin podporuje více než 70 jazyků. Pro použití češtiny stačí na začátek souboru přidat:

<code gherkin>
# language: cs

Požadavek: Přihlášení uživatele

  Scénář: Úspěšné přihlášení
    Za předpokladu, že uživatel "jan" existuje
    Když zadám "jan" a "heslo"
    Pak bych měl být přihlášen
</code>

Seznam podporovaných jazyků a klíčových slov je k dispozici na: https://cucumber.io/docs/gherkin/languages/

===== Integrace s nástroji =====

Gherkin je primárně používán s:
  * **Cucumber** (pro Ruby, Java, JavaScript, C#),
  * **SpecFlow** (.NET),
  * **Behave** nebo **pytest-bdd** (Python),
  * **Godog** (Go).

Tyto nástroje mapují jednotlivé řádky Gherkinu na **step definitions** – funkce v programovacím jazyce, které skutečně provádějí test (např. ovládají prohlížeč přes Selenium).

===== Související pojmy =====

  * [[Cucumber]]
  * [[BDD]]
  * [[Testování softwaru]]
  * [[Akcepční testování]]
  * [[Živá dokumentace]]

===== Externí odkazy =====

  * Oficiální dokumentace Gherkin: https://cucumber.io/docs/gherkin/  
  * Seznam jazyků a klíčových slov: https://cucumber.io/docs/gherkin/languages/  
  * Gherkin reference (formální syntax): https://cucumber.io/docs/gherkin/reference/

===== Viz také =====

  * [[Testovací scénář]]
  * [[Behavior-Driven Development]]
  * [[Step definition]]
  * [[Scenario Outline]]